Hosted Payment Page Payments

Use the Hosted Payment Page (HPP) integration when BXNK should collect payment details from the customer. Your server creates the payment, then redirects the customer to the hostedPaymentUrl returned by the API.

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

Crypto 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

Generate a Product API bearer token before calling payment or webhook endpoints.

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

Name	Type	Required	Description
`accessKey`	string	Yes	API access key. Must be a non-empty string.
`secret`	string	Yes	API secret. Must be a non-empty string.

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

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

Use the returned token on subsequent requests:

Authorization: Bearer <accessToken>

Register a Webhook Endpoint

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

Parameters

Name	Type	Required	Description
`url`	URL	Yes	Public URL that receives webhook POSTs.
`mId`	string	Yes	MID for this endpoint. Must belong to the authenticated PSP.
`secret`	string	No	Signing secret. Must be length `6..255`. If omitted, BXNK generates one.
`isActive`	boolean	No	Defaults to `true`.

Request

{
  "mId": "MID-ABCDEFGHIJ",
  "url": "https://merchant.example/webhooks/bxnk",
  "secret": "whsec_my_signing_secret",
  "isActive": true
}

Response `201`

{
  "message": "Webhook endpoint created successfully",
  "data": {
    "id": 1,
    "mId": "MID-ABCDEFGHIJ",
    "url": "https://merchant.example/webhooks/bxnk",
    "secret": "whsec_my_signing_secret",
    "isActive": true,
    "createdAt": "2026-03-20T10:00:00.000Z",
    "updatedAt": "2026-03-20T10:00:00.000Z"
  }
}

BXNK includes secret only when an endpoint is created or rotated. List and status update responses omit it.

Rotate a Webhook Secret

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

{
  "message": "Webhook endpoint secret rotated successfully",
  "data": {
    "id": 1,
    "mId": "MID-ABCDEFGHIJ",
    "secret": "whsec_new_signing_secret",
    "updatedAt": "2026-03-20T10:15:00.000Z"
  }
}

Create an HPP Payment

Create a payment with useHostedPaymentPage: true. The response includes hostedPaymentUrl; redirect the customer's browser to that exact value.

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

The Idempotency-Key header is optional. When present, BXNK reuses the first result for retries with the same request body.

Parameters

Name	Type	Required	Description
`amount`	number	Yes	Payment amount. Must be at least `0.000005` and have no more than 8 decimal places.
`currency`	string	Yes	Currency code looked up by the backend. Must be a string with length `3..40`; the service uppercases it before lookup.
`paymentMethod`	string	Conditionally	One of `card`, `crypto`, or `bank_transfer`. Required when `paymentMethods` is omitted. Takes precedence if both fields are provided.
`paymentMethods`	string[]	Conditionally	Non-empty array of `card`, `crypto`, or `bank_transfer`. The first value is used when `paymentMethod` is omitted.
`cardPaymentType`	string	No	Set to `on_ramp` only for an on-ramp HPP card payment.
`useHostedPaymentPage`	boolean	Yes	Set to `true` for HPP.
`successUrl`	URL	No	Callback URL used for success events and hosted redirects after success.
`failureUrl`	URL	No	Callback URL used for failed, cancelled, or expired events and hosted redirects after failure.
`orderReference`	string	No	Merchant order reference.
`customerReference`	string	No	Merchant customer reference.
`expiryTime`	ISO 8601 string	No	Future expiry timestamp. Invalid or past values return `400`.
`metadata`	object	Conditionally	Additional metadata. Crypto and on-ramp payments require `asset` and `network`.
`metadata.m_id`	string	No	MID to create the payment for. The MID embedded in the Product API bearer token is used automatically, so this key can be omitted when calling with a Product API token; it is only consulted as a fallback when the token carries no MID.
`metadata.customerName`	string	No	Customer full name, stored on the payment and returned in the response.
`metadata.customerEmail`	string	No	Customer email, stored on the payment and returned in the response.

On-Ramp HPP

