Server-to-Server Payments

Use the S2S integration when your server owns the checkout flow and sends payment details directly to BXNK.

All Product API endpoints are served under /product-apis. Except for token creation, requests require Authorization: Bearer <accessToken>.

Crypto S2S payments creates a vault deposit address for every request.

Base URL

Sandbox: https://sandbox-api.bxnk.com/

Your live base URL is available in the Partner Portal under API Keys — it's listed at the bottom of the page.

Authentication

Generates a short-lived Product API bearer token from an API access key and secret.

POST /product-apis/auth/token
Content-Type: application/json

Parameters

Request

{
  "accessKey": "test_pk_1234567890",
  "secret": "test_sk_1234567890"
}

Response 201

{
  "message": "Product API token generated successfully",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresAt": "2026-03-24T10:00:00.000Z"
  }
}

Errors

Create a Payment

Creates a payment for the authenticated MID. Omit useHostedPaymentPage or set it to false for S2S.

POST /product-apis/payments
Authorization: Bearer <accessToken>
Content-Type: application/json
Idempotency-Key: order-1001-create

Idempotency-Key is optional for crypto S2S payments, reused only to deduplicate retries with the same request body. It is required for S2S card payments — the request is rejected with 400 if it's missing.

Parameters

Card Request

Send raw card details in metadata to process the payment through BXNK's card provider. redirectUrl and the Idempotency-Key header are required for this path. Without any card fields in metadata, TEST-mode requests instead resolve via the sandbox simulator (see Sandbox Scenarios).

{
  "amount": 10.0,
  "currency": "EUR",
  "paymentMethod": "card",
  "useHostedPaymentPage": false,
  "orderReference": "ORD-S2S-002-PSP",
  "customerReference": "CUST-002",
  "redirectUrl": "<your_redirect_url>",
  "metadata": {
    "paymentBrand": "VISA",
    "attemptThreeD": "Only3D",
    "cardNumber": "<cardnumber_without_space>",
    "expiryMonth": "MM",
    "expiryYear": "YYYY",
    "cvv": "<cvv>",
    "cardHolder": "John Doe",
    "customerName": "John Doe",
    "customerEmail": "[email protected]",
    "customerPhoneCountryCode": "+91",
    "customerPhone": "<mobile_number>",
    "customerIp": "<customer_ip>",
    "shippingCountry": "DE",
    "shippingCity": "Berlin",
    "shippingState": "DE",
    "shippingPostcode": "123456",
    "shippingStreet1": "<address>"
  }
}

The card scheme is inferred from the card number (Visa numbers starting with 4, Mastercard ranges 51–55 and 2221–2720); if it can't be inferred, metadata.paymentBrand is used as a fallback, and otherwise the request fails with 400 for an unsupported scheme.

Card Response 201 (with 3DS redirect)

{
  "message": "Payment created successfully",
  "data": {
    "paymentId": "PAY-a1b2c3d4e5f6",
    "status": "processing",
    "amount": 150.50,
    "currency": "EUR",
    "paymentMethod": "card",
    "paymentFlow": "S2S",
    "orderReference": "ORDER-1234",
    "customerReference": "CUST-2002",
    "hostedPaymentUrl": null,
    "expiresAt": null,
    "instructions": {
      "type": "xoala_3ds_redirect",
      "redirect": {
        "url": "https://secure-checkout-sandbox.xoala.com/3ds/challenge",
        "method": "POST",
        "parameters": [
          { "name": "PaReq", "value": "eJxVUsFuwjAM..." },
          { "name": "TermUrl", "value": "https://api.bxnk.example/..." }
        ]
      }
    },
    "transactionId": null,
    "mId": "MID-ABCDEFGHIJ",
    "walletAddress": null,
    "qrCodeUrl": null,
    "customerName": null,
    "customerEmail": "[email protected]",
    "customerWallet": null,
    "createdAt": "2026-03-20T10:05:00.000Z",
    "successUrl": null,
    "failureUrl": null,
    "redirectUrl": "https://merchant.example/payment/redirect",
    "declineReason": null
  }
}

For 3DS flow please follow the process as described below:

Forward the customer's browser to instructions.redirect.url using instructions.redirect.method, submitting instructions.redirect.parameters as form fields for POST redirects. After the challenge completes, BXNK finalizes the payment and redirects the browser on to redirectUrl. Poll GET /product-apis/payments/{paymentId} or listen for webhooks to get the final status — do not infer success from the redirect alone.

If the card provider approves the payment without a challenge, instructions is null and status reflects the outcome directly (completed or failed) instead of processing.

Errors specific to the card provider path

Crypto Request

Crypto payments require both metadata.asset and metadata.network. The PSP must have a settlement wallet configured for the requested asset, and the requested amount must convert to at least the configured USD minimum for that currency.

{
  "amount": 500,
  "currency": "USDT",
  "paymentMethod": "crypto",
  "metadata": {
    "m_id": "MID-ABCDEFGHIJ",
    "asset": "USDT",
    "network": "ethereum"
  }
}

Crypto Response 201

{
  "message": "Payment created successfully",
  "data": {
    "paymentId": "PAY-x9y8z7w6v5u4",
    "status": "created",
    "amount": 500,
    "currency": "USDT",
    "paymentMethod": "crypto",
    "paymentFlow": "S2S",
    "orderReference": null,
    "customerReference": null,
    "hostedPaymentUrl": null,
    "expiresAt": null,
    "instructions": null,
    "transactionId": "tx_abc123def456",
    "mId": "MID-ABCDEFGHIJ",
    "walletAddress": "0x11d94ac1d603c28c03de643e5e67e66408f3ee89",
    "qrCodeUrl": "data:image/png;base64,iVBORw0KGgo...",
    "customerName": null,
    "customerEmail": null,
    "customerWallet": null,
    "createdAt": "2026-03-20T10:05:00.000Z",
    "successUrl": null,
    "failureUrl": null,
    "redirectUrl": null,
    "declineReason": null
  }
}

