Overview

The Hosted Payment Page (HPP) integration allows PSPs and merchants to accept payments without building their own checkout UI. BXNK hosts the payment page and redirects customers back to the merchant site using callback URLs.

All Product API endpoints are prefixed with /product-apis and authenticated with a bearer token.

Table of Contents

Authentication
Step 1 - Register a Webhook Endpoint
Step 2 - Create an HPP Payment
Step 3 - Redirect Customer to Hosted Payment Page
Step 4 - Customer Completes Payment
Step 5 - Receive Webhook Events
Step 6 - Handle Redirect Callbacks
Step 7 - Verify Payment Status
Step 8 - Process a Refund (Optional)
Test Scenarios
Webhook Event Reference
API Quick Reference
Error Handling

1. Authentication

Start by generating an auth token using your PSP access key and secret.

Token Request

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

{
  "accessKey": "ak_test_xxxxxxxxxxxxxxxx",
  "secret": "sk_test_xxxxxxxxxxxxxxxx"
}

Token Response `201`

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

Use the returned token on all subsequent Product API requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

2. Step 1 — Register a Webhook Endpoint

Before creating payments, register a webhook endpoint to receive payment lifecycle events.

Tip: Create webhook endpoint on your server with POST method without authentication

Request

POST `/product-apis/psp/{pspId}/webhooks`

Headers:

Content-type: application/json
Authorization: Bearer <accessToken>

Body:

{
  "url": "https://webhook.site/your-unique-id",
  "secret": "whsec_my_signing_secret",
  "isActive": true
}

Field	Type	Required	Description
`url`	string	Yes	Publicly accessible HTTPS URL that will receive payment life cycle events
`secret`	string	No	Signing secret (6–255 chars). Used to generate HMAC-SHA256 signatures
`isActive`	boolean	No	Whether the endpoint is active. Defaults to `true`

Response `201`

{
  "statusCode": 201,
  "message": "Webhook endpoint created successfully",
  "data": {
    "id": 1,
    "pspId": 12,
    "merchantId": null,
    "url": "https://webhook.site/your-unique-id",
    "isActive": true,
    "createdAt": "2026-03-20T10:00:00.000Z",
    "updatedAt": "2026-03-20T10:00:00.000Z"
  }
}

For more detail of webhook, Please click here

3. Step 2 - Create an HPP Payment

Create a payment with useHostedPaymentPage set to true. The response includes a hostedPaymentUrl that you redirect the customer to.

Request

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

Card Payment (HPP)

Card details are collected on the BXNK-hosted page. You only need to specify the payment method and amount.

Body:

{
  "amount": 49.99,
  "currency": "EUR",
  "paymentMethod": "card",
  "useHostedPaymentPage": true,
  "successUrl": "https://merchant.test/payment/success",
  "failureUrl": "https://merchant.test/payment/failure",
  "orderReference": "card_success",
  "customerReference": "CUST-2002",
  "metadata": {
    "psp_id": 1,
    "merchant_id": 10,
    "test_scenario": "card_success",
    "card_number": "4242424242424242",
  }
}

Response 201:

{
  "statusCode": 201,
  "message": "Payment created successfully",
  "data": {
    "paymentId": "PAY-a1b2c3d4e5f6",
    "status": "created",
    "amount": 49.99,
    "currency": "EUR",
    "paymentMethod": "card",
    "orderReference": "card_success",
    "customerReference": "CUST-2002",
    "hostedPaymentUrl": "https://pay.bxnk.io/checkout/PAY-a1b2c3d4e5f6",
    "expiresAt": null,
    "instructions": null,
    "createdAt": "2026-03-20T10:05:00.000Z"
  }
}

Key points:

hostedPaymentUrl is populated — redirect the customer here
instructions is null — the hosted page handles card input
Card details (number, expiry, CVV) are not required in the request — the BXNK-hosted page collects them
Status transitions happen asynchronously via webhooks: created → processing → completed

Metadata Reference:

Metadata Key	Example	Description
`psp_id`	`1`	PSP ID
`merchant_id`	`10`	Merchant ID
`card_number`	`"4242424242424242"`	Card number
`test_scenario`	`"card_success"`	Controls sandbox outcome

