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 /api/v1/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 /api/v1/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 /api/v1/product-apis/payments
Authorization: Bearer <accessToken>
Content-Type: application/json
Idempotency-Key: order-1001-create

Idempotency-Key is optional for S2S payments, reused only to deduplicate retries with the same request body.

S2S supports crypto and SEPA payments. To accept card payments, use the native on-ramp hosted payment page.

Parameters

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 /api/v1/product-apis/payments/{paymentId}
Authorization: Bearer <accessToken>

Response 200

Returns the same payment object shape as create payment. The payment status is one of created, awaiting_otp, processing, completed, failed, expired, refunded, or cancelled.

Payment retrieval and status-check endpoints are each limited to 5 requests per second. For provider reconciliation, use GET /api/v1/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 /api/v1/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 /api/v1/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 /api/v1/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.

Strongly recommended: register a webhook endpoint for every new MID as soon as it's created to receive real-time payment status updates.

Create Webhook Endpoint

POST /api/v1/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 /api/v1/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 /api/v1/product-apis/psp/webhooks/{endpointId}/status
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "isActive": false
}

Rotate Webhook Secret

POST /api/v1/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

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