Keep your existing Product API authentication and payment endpoint. To accept card payments through the native on-ramp flow with BXNK checkout, set cardPaymentType to native_on_ramp and useHostedPaymentPage to true.
Before you start
Ask BXNK to enable On-Ramp flow for your account.
Create the payment
Call POST /api/v1/product-apis/payments with:
Authorization: Bearer <accessToken>
Content-Type: application/json
Idempotency-Key: <unique-key>Request body:
{
"amount": 30,
"currency": "EUR",
"paymentMethod": "card",
"cardPaymentType": "native_on_ramp",
"useHostedPaymentPage": true,
"customerReference": "customer-123",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"redirectUrl": "https://example.com",
"metadata": {
"asset": "USDC",
"network": "eth",
"paymentMethodId": "debit-credit-card",
"customerEmail": "[email protected]",
"customerName": "FName LName",
"customerBirthDate": "1990-05-21",
"country": "AE",
"billingStreet1": "Sheikh Zayed Road 21",
"billingCity": "Dubai",
"billingPostcode": "00000",
"billingCountry": "AE"
}
}Response:
{
"message": "Payment created successfully",
"data": {
"paymentId": "PAY-ABC123",
"status": "created",
"amount": 30,
"currency": "EUR",
"paymentMethod": "card",
"paymentFlow": "HPP",
"orderReference": null,
"customerReference": "customer-123",
"hostedPaymentUrl": "https://dev-payment.bxnk.com/:payment_id",
"expiresAt": "2026-09-16T00:00:00.000Z",
"instructions": {
"type": "banxa_native_identity",
"sumsub": {
"url": "https://in.sumsub.com/websdk/p/link",
"userId": "NATIVE-CUSTOMER-ID",
"expiresAt": "2026-09-15T13:27:06.928Z"
}
},
"requiresKyc": true,
"transactionId": "card_id",
"mId": "MID-ABC123",
"walletAddress": null,
"qrCodeUrl": null,
"customerName": null,
"customerEmail": "[email protected]",
"customerWallet": null,
"createdAt": "2026-09-15T13:17:06.701Z",
"confirmedAt": null,
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/failure",
"redirectUrl": "https://example.com",
"provider": "banxa",
"declineReason": null
}
}metadata.paymentMethodId selects how the customer pays: use debit-credit-card for card or apple-pay for Apple Pay. Apple Pay is available in Safari on iPhone, iPad, or Mac with a card in Apple Wallet; otherwise checkout shows a message asking the customer to switch device or browser. Identity verification works the same as for card payments.
Use GET /api/v1/product-apis/on-ramp-networks to retrieve supported asset and network values.
Idempotency-Key, metadata.asset, metadata.network, metadata.customerEmail, metadata.customerName, metadata.customerBirthDate, metadata.country, and the customer's address (metadata.billingStreet1, metadata.billingCity, metadata.billingPostcode) are required for this flow. metadata.country is the customer's 2-letter ISO 3166-1 country code (for example AE); metadata.shippingCountry is accepted instead, and metadata.country is used if both are sent. metadata.customerBirthDate is the customer's date of birth in YYYY-MM-DD format and must be a past date. The address can be sent as metadata.shippingStreet1, metadata.shippingCity, and metadata.shippingPostcode instead; metadata.billingCountry or metadata.shippingCountry, if sent, must match metadata.country. For customers in the US, metadata.state (2-letter state code, for example CA) is also required. A request missing a required field, or with an invalid country or state, is rejected with a 400 error that names the field. Reuse the same idempotency key and unchanged request when retrying; use a new key for a new payment. onRampExperience is not needed.
Returning customers with approved identity verification
BXNK reuses an approved identity when a new payment has the same PSP, MID, environment, and customer email as the existing approved customer. The create-payment response returns requiresKyc: false with instructions.type: "banxa_native_identity_approved". Redirect the customer to data.hostedPaymentUrl as usual; BXNK Checkout skips Sumsub and prepares the payment session for customers, taking them directly to the card payment form without identity reverification. If the checkout still requires payment-specific eligibility information that is not already available, the checkout collects only those missing details or documents before showing the payment form. After the customer submits payment, BXNK confirms the provider result and completes the same webhook, status-check, and merchant-redirect flow described below.
Redirect the customer
Redirect the customer to data.hostedPaymentUrl in the create-payment response. BXNK checkout handles identity verification, card collection, and the on-ramp payment flow.
The customer starts identity verification in BXNK Checkout and is redirected to Sumsub to submit their details. When they return, the checkout waits for the review result and, if the payment eligibility requires more information, asks only for the missing details or supporting documents, such as proof of address, an identity document, or a selfie. After identity and eligibility checks are complete, the customer enters their card details in the embedded payment form; BXNK then confirms the payment result, shows the final status, and redirects the customer to the configured merchant URL when the payment completes.
Confirm the final result through your existing BXNK webhooks or GET /api/v1/product-apis/payments/:paymentId. Check data.status; creating a payment or returning to your success URL does not itself confirm completion.