The customer enters card details (expiry, CVV) directly on the BXNK-hosted checkout page. The sandbox engine determines the outcome based on the card number entered and the test_scenario metadata. CVV and expiry validation is skipped for HPP card payments in sandbox.

Crypto Payment (HPP)

The BXNK-hosted page displays wallet address, QR code, and countdown timer to the customer.

Body:

{
  "amount": 500,
  "currency": "EUR",
  "paymentMethod": "crypto",
  "useHostedPaymentPage": true,
  "successUrl": "https://merchant.test/payment/success",
  "failureUrl": "https://merchant.test/payment/failure",
  "metadata": {
    "psp_id": 4,
    "merchant_id": 1,
    "test_scenario": "crypto_success",
    "asset": "USDT",
    "network": "Ethereum"
  }
}

Response 201:

{
  "statusCode": 201,
  "message": "Payment created successfully",
  "data": {
    "paymentId": "PAY-x9y8z7w6v5u4",
    "status": "created",
    "amount": 500,
    "currency": "EUR",
    "paymentMethod": "crypto",
    "orderReference": null,
    "customerReference": null,
    "hostedPaymentUrl": "https://pay.bxnk.io/checkout/PAY-x9y8z7w6v5u4",
    "expiresAt": "2026-03-20T10:35:00.000Z",
    "instructions": {
      "event_id": "evt_abc123def456",
      "event_type": "crypto.transfer.indexed",
      "network": "Ethereum",
      "asset": "USDT",
      "tx_hash": "0x...",
      "block_number": 12345678,
      "block_hash": "0x...",
      "confirmations": 12,
      "timestamp": "2026-03-20T10:05:00.000Z",
      "from_address": "0x...",
      "to_address": "0x2c9b6c92...",
      "amount": "500.00",
      "amount_usd": "500.00",
      "decimals": 6,
      "fee": {
        "gas_used": 21000,
        "gas_price": "30000000000",
        "fee_eth": "0.00063",
        "fee_usd": "1.85"
      },
      "status": "confirmed",
      "wallet": {
        "wallet_id": "wallet_abc12345",
        "label": "merchant_hot_wallet"
      },
      "metadata": {
        "merchant_id": 1,
        "payment_id": "PAY-x9y8z7w6v5u4"
      },
      "expiry_time": "2026-03-20T10:35:00.000Z"
    },
    "createdAt": "2026-03-20T10:05:00.000Z"
  }
}

Key points:

hostedPaymentUrl is populated — redirect the customer here
instructions are returned with wallet details — the hosted page renders these for the customer
Default expiry: 30 minutes from creation
The hosted page shows to_address, amount, asset, network, and a countdown timer

Metadata Reference:

Metadata Key	Example	Description
`psp_id`	`4`	PSP ID
`merchant_id`	`1`	Merchant ID
`asset`	`"USDT"`	Cryptocurrency asset
`network`	`"Ethereum"`	Blockchain network
`test_scenario`	See below	Controls sandbox outcome

SEPA Bank Transfer (HPP)

The BXNK-hosted page displays bank transfer instructions (IBAN, BIC, remittance reference) to the customer.

Body:

{
  "amount": 150.0,
  "currency": "EUR",
  "paymentMethod": "bank_transfer",
  "useHostedPaymentPage": true,
  "successUrl": "https://merchant.test/payment/success",
  "failureUrl": "https://merchant.test/payment/failure",
  "orderReference": "sepa_completed",
  "customerReference": "CUST-3003",
  "metadata": {
    "psp_id": 1,
    "merchant_id": 10,
    "test_scenario": "sepa_completed",
    "creditor_name": "Acme Corp",
    "creditor_iban": "DE89370400440532013000",
    "creditor_bic": "ABCEDEFF",
    "debtor_name": "John Doe",
    "debtor_iban": "DE91370400440532013000",
    "remittance_information": "Invoice #INV-998877",
    "due_date": "2026-03-31"
  }
}

Response 201:

{
  "statusCode": 201,
  "message": "Payment created successfully",
  "data": {
    "paymentId": "PAY-m3n4o5p6q7r8",
    "status": "created",
    "amount": 150.0,
    "currency": "EUR",
    "paymentMethod": "bank_transfer",
    "orderReference": "sepa_completed",
    "customerReference": "CUST-3003",
    "hostedPaymentUrl": "https://pay.bxnk.io/checkout/PAY-m3n4o5p6q7r8",
    "expiresAt": "2026-03-22T10:05:00.000Z",
    "instructions": {
      "requestToPay": {
        "msgId": "MSGabc123def456",
        "createdAt": "2026-03-20T10:05:00.000Z",
        "debtor": {
          "name": "John Doe",
          "iban": "DE91370400440532013000"
        },
        "creditor": {
          "name": "Acme Corp",
          "iban": "DE89370400440532013000",
          "bic": "ABCEDEFF"
        },
        "paymentDetails": {
          "amount": {
            "currency": "EUR",
            "value": 150.0
          },
          "remittanceInformation": "Invoice #INV-998877",
          "dueDate": "2026-03-31"
        },
        "expirationDate": "2026-03-22T10:05:00.000Z"
      }
    },
    "createdAt": "2026-03-20T10:05:00.000Z"
  }
}

Key points:

hostedPaymentUrl is populated — redirect the customer here
instructions contain bank transfer details — the hosted page renders these for the customer
Default expiry: 2 days from creation
The hosted page shows creditor IBAN, BIC, remittance information, and due date

Metadata Reference:

Metadata Key	Example	Description
`psp_id`	`1`	PSP ID
`merchant_id`	`10`	Merchant ID
`creditor_name`	`"Acme Corp"`	Receiving entity name
`creditor_iban`	`"DE89370400440532013000"`	Receiving IBAN
`creditor_bic`	`"ABCEDEFF"`	Receiving BIC
`debtor_name`	`"John Doe"`	Sending entity name
`debtor_iban`	`"DE91370400440532013000"`	Sending IBAN
`remittance_information`	`"Invoice #123"`	Payment reference
`due_date`	`"2026-03-22"`	Payment due date
`test_scenario`	`"sepa_completed"`	Controls sandbox outcome

Request Fields Reference

Field	Type	Required	Description
`amount`	number	Yes	Payment amount (min `0.01`, up to 8 decimal places)
`currency`	string	Yes	ISO currency code (3–10 chars, e.g., `EUR`, `USD`)
`paymentMethod`	string	*	Single method: `card`, `crypto`, or `bank_transfer`
`paymentMethods`	string[]	*	Array of methods. First one is used. Alternative to `paymentMethod`
`useHostedPaymentPage`	boolean	Yes	Set to `true` for HPP integration
`successUrl`	string	Yes	URL to redirect the customer after successful payment
`failureUrl`	string	Yes	URL to redirect the customer after failed/expired payment
`orderReference`	string	No	Your order ID for reconciliation
`customerReference`	string	No	Your customer ID for reconciliation
`expiryTime`	string	No	ISO 8601 expiry timestamp. Defaults vary by method (crypto: 30 min, SEPA: 2 days)
`metadata`	object	No	Arbitrary key-value pairs. Use `test_scenario` to control sandbox behavior

Note: Either paymentMethod or paymentMethods is required. If both are provided, paymentMethod takes precedence.

4. Step 3 — Redirect Customer to Hosted Payment Page

After creating the payment, redirect the customer's browser to the hostedPaymentUrl returned in the response.

The URL format is:

https://pay.bxnk.io/checkout/{paymentId}

Redirect Methods

Server-side redirect (recommended):

HTTP/1.1 302 Found
Location: https://pay.bxnk.io/checkout/PAY-a1b2c3d4e5f6

Client-side redirect:

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

Tip: Do not embed the hosted payment page in an iframe. Always perform a full-page redirect to ensure proper rendering and security.

5. Step 4 — Customer Completes Payment

Once redirected, the customer interacts with the BXNK-hosted checkout page:

Payment Method	Customer Experience
Card	Customer enters card number, expiry date, and CVV on the hosted form. Payment is processed in sandbox.
Crypto	Customer sees wallet address, QR code, asset, network, amount, and a countdown timer.
Bank Transfer	Customer sees creditor IBAN, BIC, remittance reference, amount, and due date.

