Akbank Sanal POS is integrated over Akbank's VPOS API. Authentication is store-key based: requests are signed with a hash derived from your storeKey (and secure3DStoreKey for the 3-D flow) — there is no OAuth token to manage. Both direct (2D) and 3D Secure payments are supported.

Getting your credentials

Akbank issues VPOS credentials through your member-merchant (üye işyeri) agreement — they are not self-service. Obtain them from the Akbank merchant onboarding/VPOS team (or your integrator):

merchantId — your Akbank merchant number
terminalId — the terminal assigned to the merchant
storeKey — the store key used to sign API requests
secure3DStoreKey (optional) — separate key for the 3-D Secure hash, if your terminal uses one

Ask Akbank for test/sandbox credentials for integration and a separate production set for go-live.

Configuration

akbank: {
  enabled: true,
  config: {
    apiKey: process.env.AKBANK_API_KEY ?? '',     // carried for shape; not used for auth
    secretKey: process.env.AKBANK_SECRET_KEY ?? '', // carried for shape; not used for auth
    merchantId: process.env.AKBANK_MERCHANT_ID!,
    terminalId: process.env.AKBANK_TERMINAL_ID!,
    storeKey: process.env.AKBANK_STORE_KEY!,
    secure3DStoreKey: process.env.AKBANK_3D_STORE_KEY, // optional
    testMode: true, // optional; defaults true
  },
}

baseUrl defaults to https://entegrasyon.akbank.com (sandbox mode) or https://apiprod.akbank.com (production mode).

Direct Payment (2D)

const result = await payment.akbank.createPayment({
  price: '100.00',
  paidPrice: '100.00',
  currency: 'TRY',
  basketId: 'order-1',
  paymentCard: { cardHolderName, cardNumber, expireMonth, expireYear, cvc },
  buyer: { id, name, surname, email, ip, /* … */ },
  basketItems: [{ id, name, category1, itemType: 'PHYSICAL', price: '100.00' }],
});

3D Secure

const init = await payment.akbank.initThreeDSPayment({
  ...paymentRequest,
  callbackUrl: 'https://yoursite.com/akbank/callback',
});

if (init.status === 'pending' && init.threeDSHtmlContent) {
  // Render init.threeDSHtmlContent — it posts the buyer to the bank's 3-D page.
}

// On the callback, pass the bank's posted fields straight back. The response
// hash is verified before the result is trusted.
const result = await payment.akbank.completeThreeDSPayment(req.body);
// result.status === 'success' on a verified, paid order

Refund / Cancel / Get

await payment.akbank.refund({ paymentId, price: '50.00', currency: 'TRY', ip: '…' });
await payment.akbank.cancel({ paymentId, ip: '…' });
await payment.akbank.getPayment(paymentId);

BIN check & installments

Akbank also exposes card-BIN lookup and installment queries:

await payment.akbank.binCheck('454671');
await payment.akbank.installmentInfo({ binNumber: '454671', price: '100.00' });

Testing

Use the test credentials Akbank provides and keep testMode: true (the default), which keeps baseUrl on the sandbox host. Run a 3D Secure init, complete the bank's 3-D page with a test card from Akbank's integration guide, and confirm completeThreeDSPayment returns success only after the response hash verifies.

Akbank