walletAddress and qrCodeUrl are populated immediately — BXNK allocates a real vault deposit address on every crypto payment request, in both TEST and LIVE mode. There is no synthetic crypto sandbox outcome for S2S: the payment only progresses once BXNK's indexer observes an on-chain transfer to walletAddress. instructions remains null until that transfer is indexed, at which point it's populated with the indexed transfer event shown under Verify a Payment.

Create Payment Errors

Retrieve a Payment

Returns payment details by ID.

GET /product-apis/payments/{paymentId}
Authorization: Bearer <accessToken>

Response 200

Returns the same payment object shape as create payment.

Payment retrieval and status-check endpoints are each limited to 5 requests per second. For provider reconciliation, use GET /product-apis/payments/{paymentId}/status-check for unfinished, failed, or expired payments when applicable; it may update the stored status.

Errors

List Payments

Returns payments for the MID embedded in the authenticated token.

GET /product-apis/payments?page=1&limit=10&status=completed&paymentMethod=card&currency=EUR&sortBy=createdAt&sortOrder=DESC
Authorization: Bearer <accessToken>

Query Parameters

Refund a Payment

Refunds a completed payment. Both partial and full refunds are supported.

Sandbox limitation: Partial refunds are not supported in the sandbox environment. In sandbox, refund the full payment amount only. Partial refunds will work in production.

POST /product-apis/payments/{paymentId}/refund
Authorization: Bearer <accessToken>
Content-Type: application/json
Idempotency-Key: order-1001-refund

Parameters

Request

{
  "refundAmount": 49.99,
  "reason": "Customer requested refund"
}

Response 201

{
  "message": "Refund processed successfully",
  "data": {
    "refundId": "REF-XYZ123ABC",
    "paymentId": "PAY-a1b2c3d4e5f6",
    "refundAmount": 49.99,
    "refundStatus": "completed",
    "reason": "Customer requested refund",
    "createdAt": "2026-03-20T11:00:00.000Z",
    "refundedAmount": 49.99,
    "remainingRefundableAmount": 0,
    "isFullyRefunded": true
  }
}

refundStatus is one of processing, completed, or failed. The cumulative fields show the total completed refund amount, the amount still refundable, and whether the payment is fully refunded.

Use GET /product-apis/payments/{paymentId}/refund/{refundId} to retrieve the current status of a refund. This endpoint is limited to 5 requests per second.

Errors

Webhook Endpoints

Register webhook endpoints before creating payments.

Create Webhook Endpoint

POST /product-apis/psp/webhooks
Authorization: Bearer <accessToken>
Content-Type: application/json

The create response includes secret. List and status update responses do not include it.

List Webhook Endpoints

GET /product-apis/psp/webhooks
Authorization: Bearer <accessToken>

Returns active and inactive endpoints for MIDs owned by the authenticated PSP, excluding soft-deleted endpoints.

Update Webhook Status

PATCH /product-apis/psp/webhooks/{endpointId}/status
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "isActive": false
}

Rotate Webhook Secret

POST /product-apis/psp/webhooks/{endpointId}/rotate-secret
Authorization: Bearer <accessToken>

Returns id, mId, the new secret, and updatedAt.

Webhook Delivery

Webhook requests are JSON POST requests. BXNK signs the exact JSON string with HMAC-SHA256 and sends the signature in x-psp-signature when a signing secret exists.

Registered active endpoints for the payment MID are used first. If none exist and DEFAULT_WEBHOOK_URL is configured, BXNK delivers to that fallback URL and signs with the PSP signing secret.

const express = require('express');
const crypto = require('crypto');

const app = express();

app.post('/bxnk/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-psp-signature'];
  if (!signature) {
    return res.status(401).send('Missing signature');
  }

  const expectedSignature = crypto
    .createHmac('sha256', process.env.BXNK_WEBHOOK_SECRET)
    .update(req.body) // pass the Buffer directly, no need to .toString() first
    .digest('hex');

  const expectedBuf = Buffer.from(expectedSignature, 'hex');
  const receivedBuf = Buffer.from(signature, 'hex');

  if (
    expectedBuf.length !== receivedBuf.length ||
    !crypto.timingSafeEqual(expectedBuf, receivedBuf)
  ) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body.toString('utf8'));
  return res.sendStatus(200);
});

Payment lifecycle events are emitted as payment.created, payment.awaiting_otp, payment.processing, payment.completed, payment.failed, payment.expired, payment.refunded, and payment.cancelled.

Sandbox Scenarios

TEST-mode card payments are decided by which test card number you submit.

Use the following sandbox card numbers:

For S2S, submit these as metadata.cardNumber with the matching metadata.expiryMonth, metadata.expiryYear, and metadata.cvv (see Card Request). The resulting outcome (approved, declined, 3DS challenge, etc.) is whatever sandbox engine returns for that card.

SEPA S2S sandbox outcomes are driven by the debtor IBAN you submit. Use one of the following sandbox debtor IBANs:

Crypto has no synthetic sandbox outcome for S2S: outcomes always depend on the real deposit address and the on-chain transfer indexed against it (see the Crypto Request section above).

Product API Quick Reference