After the payment is processed (or fails/expires), the customer is redirected to the appropriate callback URL:

Success: Redirected to successUrl provided in the create request
Failure/Expiry: Redirected to failureUrl provided in the create request

Tip: Do not rely solely on the redirect to determine payment outcome. Always verify via webhooks or the GET payment endpoint.

6. Step 5 — Receive Webhook Events

After payment creation, the system emits webhook events to your registered endpoint in sequence:

Order	Event Type	Timing	Description
1	`payment.created`	Immediately	Payment record created
2	`payment.processing`	~60 seconds later	Payment is being processed
3	`payment.completed`	~90 seconds later	Payment completed successfully
3	`payment.failed`	~90 seconds later	Payment failed (alternative final state)
3	`payment.expired`	~90 seconds later	Payment expired (alternative final state)

Timing is based on WEBHOOK_DELAY_MS (default: 30,000 ms). Events 2 and 3 fire at 2x and 3x the delay.

Webhook Payload Structure

Each webhook is delivered as an HTTP POST with Content-Type: application/json:

Standard payload (card, SEPA):

{
  "event_id": "evt_a1b2c3d4e5f6",
  "event_type": "payment.completed",
  "payment_id": "PAY-a1b2c3d4e5f6",
  "event_timestamp": "2026-03-20T10:06:30.000Z",
  "payload": {
    "paymentId": "PAY-a1b2c3d4e5f6",
    "status": "completed",
    "amount": 49.99,
    "currency": "EUR",
    "paymentMethod": "card"
  }
}

Crypto payload:

For crypto payments, the payload contains the full instruction set (tx_hash, addresses, fee structure, etc.) instead of the simplified format above.

{
  "event_id": "evt_jLmARrUrMeK3",
  "event_type": "payment.completed",
  "payment_id": "PAY-5H7kOr-cGP4Z",
  "event_timestamp": "2026-03-18T12:20:18.014Z",
  "payload": {
    "fee": {
      "fee_eth": "0.00063",
      "fee_usd": "1.85",
      "gas_used": 21000,
      "gas_price": "30000000000"
    },
    "asset": "USDT",
    "amount": "500.00",
    "status": "confirmed",
    "wallet": {
      "label": "merchant_hot_wallet",
      "wallet_id": "wallet_7afbba9c"
    },
    "network": "Ethereum",
    "tx_hash": "0x72547233b3c30f96e2311e04705b7bb09c3c0a9fb84c2c3ac54bc3ceac670ffc",
    "decimals": 6,
    "event_id": "evt_e9bfd434ee06dd2b",
    "metadata": {
      "payment_id": "PAY-5H7kOr-cGP4Z",
      "merchant_id": 1
    },
    "timestamp": "2026-03-18T12:18:47.968Z",
    "amount_usd": "500.00",
    "block_hash": "0x0a96c04bb5c68e97c2b90f46cf5dc04e8b8ea82b25ff0c82b71b68f85832b5c9",
    "event_type": "crypto.transfer.indexed",
    "to_address": "0x11d94ac1d603c28c03de643e5e67e66408f3ee89",
    "expiry_time": "2026-03-18T12:48:47.968Z",
    "block_number": 13874650,
    "from_address": "0xdda1aaa067003cecabf7328e00267b764ec840ab",
    "confirmations": 12
  }
}

SEPA Payload

{
  "event_id": "evt_-pbmufNI9A-I",
  "event_type": "payment.completed",
  "payment_id": "PAY-8CsCABpOyP5A",
  "event_timestamp": "2026-03-13T13:33:28.927Z",
  "payload": {
    "paymentId": "PAY-8CsCABpOyP5A",
    "status": "completed",
    "amount": 100,
    "currency": "EUR",
    "paymentMethod": "bank_transfer"
  }
}

Webhook Signature Verification

If you provided a secret when creating the webhook endpoint, every delivery includes a x-psp-signature header containing an HMAC-SHA256 hex digest of the request body:

x-psp-signature: a1b2c3d4e5f6...

To verify:

const crypto = require("crypto");

