Node.js SDK

Kurulum

Node.js 18 ve üzeri gerekir. TypeScript tipleri pakettedir.

npm install @odemehub/node-sdk

İstemci

import { Client } from '@odemehub/node-sdk';

const client = new Client({
    baseUrl: 'https://odeme.gurmehub.com',
    team: process.env.ODEMEHUB_TEAM!,                  // Çalışma Alanı Kimliği
    channelToken: process.env.ODEMEHUB_CHANNEL_TOKEN!,
    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
});

Bütün metotlar Promise döner (subscriptionWebhook hariç). İstekler düz nesnedir; tipleri Request ad alanındadır. Yanıtlar Response ad alanındaki sınıflardır.

Müşteri ve kart

const customer = {
    channelReference: 'musteri-88',
    firstname: 'Ahmet',
    lastname: 'Yılmaz',
    email: '[email protected]',
    phone: '05551112233',
    address: 'Kızılırmak Mah. Dumlupınar Blv. No:3',
    district: 'Çankaya',
    province: 'Ankara',
    country: 'Türkiye',
    // tax: { companyTitle: '...', taxNumber: '...', taxOffice: '...' },
};

const card = {
    holderName: 'AHMET YILMAZ',
    number: '5400360000000003',
    securityCode: '000',
    expiryMonth: '12',
    expiryYear: '2030',
    // shouldSave: true,
};

Regular ödeme

const payment = await client.regularPayment({
    channelReference: 'SIP-10231',
    amount: '450.00',
    installmentNumber: 1,
    ip: req.ip,
    customer,
    card,
});

payment.result.successful;  // boolean
payment.result.message;     // string | null
payment.transactionToken;   // string
payment.conversion;         // Conversion | null
payment.savedCard;          // SavedCard | null

Bir ödemede card ile savedCardToken alanlarından tam olarak biri verilmelidir; aksi hâlde istemci istek göndermeden TypeError atar.

3D Secure ödeme

const payment = await client.securePayment({
    channelReference: 'SIP-10232',
    amount: '450.00',
    installmentNumber: 1,
    ip: req.ip,
    callbackUrl: 'https://magazam.com/odeme/donus',
    customer,
    card,
});

if (payment.result.successful) {
    res.redirect(payment.redirectUrl!);
}

callbackUrl işleyicisi (form gövdesi):

app.post('/odeme/donus', express.urlencoded({ extended: false }), async (req, res) => {
    const outcome = await client.retrievePayment({ transactionToken: req.body.transaction_token });

    if (outcome.result.successful) {
        // ödendi
    }
});

Akış: Secure (3D) Ödeme.

Ödeme sorgusu

const payment = await client.retrievePayment({ transactionToken });

İade ve iptal

const cancel = await client.cancelPayment({ transactionToken });
const refund = await client.refundPayment({ transactionToken, amount: '100.00' });

refund.type;    // 'refund' | 'cancel'
refund.amount;  // geri verilen tutar

Diğer uçlar

Metot	İstek alanları
orderPayment	channelReference, successUrl, customer, items[], cancelUrl?, description?, currency?, paymentProviderToken?
subscriptionPayment	channelReference, items[], successUrl, customer, cancelUrl?, webhookUrl?, paymentProviderToken?
retrieveSubscription / cancelSubscription	subscriptionToken
retrieveBin	bin, amount, paymentProviderToken?, currency?
saveProduct	channelReference, name, type, amount, taxRate, period?, currency?, isActive?
saveCard	customer, card (securityCode isteğe bağlı), paymentProviderToken?
savedCards	customer: { channelReference }
defaultSavedCard / deleteSavedCard	customer: { channelReference }, savedCardToken

Kanal alanı olan isteklerde channelToken verilerek istemcinin kanalı istek bazında değiştirilebilir. Örnekler her uç sayfasının SDK örnekleri bölümündedir.

Hata yönetimi

import {
    AuthenticationError, OdemehubError, SignatureError,
    TransportError, UnexpectedResponseError, ValidationError,
} from '@odemehub/node-sdk';

try {
    await client.regularPayment(request);
} catch (error) {
    if (error instanceof ValidationError) {
        error.errors;   // { 'transaction.amount': ['...'] }
    } else if (error instanceof AuthenticationError) {
        // 401
    } else if (error instanceof UnexpectedResponseError) {
        error.status;   // ör. 403
    } else if (error instanceof SignatureError) {
        // yanıtın imzası tutmadı
    } else if (error instanceof TransportError) {
        // gateway'e ulaşılamadı; sonuç bilinmiyor
    } else {
        throw error;
    }
}

Abonelik webhook'u

Gövde ham okunmalıdır (express.raw); express.json() imzayı bozar.

import express from 'express';
import { SignatureError } from '@odemehub/node-sdk';

app.post('/odemehub/abonelik', express.raw({ type: 'application/json' }), (req, res) => {
    let webhook;

    try {
        webhook = client.subscriptionWebhook(req.body, req.get('X-Signature'));
    } catch (error) {
        if (error instanceof SignatureError) {
            return res.sendStatus(400);
        }
        throw error;
    }

    if (webhook.isActive()) { /* webhook.subscription.endsAt */ }
    if (webhook.isPastDue()) { /* webhook.subscription.checkoutUrl */ }
    if (webhook.isCancelled()) { /* ... */ }
    if (webhook.isEnded()) { /* ... */ }

    res.sendStatus(200);
});

Ayrıntılar: Abonelik Webhook'u.