Use on-ramp only with paymentMethod: "card" and useHostedPaymentPage: true.

Get the supported network and asset pairs.
Use the selected networkCode as metadata.network and currencies[].name as metadata.asset.
Create the HPP payment with cardPaymentType: "on_ramp", then redirect the customer to hostedPaymentUrl.

GET /product-apis/on-ramp-networks
Authorization: Bearer <accessToken>

{
  "message": "On-ramp networks retrieved successfully",
  "data": [
    {
      "networkCode": "polygon",
      "networkName": "Polygon",
      "currencies": [{ "name": "USDC" }]
    }
  ]
}

The endpoint returns networks and assets for creating an on-ramp payment. Use the returned asset and network values; do not send an unsupported pair.

POST /product-apis/payments
Authorization: Bearer <accessToken>
Content-Type: application/json
Idempotency-Key: order-1002-on-ramp

{
  "amount": 50,
  "currency": "EUR",
  "paymentMethod": "card",
  "cardPaymentType": "on_ramp",
  "useHostedPaymentPage": true,
  "successUrl": "https://merchant.example/payment/success",
  "failureUrl": "https://merchant.example/payment/failure",
  "metadata": {
    "asset": "USDC",
    "network": "polygon",
    "customerName": "FName LName",
    "customerEmail": "<email>"
  }
}

For on-ramp payments, Idempotency-Key, metadata.asset, and metadata.network are required. The selected payment currency and amount must be supported by the configured provider.

Card HPP Request

Do not send card details in the create request. Card details are collected on the hosted page.

{
  "amount": 49.99,
  "currency": "EUR",
  "paymentMethod": "card",
  "useHostedPaymentPage": true,
  "successUrl": "https://merchant.example/payment/success",
  "failureUrl": "https://merchant.example/payment/failure",
  "orderReference": "card_success",
  "customerReference": "CUST-2002",
  "metadata": {
    "m_id": "MID-ABCDEFGHIJ",
    "customerName": "John Doe",
    "customerEmail": "[email protected]"
  }
}

Card HPP Response `201`

{
  "message": "Payment created successfully",
  "data": {
    "paymentId": "PAY-a1b2c3d4e5f6",
    "status": "created",
    "amount": 49.99,
    "currency": "EUR",
    "paymentMethod": "card",
    "paymentFlow": "HPP",
    "orderReference": "card_success",
    "customerReference": "CUST-2002",
    "hostedPaymentUrl": "https://pay.bxnk.example/UEFZLWExYjJjM2Q0ZTVmNg.signature",
    "expiresAt": null,
    "instructions": null,
    "transactionId": null,
    "mId": "MID-ABCDEFGHIJ",
    "walletAddress": null,
    "qrCodeUrl": null,
    "customerName": "John Doe",
    "customerEmail": "[email protected]",
    "customerWallet": null,
    "createdAt": "2026-03-20T10:05:00.000Z",
    "successUrl": "https://merchant.example/payment/success",
    "failureUrl": "https://merchant.example/payment/failure",
    "redirectUrl": null,
    "declineReason": null
  }
}

hostedPaymentUrl is an opaque signed token URL built by the backend. Do not construct it yourself from the payment ID.

Card details and customer email are collected entirely on the hosted page — your server is not involved in that step. Verify the final outcome with GET /product-apis/payments/{paymentId} or a webhook; do not treat page navigation alone as settlement confirmation.

Crypto HPP Request

Crypto HPP creation validates metadata.asset, metadata.network, and PSP wallet configuration before returning the hosted page URL. BXNK also enforces a minimum deposit amount, converted to USD using the current exchange rate for the requested asset; requests below that minimum return 400.

{
  "amount": 500,
  "currency": "USDT",
  "paymentMethod": "crypto",
  "useHostedPaymentPage": true,
  "successUrl": "https://merchant.example/payment/success",
  "failureUrl": "https://merchant.example/payment/failure",
  "metadata": {
    "m_id": "MID-ABCDEFGHIJ",
    "asset": "USDT",
    "network": "ethereum"
  }
}