const signature = crypto
  .createHmac("sha256", "whsec_my_signing_secret")
  .update(rawRequestBody)
  .digest("hex");

const isValid = signature === req.headers["x-psp-signature"];

7. Step 6 — Handle Redirect Callbacks

After the payment completes on the hosted page, the customer's browser is redirected to the URL you provided:

Outcome	Redirect Target	Description
Payment succeeded	`successUrl`	Customer completed the payment successfully
Payment failed	`failureUrl`	Payment was declined, underpaid, or otherwise failed
Payment expired	`failureUrl`	Payment window expired before completion

Callback URL Parameters

The redirect appends query parameters to your callback URL:

https://merchant.test/payment/success?paymentId=PAY-a1b2c3d4e5f6&status=completed

https://merchant.test/payment/failure?paymentId=PAY-a1b2c3d4e5f6&status=failed

Tip: Always verify the payment status server-side using the GET payment endpoint or webhooks. Redirect parameters can be manipulated by the end user.

8. Step 7 — Verify Payment Status

Poll the payment status at any time using the payment ID returned in the create response.

Request

GET `/product-apis/payments/{paymentId}`
Content-type: application/json
Authorization: Bearer <accessToken>

Response `200`

{
  "statusCode": 200,
  "message": "Payment retrieved successfully",
  "data": {
    "paymentId": "PAY-a1b2c3d4e5f6",
    "status": "completed",
    "amount": 49.99,
    "currency": "EUR",
    "paymentMethod": "card",
    "orderReference": "card_success",
    "customerReference": "CUST-2002",
    "hostedPaymentUrl": null,
    "expiresAt": null,
    "instructions": null,
    "createdAt": "2026-03-20T10:05:00.000Z"
  }
}

List Payments by PSP

GET `/product-apis/payments/psp/{pspId}?page=1&limit=10&status=completed&paymentMethod=card&currency=EUR&sortBy=createdAt&sortOrder=DESC`
Content-type: application/json
Authorization: Bearer <accessToken>

List Payments by Merchant

GET `/product-apis/payments/merchant/{merchantId}?page=1&limit=10`
Content-type: application/json
Authorization: Bearer <accessToken>

Payment Status Lifecycle

created → processing → completed
                     → failed
                     → expired
completed → refunded
created/processing → cancelled

Status	Description
`created`	Payment record created, awaiting processing
`processing`	Payment is being processed by the payment network
`completed`	Payment received and confirmed
`failed`	Payment failed (declined, underpayment, etc.)
`expired`	Payment window expired before completion
`refunded`	A refund has been processed against this payment
`cancelled`	Payment was cancelled before completion

9. Step 8 — Process a Refund (Optional)

Refunds are only allowed on completed payments. The refund amount must not exceed the original payment amount.

Request

POST `/product-apis/payments/{paymentId}/refund`
Content-type: application/json
Authorization: Bearer <accessToken>

Body:

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

Field	Type	Required	Description
`refundAmount`	number	Yes	Amount to refund (min `0.01`, must not exceed payment amount)
`reason`	string	No	Reason for the refund

Response `201`

{
  "statusCode": 201,
  "message": "Refund processed successfully",
  "data": {
    "refundId": "REF-XYZ123ABC",
    "paymentId": "PAY-a1b2c3d4e5f6",
    "refundAmount": 50.0,
    "refundStatus": "completed",
    "reason": "Customer requested refund",
    "createdAt": "2026-03-20T11:00:00.000Z"
  }
}

A payment.refunded webhook event is emitted after a successful refund:

{
  "event_id": "evt_ref123abc",
  "event_type": "payment.refunded",
  "payment_id": "PAY-a1b2c3d4e5f6",
  "event_timestamp": "2026-03-20T11:00:00.000Z",
  "payload": {
    "paymentId": "PAY-a1b2c3d4e5f6",
    "status": "refunded",
    "amount": 49.99,
    "currency": "EUR",
    "paymentMethod": "card",
    "refundId": "REF-XYZ123ABC",
    "refundAmount": 50.0,
    "refundStatus": "completed"
  }
}

11. Test Scenarios

Control sandbox payment outcomes using the test_scenario metadata field or specific orderReference prefixes.

