Ana içeriğe geç

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, Promise dö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 alana null verilir.
  • 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;
}
}
HataDurum
AuthenticationError401
ForbiddenError403
NotFoundError404
ValidationError422
RateLimitError429
UnexpectedResponseErrorDiğer kodlar (500 dahil) ya da okunamayan yanıt; error.status.
SignatureErrorYanıtın imzası tutmadı.
TransportErrorGateway'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ı timeout ve fetch; team yok) iş ortağının anahtarıyla /api/partner/ uçlarını çağırır: createTeam(), retrieveTeams() (sayfalı), updateTeamModules(), deleteTeam(). Yanıtlar Response.PartnerTeamDetails, Response.PartnerTeamList (pagination) ve Response.DeletedTeam; çalışma alanı Response.PartnerTeam (slug, name, timezone, isTest, modules, gatewayUrl, apiKey, apiSecret, createdAt). teamClient(team) açılan çalışma alanının Client'ını kurar. Bkz. İş Ortakları.
  • Yalnızca iş ortağı çalışma alanlarına açık uçlar (Client üzerinde; başka çalışma alanında ForbiddenError): retrieveProviders(), createPaymentProvider(), retrievePaymentProviders(), updatePaymentProvider(), deletePaymentProvider(), createWebhookEndpoint(), retrieveWebhookEndpoints(), updateWebhookEndpoint(), deleteWebhookEndpoint(), updateTeam(), retrieveCheckoutDesign(), updateCheckoutDesign() (logo: null ve termsUrl: null kaldırır) ve createLogo() (content bayt ya da base64 metin). Yanıtlar ProviderList, PaymentProviderDetails, PaymentProviderList, DeletedPaymentProvider, WebhookEndpointDetails, WebhookEndpointList, DeletedWebhookEndpoint, TeamDetails, CheckoutDesignDetails ve LogoDetails. 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, Subscription ve PaymentLink yanıtlarında maxInstallments (MaxInstallments ya da null). 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(); istekler Request.CreateBankAccount, Request.UpdateBankAccount, Request.DeleteBankAccount, Request.RetrieveBankAccounts, Request.RetrieveBankTransactions, yanıtlar Response.BankList, Response.BankAccountDetails, Response.BankAccountList, Response.DeletedBankAccount, Response.BankTransactionList. Bankanın reddettiği kimlik bilgisi hata fırlatmaz: result.successful false, bankAccount null. Bkz. Banka Hareketleri.
  • Sorgularda sayfalama: altı sorgu isteği page ve perPage (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ı varsa pagination toplamı gösterir, kalanını sayfa sayfa isteyin. SDK tarafında var olan kod değişmeden çalışır.

Değişenler:

  • UpdatePaymentLink.reference ve taxMode null alır: reference: null linke yeni bir LINK{n} referansı verir, taxMode: null inclusive'e döndürür. Verilmeyen alan eskisi gibi gövdeye yazılmaz.
  • Açıklama düzeltmeleri: NotFoundError yalnızca token'lı güncelleme/silme/iade/iptalde, Item.image http 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:

  • RefundStatus kaldı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.billingAddress ve createSavedCard()'ın customer.billingAddress alanı isteğe bağlıdır; adresin alanları da tek tek verilmeyebilir. regularPayment() ve securePayment()'ta customer da 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 eksikler ValidationError (422) alır. createSavedCard()'da customer.reference zorunlu kalır.
  • 403 anlatımı: ForbiddenError açı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.baseUrl açıklaması entegrasyonu https://sandbox.odemehub.com üzerinde kurar; canlıya çıkarken baseUrl https://app.odemehub.com olur. 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() ve updateSubscription() locksCustomer ve emailsCustomer alır. Response.Order ve Response.Subscription requiresShipping, locksCustomer ve emailsCustomer döner. Bkz. create-order ve E-postalar.
  • Kırıcı: ödeme linkinde emailsPayer → emailsCustomer. createPaymentLink(), updatePaymentLink() ve Response.PaymentLink'te alanın adı değişti; gateway eski emails_payer adını kabul etmez.

1.0.2'deki değişiklikler​

Eklenenler:

  • Link ödemeleri: retrieveLinkPayments() (token, LINKPAY{n} biçiminde reference ya da createdFrom / createdTo). Yanıt Response.LinkPaymentList (paid()); her Response.LinkPayment paymentLink (token, reference), kalemler, tutarlar, discount, customer, transaction ve isPaid() taşır. Yeni sabit: LinkPaymentStatus (open, paid). Bkz. retrieve-link-payments.
  • linkPaymentToken: PaymentTransaction, Transaction ve Webhook linkte alınan ödemede link ödemesinin token'ını verir.
  • Ödeme linki alanları: createPaymentLink() ve updatePaymentLink() amountType, itemName, predefinedAmounts, taxRate, taxMode, currencyType, currencies ve emailsPayer (1.0.3'te emailsCustomer oldu) alır; Response.PaymentLink aynı alanları döner. Yeni sabitler: AmountType, CurrencyType, TaxMode. Güncellemede itemName, predefinedAmounts, taxRate ve currencies null ile boşaltılabilir.
  • discount: Order, Subscription ve LinkPayment yanıtları Response.Discount (code, amount) taşır; kupon yoksa null. Webhook gövdesinde yoktur.

Küçük kırıcı değişiklikler:

  • create* her çağrıda yeni kayıt açar. createOrder(), createSubscription() ve createPaymentLink() aynı reference ile çağrılsa da yeni kayıt ve yeni token döner; önceki kayıt yeniden yazılmaz, tekrarlanan referans için ValidationError atılmaz. Yanıttaki token'ı saklayın, değişiklik için update*() kullanın. Bkz. Aynı referansla tekrarlanan create-* istekleri.
  • createPaymentLink() için items isteğe bağlıdır: yalnızca fixed tipte gerekir.
  • PaymentLink.subtotal, taxAmount ve amount artık string | null: tutarı ödeyenin belirlediği linkte null gelir (eskiden '').
  • Linkte alınan deneme: işlemin reference değeri link ödemesinin LINKPAY{n} referansıdır; linkin kendi referansıyla retrievePayments() 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-Timestamp ile, 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. Yerlerine createOrder, 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, savedCardToken parametreleri yerine her yerde token.
  • Müşteri: customer.reference yerine customer.reference; adres alanları billingAddress ve shippingAddress altında; firma bilgisi tax yerine fatura adresindeki companyTitle, taxNumber, taxOffice.
  • Yanıtlar iç içe: payment.transactionToken yerine payment.transaction.token; sipariş details.order, abonelik details.subscription, link details.paymentLink altı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 422 ile reddedilir.
  • Kanal kalktı. Options.channelToken ve isteklerdeki channelToken yoktur. Referans alanları channelReference yerine reference adını taşır (ödeme, sipariş, abonelik, link, kalem); yanıtlarda channelToken yoktur. Geri dönüşte tarayıcı channel_reference değil reference POST 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ıt NotFoundError değil boş listedir.
  • Gönderim: sipariş ve abonelik requiresShipping ile ö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: taxRate isteğe bağlı; yeni saveAsProduct.
  • Müşteri: referans gönderilmeyebilir; o zaman müşteri kaydedilmez ve kart saklanamaz. Abonelikte ve kart saklamada zorunludur. reference ve billingAddress null olabilir.
  • Ödeme linki: son 50 deneme ve transactionsCount retrievePaymentLinks yanıtında her PaymentLink üzerindedir; PaymentLinkDetails yalnızca linki taşır.
  • Kayıtlı kart: listede her kart kendi customer'ını taşır; SavedCardList.customer kalktı. Listelenen ödemede savedCard, 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.