Crypto HPP Response `201`

{
  "message": "Payment created successfully",
  "data": {
    "paymentId": "PAY-x9y8z7w6v5u4",
    "status": "created",
    "amount": 500,
    "currency": "USDT",
    "paymentMethod": "crypto",
    "paymentFlow": "HPP",
    "orderReference": null,
    "customerReference": null,
    "hostedPaymentUrl": "https://pay.bxnk.example/UEFZLXg5eTh6N3c2djV1NA.signature",
    "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": "https://merchant.example/payment/success",
    "failureUrl": "https://merchant.example/payment/failure",
    "redirectUrl": null,
    "declineReason": null
  }
}

The crypto engine allocates a real vault deposit address for every request (test and live), so walletAddress and qrCodeUrl are populated immediately on create, and instructions is null until the deposit is indexed. Once BXNK indexes an on-chain transfer to walletAddress, instructions is populated with the indexed transfer event (see the Verify Payment Status example below) and the payment transitions out of created.

SEPA HPP Request

For HPP SEPA, the create request stores the payment and returns the hosted page URL. The hosted page collects SEPA details and submits them before bank-transfer instructions are generated.

{
  "amount": 150.5,
  "currency": "EUR",
  "paymentMethod": "bank_transfer",
  "useHostedPaymentPage": true,
  "orderReference": "INV-1001",
  "customerReference": "CUSTOMER-42",
  "successUrl": "https://merchant.example/payment/success",
  "failureUrl": "https://merchant.example/payment/failure",
  "metadata": {
    "m_id": "MID-ABCDEFGHIJ"
  }
}

SEPA HPP Response `201`

{
  "message": "Payment created successfully",
  "data": {
    "paymentId": "PAY-m3n4o5p6q7r8",
    "status": "created",
    "amount": 150.5,
    "currency": "EUR",
    "paymentMethod": "bank_transfer",
    "paymentFlow": "HPP",
    "orderReference": "INV-1001",
    "customerReference": "CUSTOMER-42",
    "hostedPaymentUrl": "https://pay.bxnk.example/UEFZLW0zbjRvNXA2cTdyOA.signature",
    "expiresAt": null,
    "instructions": null,
    "transactionId": null,
    "mId": "MID-ABCDEFGHIJ",
    "walletAddress": null,
    "qrCodeUrl": null,
    "customerName": null,
    "customerEmail": null,
    "customerWallet": null,
    "createdAt": "2026-03-20T10:05:00.000Z",
    "successUrl": "https://merchant.example/payment/success",
    "failureUrl": "https://merchant.example/payment/failure",
    "redirectUrl": null,
    "declineReason": null
  }
}

SEPA HPP payments are only supported in sandbox (TEST mode) today. Live SEPA S2S/HPP submission is not yet available; submitting a SEPA payment for a LIVE-mode API key fails with 400.

Redirect the Customer

After create payment succeeds, redirect the browser to data.hostedPaymentUrl.

window.location.href = response.data.hostedPaymentUrl;

Do not embed the hosted page in an iframe, and do not derive the URL from paymentId. The URL contains a signed token.

After payment completion, cancellation, failure, or expiry, the hosted flow uses the stored successUrl or failureUrl where applicable. Treat redirects as a user-experience signal only; verify final state with webhooks or GET /product-apis/payments/{paymentId}.

Card Checkout: What the Customer Sees

On the hosted page, the customer enters their name and email, picks a card brand, then continues to a secure checkout page where they enter their card details and complete 3D Secure if the issuer requires it. They're then returned to the hosted page, which confirms the result and redirects to your successUrl or failureUrl with paymentId appended. Don't treat that redirect as proof of payment on its own — always confirm the final status with GET /product-apis/payments/{paymentId} or a webhook.

To test both with and without a 3D Secure challenge, use:

Card number	Brand	Expiry	CVV
`5332990065668865`	Mastercard	`10/26`	`872`
`4295550031726664`	Visa	`05/27`	`390`

Verify Payment Status

Returns payment details by ID.

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

The response uses the same payment object shape returned by 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.

{
  "message": "Payment retrieved successfully",
  "data": {
    "paymentId": "PAY-x9y8z7w6v5u4",
    "status": "processing",
    "amount": 500,
    "currency": "USDT",
    "paymentMethod": "crypto",
    "paymentFlow": "HPP",
    "orderReference": null,
    "customerReference": null,
    "hostedPaymentUrl": "https://pay.bxnk.example/UEFZLXg5eTh6N3c2djV1NA.signature",
    "expiresAt": "2026-03-20T10:35:00.000Z",
    "instructions": {
      "event_id": "evt_abc123def4567890",
      "event_type": "crypto.transfer.indexed",
      "network": "ethereum",
      "asset": "USDT",
      "timestamp": "2026-03-20T10:05:00.000Z",
      "amount": "500.00",
      "amount_usd": "500.00",
      "decimals": 6,
      "metadata": {
        "merchant_id": "mrc_abc123",
        "payment_id": "PAY-x9y8z7w6v5u4"
      },
      "expiry_time": "2026-03-20T10:35:00.000Z"
    },
    "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": "https://merchant.example/payment/success",
    "failureUrl": "https://merchant.example/payment/failure",
    "redirectUrl": null,
    "declineReason": null
  }
}

Status Values

Status	Description
`created`	Payment record has been created.
`awaiting_otp`	Card 3DS challenge exists and waits for OTP verification.
`processing`	Payment is being processed.
`completed`	Payment completed.
`failed`	Payment failed. `declineReason` may be populated.
`expired`	Payment expired before completion.
`refunded`	Payment was fully refunded.
`cancelled`	Payment was cancelled.

Refund a Payment

Refunds a completed payment. Both full and partial 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

Name	Type	Required	Description
`refundAmount`	number	Yes	Must be at least `0.01`, have no more than 8 decimal places, and less or equal to the original payment amount.
`reason`	string	No	Refund reason.

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