Card Scenarios

Scenario	Final Status	Description
`card_success`	`completed`	Successful card payment
`card_declined`	`failed`	Card was declined
(none)	(pending)	Stays in `processing`

Test Card Numbers

These card numbers are entered by the customer on the hosted payment page:

Card Number	Result
`4111111111111111`	Success
`5555555555554444`	Success
`4000000000000002`	Decline
`4000000000009995`	Decline

In HPP mode, card expiry and CVV validation is skipped in sandbox. Any values entered on the hosted page are accepted.

Scenarios can also be triggered by using the scenario name as the orderReference (e.g., "orderReference": "card_success").

12. Webhook Event Reference

Event Type	Trigger
`payment.created`	Payment record saved to database
`payment.processing`	Payment transitions to processing
`payment.completed`	Payment confirmed as successful
`payment.failed`	Payment failed or declined
`payment.expired`	Payment expired before completion
`payment.refunded`	Refund processed against completed payment
`payment.cancelled`	Payment was cancelled before completion

Delivery Details

Method: POST
Content-Type: application/json
Timeout: 10 seconds
Retries: 3 attempts in sandbox, 1 in production
Signature header: x-psp-signature (HMAC-SHA256, only if secret is configured)
Fallback: If no endpoints are registered, the system falls back to DEFAULT_WEBHOOK_URL (env variable)
Target resolution: Webhooks are sent to all active endpoints matching the payment's pspId or merchantId

13. API Quick Reference

All endpoints require X-Access-Key and X-Secret-Key headers.

Method	Endpoint	Description
`POST`	`/product-apis/psp/{pspId}/webhooks`	Create webhook endpoint
`GET`	`/product-apis/psp/{pspId}/webhooks`	List webhook endpoints
`PATCH`	`/product-apis/psp/{pspId}/webhooks/{id}/status`	Enable/disable webhook endpoint
`POST`	`/product-apis/payments`	Create a payment (HPP or S2S)
`GET`	`/product-apis/payments/{paymentId}`	Get payment details
`GET`	`/product-apis/payments/psp/{pspId}`	List payments for a PSP
`GET`	`/product-apis/payments/merchant/{merchantId}`	List payments for a merchant
`POST`	`/product-apis/payments/{paymentId}/refund`	Refund a payment
`POST`	`/product-apis/payments/{paymentId}/cancel`	Cancel a payment
`GET`	`/product-apis/psp/{pspId}/balance`	Get PSP balance
`GET`	`/product-apis/psp/{pspId}/chargeback-config`	Get chargeback configuration
`GET`	`/product-apis/payment-methods/active`	List active payment methods
`GET`	`/product-apis/payment-methods/psp`	List PSP's supported payment methods
`GET`	`/product-apis/payment-methods/psp/{paymentMethodId}/currencies`	List currencies for a payment method
`GET`	`/product-apis/currencies`	List all currencies
`GET`	`/product-apis/currencies/psp`	List PSP's supported currencies
`POST`	`/product-apis/storage/presigned-upload`	Get presigned upload URL
`GET`	`/product-apis/storage/presigned-download/{key}`	Get presigned download URL
`DELETE`	`/product-apis/storage/delete/{key}`	Delete a file from S3
`GET`	`/product-apis/healthz`	Health check

14. Error Handling

All error responses follow a consistent structure:

{
  "statusCode": 400,
  "message": "paymentMethod or paymentMethods is required",
  "error": "Bad Request"
}

Status	Meaning
`400`	Validation error (missing fields, invalid values)
`401`	Missing or invalid API key headers
`403`	API key does not have access to the requested PSP resource
`404`	Payment or webhook endpoint not found

Common Validation Errors

Error	Cause
`paymentMethod or paymentMethods is required`	Neither field provided
`Refunds are only allowed for completed payments`	Payment status is not `completed`
`Refund amount exceeds payment amount`	`refundAmount` > original `amount`
`Payment does not belong to this PSP`	API key's PSP does not own the payment
`API key does not have access to this PSP`	`pspId` in URL does not match API key's PSP
`PSP balance cannot be negative`	Refund would result in negative PSP balance