Ziraat Bankası

Ziraat Bankası uses NestPay/CC5 (same Asseco platform as İş Bankası) with HMAC-SHA512 v3 hash authentication. 3D Secure is delivered as an auto-submitting form in 3d_pay_hosting mode.

Getting your credentials

NestPay credentials come from your Ziraat Bankası member-merchant agreement (issued via the bank's VPOS management portal) — they are not self-service. Obtain from the bank or your integrator:

• clientId — your NestPay client/merchant id
• username, password — the API user
• storeKey — key used for the v3 hash

Request a test set for integration and a separate production set for go-live.

Configuration

ziraat: {
  enabled: true,
  config: {
    clientId: process.env.ZIRAAT_CLIENT_ID!,
    username: process.env.ZIRAAT_USERNAME!,
    password: process.env.ZIRAAT_PASSWORD!,
    storeKey: process.env.ZIRAAT_STORE_KEY!,
  },
}

baseUrl defaults to https://preprod.ziraatpay.com.tr in sandbox and https://sanalpos2.ziraatbank.com.tr in production.

3D Secure

const init = await payment.ziraat.initThreeDSPayment({
  price: '75.00',
  currency: 'TRY',
  callbackUrl: 'https://yoursite.com/ziraat/callback',
  paymentCard: { cardHolderName, cardNumber, expireMonth, expireYear, cvc },
  buyer: { /* … */ },
  basketId: 'order-1',
  /* … */
});

const final = await payment.ziraat.completeThreeDSPayment(req.body);

Refund / Cancel / Get

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

Testing

Set mode: 'sandbox' and use the bank's test credentials; baseUrl switches to https://preprod.ziraatpay.com.tr automatically. Run a 3D Secure flow with a NestPay test card from the bank's integration guide and confirm completeThreeDSPayment returns success only after the response hash verifies.