Banks
Akbank
Akbank Sanal POS (JSON API) integration reference.
Uses Akbank's Sanal POS JSON API. Every request carries an auth-hash header
(base64(HMAC-SHA512(body, secretKey))).
Configuration
akbank: {
enabled: true,
config: {
merchantSafeId: process.env.AKBANK_MERCHANT_SAFE_ID!,
terminalSafeId: process.env.AKBANK_TERMINAL_SAFE_ID!,
secretKey: process.env.AKBANK_SECRET_KEY!,
// subMerchantId?: string
// testMode: defaults to mode === 'sandbox' (test 3D gateway)
// baseUrl: defaults from mode (apipre.akbank.com / api.akbank.com)
},
}paymentId is your order id: the conversationId you pass, or a generated id.
Direct Payment (non-3D)
const result = await payment.akbank.createPayment({ ...paymentRequest, conversationId: 'ORDER123' });
// txnCode 1000; success when responseCode is VPS-00003D Secure (3D_PAY)
const init = await payment.akbank.initThreeDSPayment({
...paymentRequest,
conversationId: 'ORDER123',
callbackUrl: 'https://yoursite.com/api/pay/akbank/payment/complete-3ds',
});
// init.threeDSHtmlContent auto-submits a signed form to the Akbank securepay gatewayAkbank authenticates the card, charges it, and POSTs the signed result to callbackUrl:
const result = await payment.akbank.completeThreeDSPayment(callbackBody);The result is trusted only if:
- the HMAC
hashover the fields inhashParamsis valid, and coversresponseCode,orderId,merchantSafeIdandterminalSafeId; - the terminal ids match your configuration.
It is success only when responseCode is VPS-0000. A missing result code is
never treated as success.
Refund, Cancel & Status
await payment.akbank.refund({ paymentId: 'ORDER123', price: '50.00', currency: 'TRY', ip: '1.2.3.4' }); // 1002
await payment.akbank.cancel({ paymentId: 'ORDER123', ip: '1.2.3.4' }); // 1003
const status = await payment.akbank.getPayment('ORDER123'); // 1010
// status: 'success' (N), 'cancelled' (V/R), 'failure'BIN and installment queries are not supported for Akbank; binCheck() and installmentInfo() throw.