{
  "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.

Webhooks

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.

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 events include payment.created, payment.awaiting_otp, payment.processing, payment.completed, payment.failed, payment.expired, payment.refunded, and payment.cancelled.

For non-crypto payments, webhook payloads include paymentId, status, amount, currency, paymentMethod, and declineReason when present. For crypto payments, the payload includes paymentId, status, the indexed crypto transfer fields, and (on the payment.created event only) transaction_id, wallet_address, vault_account_id, and vault_account_name.

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.

Sandbox Testing

Sandbox outcomes for card payments are decided by which test card number is entered.

Use the following sandbox card numbers:

Card number	Brand	Expiry	CVV
`5332990065668865`	Mastercard	`10/26`	`872`
`4295550031726664`	Visa	`05/27`	`390`

Sandbox outcomes for SEPA are driven by the debtor IBAN entered on the hosted page (or submitted via S2S). Use one of the following sandbox debtor IBANs:

Debtor IBAN	Final status	Decline reason
`DE89370400440532013000`	`completed`	—
`DE91370400440532013000`	`failed`	`insufficient_funds`
`DE12500105170648489890`	`failed`	`iban_invalid`

Any other debtor IBAN stays in processing until another status check changes it.

For crypto, the outcome always depends on the actual on-chain deposit indexed against the generated wallet address, compared against the expected amount.

Common Errors

Status	When it happens
`400`	Request validation fails, no MID can be resolved from the token or `metadata.m_id`, `paymentMethod` and `paymentMethods` are both omitted, `expiryTime` is invalid or not in the future, or payment method requirements are not met.
`400`	On-ramp is not a hosted card payment, its idempotency key or asset/network is missing, the amount is outside the supported range, or the configured provider does not support on-ramp for the selected currency.
`400`	Crypto request omits `metadata.network` or `metadata.asset`, uses an unsupported asset/network, the deposit amount converts to less than the configured USD minimum, or the PSP has no settlement wallet configured for the asset.
`400`	Refund is attempted on a non-`completed` payment, the payment has already been fully refunded, or the requested amount exceeds the remaining refundable amount.
`400`	SEPA payment is submitted for a `LIVE`-mode API key (live SEPA is not yet supported).
`401`	Bearer token is missing, expired, or invalid.
`403`	Payment MID does not match the authenticated token where ownership is checked.
`404`	Payment or webhook endpoint is not found.
`429`	Polling rate limit exceeded. Payment retrieval, status-check, and refund-status endpoints allow up to 5 requests per second.
`502`	The card provider declined the refund.
`503`	The refund result could not be confirmed with the card provider and requires manual reconciliation.
`503`	Crypto payment creation has been disabled for the environment. This gate applies only to crypto; there is no equivalent disable switch for card or SEPA creation.

Product API Quick Reference

Method	Endpoint	Description
`POST`	`/product-apis/auth/token`	Generate a Product API bearer token.
`POST`	`/product-apis/payments`	Create an HPP or S2S payment.
`GET`	`/product-apis/on-ramp-networks`	List supported on-ramp network and asset pairs.
`GET`	`/product-apis/payments`	List payments for the authenticated MID.
`GET`	`/product-apis/payments/{paymentId}`	Retrieve a payment.
`GET`	`/product-apis/payments/{paymentId}/status-check`	Check status and resume a non-terminal payment if possible.
`POST`	`/product-apis/payments/{paymentId}/refund`	Refund a completed payment.
`GET`	`/product-apis/payments/{paymentId}/refund/{refundId}`	Retrieve refund status.
`GET`	`/payments/hosted/{hostedPaymentToken}`	Public: retrieve hosted payment details (no auth).
`POST`	`/product-apis/psp/webhooks`	Create a webhook endpoint.
`GET`	`/product-apis/psp/webhooks`	List webhook endpoints.
`PATCH`	`/product-apis/psp/webhooks/{endpointId}/status`	Enable or disable a webhook endpoint.
`POST`	`/product-apis/psp/webhooks/{endpointId}/rotate-secret`	Rotate a webhook signing secret.
`GET`	`/product-apis/psp/balance`	Get PSP balance.
`GET`	`/product-apis/psp/balances/assets`	Get PSP asset balances.
`GET`	`/product-apis/psp/chargeback-config`	Get PSP chargeback config.
`GET`	`/product-apis/payment-methods/active`	List active payment methods.
`GET`	`/product-apis/payment-methods/psp`	List the authenticated PSP's payment methods.
`GET`	`/product-apis/payment-methods/psp/{paymentMethodId}/currencies`	List currencies assigned to a PSP payment method.
`GET`	`/product-apis/currencies`	List currencies.
`GET`	`/product-apis/currencies/psp`	List currencies supported by the authenticated PSP.
`POST`	`/product-apis/storage/presigned-upload`	Generate a presigned S3 upload URL.
`GET`	`/product-apis/storage/presigned-download/{key}`	Generate a presigned S3 download URL.
`DELETE`	`/product-apis/storage/delete/{key}`	Delete an S3 object.
`GET`	`/product-apis/healthz`	Check database health.

Hosted Payment Page Payments

Base URL

Authentication

Register a Webhook Endpoint

Parameters

Request

Response 201

Rotate a Webhook Secret

Create an HPP Payment

Parameters

On-Ramp HPP

Card HPP Request

Card HPP Response 201

Crypto HPP Request

Crypto HPP Response 201

SEPA HPP Request

SEPA HPP Response 201

Redirect the Customer

Card Checkout: What the Customer Sees

Verify Payment Status

Status Values

Refund a Payment

Webhooks

Sandbox Testing

Common Errors

Product API Quick Reference

Response `201`

Card HPP Response `201`

Crypto HPP Response `201`

SEPA HPP Response `201`