Node.js SDK
Kurulum
Node.js 18 ve üzeri gerekir. Çalışma zamanı bağımlılığı yoktur; TypeScript tipleri pakettedir.
npm install @odemehub/node-sdk
Bu sayfa 1.0.8 sürümünü anlatır. Önceki sürümlerden geçiş için: 1.0.8, 1.0.7, 1.0.6, 1.0.5, 1.0.4, 1.0.3, 1.0.2. 1.0.0 bugünkü gateway'le çalışmaz; geçiş için: 1.0.1'deki kırıcı değişiklikler.
İstemci
import { Client } from '@odemehub/node-sdk';
const client = new Client({
baseUrl: 'https://sandbox.odemehub.com',
team: process.env.ODEMEHUB_TEAM!, // Çalışma Alanı Kimliği
apiKey: process.env.ODEMEHUB_API_KEY!,
apiSecret: process.env.ODEMEHUB_API_SECRET!,
// timeout: 60_000, // milisaniye, varsayılan 60000
// fetch: customFetch // varsayılan globalThis.fetch
});
- Her uç için uçla aynı adı taşıyan,
Promisedöndüren bir metot vardır:create-order→createOrder(). Liste: SDK'lar. - İstekler düz nesnedir; verilmeyen isteğe bağlı alan gövdeye yazılmaz.
update*isteklerinde bir alanı boşaltmak için alananullverilir. - Yanıtlar API JSON'unu birebir izler (
payment.transaction.token,details.order.checkoutUrl). Sabit kümeli alanlar string-literal tiplerdir; SDK'nın bilmediği bir değer metin olarak gelir. - Tek bir kaydı adlandıran istek alanı her zaman
token'dır.
Müşteri ve kart
import type { Request } from '@odemehub/node-sdk';
const billingAddress = {
firstname: 'Ahmet',
lastname: 'Yılmaz',
phone: '05551112233',
address: 'Kızılırmak Mah. Dumlupınar Blv. No:3',
district: 'Çankaya',
province: 'Ankara',
country: 'TR',
// companyTitle, taxNumber, taxOffice: üçü birlikte
};
const customer: Request.PaymentCustomer = { reference: 'musteri-88', billingAddress };
const card = {
holderName: 'AHMET YILMAZ',
number: '5400360000000003',
securityCode: '000',
expiryMonth: '12',
expiryYear: '2030',
shouldSave: false,
};
Ödeme ve kart saklama istekleri Request.PaymentCustomer alır; gönderim adresi yoktur. Fatura adresi zorunludur; Varsayılan Ödeyen açıksa billingAddress'i ya da alanlarından bazılarını vermeyebilirsiniz, eksikler varsayılan ödeyenden tamamlanır. Ödemede customer da verilmeyebilir; createSavedCard()'da customer.reference yine zorunludur. Sipariş ve abonelikte customer Request.Customer tipindedir; orada billingAddress ve shippingAddress isteğe bağlıdır.
Regular ödeme
const payment = await client.regularPayment({
reference: 'SIP-10231',
amount: '450.00',
installmentNumber: 1,
ip: req.ip,
customer,
card,
});
if (payment.result.successful) {
payment.transaction.token; // iade, iptal ve sorgu için
payment.transaction.paymentStatus; // 'paid'
}
3D Secure ödeme
const payment = await client.securePayment({
reference: 'SIP-10231',
amount: '450.00',
installmentNumber: 1,
ip: req.ip,
callbackUrl: 'https://magazam.com/odeme/donus',
customer,
card,
});
if (payment.redirectUrl !== null) {
res.redirect(payment.redirectUrl);
}
// callback_url işleyicisinde:
const [outcome] = (await client.retrievePayments({ token: req.body.transaction_token })).payments;
outcome?.isSuccessful();
Sipariş, ödeme linki, abonelik, kayıtlı kart
const created = await client.createOrder({
reference: 'SIP-10233',
successUrl: 'https://magazam.com/tesekkurler',
items: [{ name: 'Kahve makinesi', unitAmount: '450.00', quantity: 1, taxRate: '20' }],
customer: { reference: 'musteri-88', billingAddress },
requiresShipping: true, // ödeme sayfasında gönderim yöntemi seçilir, ücreti tutara eklenir
locksCustomer: true, // müşteri bilgisi sorulmaz, gönderildiği gibi gösterilir
emailsCustomer: true, // ödeme tamamlanınca fatura adresindeki e-postaya yazılır
maxInstallments: { individual: 1, commercial: 3 }, // bireysel kartta tek çekim, ticari kartta en çok 3 taksit
});
res.redirect(created.order.checkoutUrl!);
locksCustomer: true eksiksiz fatura adresi ister; requiresShipping de açıksa gönderim adresi shippingAddress'ten, verilmezse fatura adresinden alınır. Aynı üç alan updateOrder(), createSubscription() ve updateSubscription()'da da vardır; Response.Order ve Response.Subscription üçünü de döner. Ödeme linkinde yalnızca emailsCustomer vardır ve e-posta, ödeyenin ödeme sayfasında verdiği adrese gider.
Diğer örnekler uç sayfalarındadır: create-order, create-payment-link, retrieve-link-payments, create-subscription, create-saved-card ve rehberler.
İade ve iptal
const refund = await client.refundPayment({ token: transactionToken, amount: '100.00' });
refund.refund?.amount;
await client.cancelPayment({ token: transactionToken });
Hata yönetimi
Gateway isteği reddederse hata fırlatılır; reddedilen ödeme, iade ya da kart saklama hata değildir (result.successful false).
import {
AuthenticationError, ForbiddenError, NotFoundError, OdemehubError, RateLimitError,
SignatureError, TransportError, UnexpectedResponseError, ValidationError,
} from '@odemehub/node-sdk';
try {
await client.regularPayment(payment);
} catch (error) {
if (error instanceof ValidationError) {
error.errors['transaction.amount']?.[0]; // 422
} else if (error instanceof RateLimitError) {
error.retryAfter; // 429; beklenecek saniye (Retry-After)
} else if (error instanceof NotFoundError) {
// 404
} else if (error instanceof OdemehubError) {
error.message; // Türkçe
} else {
throw error;
}
}
| Hata | Durum |
|---|---|
AuthenticationError | 401 |
ForbiddenError | 403 |
NotFoundError | 404 |
ValidationError | 422 |
RateLimitError | 429 |
UnexpectedResponseError | Diğer kodlar (500 dahil) ya da okunamayan yanıt; error.status. |
SignatureError | Yanıtın imzası tutmadı. |
TransportError | Gateway'e ulaşılamadı; sonuç bilinmiyor. |
Bkz. Hatalar.
1.0.8'deki değişiklikler
Eklenenler:
- İş ortağı istemcisi:
PartnerClient(PartnerOptions:baseUrl,apiKey,apiSecret, isteğe bağlıtimeoutvefetch;teamyok) iş ortağının anahtarıyla/api/partner/uçlarını çağırır:createTeam(),retrieveTeams()(sayfalı),updateTeamModules(),deleteTeam(). YanıtlarResponse.PartnerTeamDetails,Response.PartnerTeamList(pagination) veResponse.DeletedTeam; çalışma alanıResponse.PartnerTeam(slug,name,timezone,isTest,modules,gatewayUrl,apiKey,apiSecret,createdAt).teamClient(team)açılan çalışma alanınınClient'ını kurar. Bkz. İş Ortakları. - Yalnızca iş ortağı çalışma alanlarına açık uçlar (
Clientüzerinde; başka çalışma alanındaForbiddenError):retrieveProviders(),createPaymentProvider(),retrievePaymentProviders(),updatePaymentProvider(),deletePaymentProvider(),createWebhookEndpoint(),retrieveWebhookEndpoints(),updateWebhookEndpoint(),deleteWebhookEndpoint(),updateTeam(),retrieveCheckoutDesign(),updateCheckoutDesign()(logo: nullvetermsUrl: nullkaldırır) vecreateLogo()(contentbayt ya da base64 metin). YanıtlarProviderList,PaymentProviderDetails,PaymentProviderList,DeletedPaymentProvider,WebhookEndpointDetails,WebhookEndpointList,DeletedWebhookEndpoint,TeamDetails,CheckoutDesignDetailsveLogoDetails. Bkz. yalnızca iş ortağı çalışma alanlarına açık uçlar.
Kırıcı değişiklik yok.
1.0.7'deki değişiklikler
Eklenenler:
- Taksit sınırı:
maxInstallments({ individual, commercial }) sipariş, abonelik ve ödeme linki oluşturma/güncelleme isteklerinde;Order,SubscriptionvePaymentLinkyanıtlarındamaxInstallments(MaxInstallmentsya danull). Güncellemede{ individual: null, commercial: null }sınırı kaldırır. Bkz. Taksit sınırı.
1.0.6'daki değişiklikler
Eklenenler:
- Banka hareketleri:
retrieveBanks(),createBankAccount(),retrieveBankAccounts(),updateBankAccount(),deleteBankAccount(),retrieveBankTransactions(); isteklerRequest.CreateBankAccount,Request.UpdateBankAccount,Request.DeleteBankAccount,Request.RetrieveBankAccounts,Request.RetrieveBankTransactions, yanıtlarResponse.BankList,Response.BankAccountDetails,Response.BankAccountList,Response.DeletedBankAccount,Response.BankTransactionList. Bankanın reddettiği kimlik bilgisi hata fırlatmaz:result.successfulfalse,bankAccountnull. Bkz. Banka Hareketleri. - Sorgularda sayfalama: altı sorgu isteği
pageveperPage(1–250) alır; liste yanıtlarıpagination(Response.Pagination,hasMorePages()) taşır. Sayfalama. Gateway'de davranış değişikliği: sayfa istemeyen sorgu artık bütün kayıtları değil ilk 250'yi döner; daha fazlası varsapaginationtoplamı gösterir, kalanını sayfa sayfa isteyin. SDK tarafında var olan kod değişmeden çalışır.
Değişenler:
UpdatePaymentLink.referencevetaxModenullalır:reference: nulllinke yeni birLINK{n}referansı verir,taxMode: nullinclusive'e döndürür. Verilmeyen alan eskisi gibi gövdeye yazılmaz.- Açıklama düzeltmeleri:
NotFoundErroryalnızca token'lı güncelleme/silme/iade/iptalde,Item.imagehttp ya da https, dönüş adresleri (canlıda herkese açık https, sandbox'ta localhost dahil), en çok 100 kalem.
Kırıcı değişiklik:
RefundStatuskaldırıldı; gateway iade durumu döndürmediği için hiçbir yanıtta kullanılmıyordu. Bu enum'u kullanan kod derlenmez; kullanımı silin.
1.0.5'teki değişiklikler
- Varsayılan Ödeyen: fatura adresi isteğe bağlı.
Request.PaymentCustomer.billingAddressvecreateSavedCard()'ıncustomer.billingAddressalanı isteğe bağlıdır; adresin alanları da tek tek verilmeyebilir.regularPayment()vesecurePayment()'tacustomerda isteğe bağlıdır. Verilmeyen alan gövdeye yazılmaz. Varsayılan Ödeyen açıksa eksikler varsayılan ödeyenden tamamlanır; kapalıyken sekiz kişi alanı yine zorunludur ve eksiklerValidationError(422) alır.createSavedCard()'dacustomer.referencezorunlu kalır. 403anlatımı:ForbiddenErroraçıklaması ve README'deki hata tablosu iki nedeni anlatır: çalışma alanının ödenmemiş bakiyesi ya da ucun modülünün kapalı olması. Kod değişmedi; bkz.403.
Kırıcı değişiklik yoktur; 1.0.4 kodu değişmeden derlenir ve çalışır.
1.0.4'teki değişiklikler
- Sandbox'la başlayan kurulum: README ve
Options.baseUrlaçıklaması entegrasyonuhttps://sandbox.odemehub.comüzerinde kurar; canlıya çıkarkenbaseUrlhttps://app.odemehub.comolur. Bkz. Ortamlar ve Adresler. - Webhook anlatımı: README menüyü (Ödeme Ayarları → Webhook), bir adrese birden çok olay bağlanmasını ve olaydan 30 saniye sonraki ilk gönderimi anlatır. Bkz. Webhook.
Kodda davranış değişikliği yoktur. Ödeme ve kart saklama isteklerinin müşterisi Node.js SDK'da zaten ayrı bir tiptir (PaymentCustomer); PHP, Python ve Java 1.0.4'te aynı ayrıma geçti.
1.0.3'teki değişiklikler
- Müşteri kilidi ve müşteriye e-posta:
createOrder(),updateOrder(),createSubscription()veupdateSubscription()locksCustomerveemailsCustomeralır.Response.OrderveResponse.SubscriptionrequiresShipping,locksCustomerveemailsCustomerdöner. Bkz.create-orderve E-postalar. - Kırıcı: ödeme linkinde
emailsPayer→emailsCustomer.createPaymentLink(),updatePaymentLink()veResponse.PaymentLink'te alanın adı değişti; gateway eskiemails_payeradını kabul etmez.
1.0.2'deki değişiklikler
Eklenenler:
- Link ödemeleri:
retrieveLinkPayments()(token,LINKPAY{n}biçimindereferenceya dacreatedFrom/createdTo). YanıtResponse.LinkPaymentList(paid()); herResponse.LinkPaymentpaymentLink(token,reference), kalemler, tutarlar,discount,customer,transactionveisPaid()taşır. Yeni sabit:LinkPaymentStatus(open,paid). Bkz.retrieve-link-payments. linkPaymentToken:PaymentTransaction,TransactionveWebhooklinkte alınan ödemede link ödemesinin token'ını verir.- Ödeme linki alanları:
createPaymentLink()veupdatePaymentLink()amountType,itemName,predefinedAmounts,taxRate,taxMode,currencyType,currenciesveemailsPayer(1.0.3'teemailsCustomeroldu) alır;Response.PaymentLinkaynı alanları döner. Yeni sabitler:AmountType,CurrencyType,TaxMode. GüncellemedeitemName,predefinedAmounts,taxRatevecurrenciesnullile boşaltılabilir. discount:Order,SubscriptionveLinkPaymentyanıtlarıResponse.Discount(code,amount) taşır; kupon yoksanull. Webhook gövdesinde yoktur.
Küçük kırıcı değişiklikler:
create*her çağrıda yeni kayıt açar.createOrder(),createSubscription()vecreatePaymentLink()aynıreferenceile çağrılsa da yeni kayıt ve yeni token döner; önceki kayıt yeniden yazılmaz, tekrarlanan referans içinValidationErroratılmaz. Yanıttaki token'ı saklayın, değişiklik içinupdate*()kullanın. Bkz. Aynı referansla tekrarlanancreate-*istekleri.createPaymentLink()içinitemsisteğe bağlıdır: yalnızcafixedtipte gerekir.PaymentLink.subtotal,taxAmountveamountartıkstring | null: tutarı ödeyenin belirlediği linktenullgelir (eskiden'').- Linkte alınan deneme: işlemin
referencedeğeri link ödemesininLINKPAY{n}referansıdır; linkin kendi referansıylaretrievePayments()linkin denemelerini getirmez.
1.0.1'deki kırıcı değişiklikler
1.0.1, SDK'yı geçidin bugünkü API'sine taşır ve 1.0.0 koduyla uyumlu değildir. 1.0.0'dan geçerken dikkat edilecekler:
- İmza: İstekler ve yanıtlar
X-Timestampile, zaman damgası, metot, yol ve gövde üzerinden imzalanır. 1.0.0 bugünkü gateway'le konuşamaz. - Kaldırılan metotlar:
orderPayment,subscriptionPayment,saveProduct,cancelSubscription,retrieveTransactions,saveCard,savedCards,defaultSavedCard. YerlerinecreateOrder,createSubscription,updateSubscription({ status: 'cancelled' }),retrievePayments,createSavedCard,retrieveSavedCards,updateSavedCard. Ürün kataloğu yoktur; kalemler adı ve fiyatıyla gönderilir. - Yeni metotlar: ödeme linki uçları, bütün güncelleme uçları ve her kaynakta tek
retrieve*sorgusu. - Token:
transactionToken,orderToken,subscriptionToken,paymentLinkToken,savedCardTokenparametreleri yerine her yerdetoken. - Müşteri:
customer.referenceyerinecustomer.reference; adres alanlarıbillingAddressveshippingAddressaltında; firma bilgisitaxyerine fatura adresindekicompanyTitle,taxNumber,taxOffice. - Yanıtlar iç içe:
payment.transactionTokenyerinepayment.transaction.token; siparişdetails.order, abonelikdetails.subscription, linkdetails.paymentLinkaltında. - Hatalar: güncellenen, silinen, iade ya da iptal edilen kaydın token'ı bulunamazsa
NotFoundError(404) atılır; eskiden bu durum 422 dönüyordu. Sorgular bulunamayan kayıtta boş liste döner. Yeni istisnalar:ForbiddenError(403),NotFoundError(404),RateLimitError(429,retryAfter). - İstemci tarafı denetim yok: Kart ile kayıtlı kartın birlikte verilmesi gibi durumlar gateway'de
422ile reddedilir. - Kanal kalktı.
Options.channelTokenve isteklerdekichannelTokenyoktur. Referans alanlarıchannelReferenceyerinereferenceadını taşır (ödeme, sipariş, abonelik, link, kalem); yanıtlardachannelTokenyoktur. Geri dönüşte tarayıcıchannel_referencedeğilreferencePOST eder. - Sorgular tek uçta. Her kaynakta tek sorgu metodu vardır:
retrievePayments,retrieveOrders,retrieveSubscriptions,retrievePaymentLinks,retrieveSavedCards. İstek{ token },{ reference }(kartta{ customerReference }),{ createdFrom, createdTo }ya da boş nesnedir; yanıt her zaman listedir, bulunamayan kayıtNotFoundErrordeğil boş listedir. - Gönderim: sipariş ve abonelik
requiresShippingile ödeme sayfasında gönderim adresi ister; gönderim yöntemleri panelde tanımlanır, istekte gönderilmez. Yanıtta yalnızca ödeyenin seçtiği yöntem (shippingMethod:reference,title,amount,taxRate) gelir. - Kalemler:
taxRateisteğe bağlı; yenisaveAsProduct. - Müşteri: referans gönderilmeyebilir; o zaman müşteri kaydedilmez ve kart saklanamaz. Abonelikte ve kart saklamada zorunludur.
referencevebillingAddressnullolabilir. - Ödeme linki: son 50 deneme ve
transactionsCountretrievePaymentLinksyanıtında herPaymentLinküzerindedir;PaymentLinkDetailsyalnızca linki taşır. - Kayıtlı kart: listede her kart kendi
customer'ını taşır;SavedCardList.customerkalktı. Listelenen ödemedesavedCard, kartın saklanması istendiyse saklanan kartı verir.
Webhook'lar
Tek okuyucu vardır: webhook(method, path, body, timestamp, signature) imzayı (X-Timestamp + X-Signature) doğrular ve Response.Webhook döner. Nesne yalnızca token taşır: orderToken, paymentLinkToken, linkPaymentToken, subscriptionToken, transactionToken. Kararı bu token'larla çağırdığınız retrieve yanıtına göre verin. Yalnızca imzayı doğrulamak için verifyWebhook() kullanılır.
Olaylar, adres tanımlama ve her dildeki örnek işleyici: Webhook.