Accept Apple Pay with Native On-Ramp

Let customers process payments with Apple Pay in BXNK Checkout. Create a native on-ramp payment with metadata.paymentMethodId set to apple-pay, then redirect the customer to the hosted checkout.

Before you start

Ask BXNK to enable native on-ramp and Apple Pay for your account.
Use your existing Product API access token.
Use GET /api/v1/product-apis/on-ramp-networks to retrieve supported asset and network values.

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": "apple-pay",
    "customerEmail": "[email protected]",
    "customerName": "FName LName",
    "customerBirthDate": "1990-05-21",
    "country": "AE",
    "billingStreet1": "Sheikh Zayed Road 21",
    "billingCity": "Dubai",
    "billingPostcode": "00000",
    "billingCountry": "AE"
  }
}

Field	Required	Notes
`cardPaymentType`	Yes	Set to `native_on_ramp`.
`useHostedPaymentPage`	Yes	Set to `true`.
`metadata.paymentMethodId`	Yes	Set to `apple-pay`.
`metadata.asset`, `metadata.network`	Yes	Use a supported pair from `GET /api/v1/product-apis/on-ramp-networks`.
`metadata.customerEmail`	Yes	Identifies the customer and lets BXNK reuse an approved identity verification.
`metadata.customerName`	Yes	Customer's full name.
`metadata.country`	Yes	Customer's 2-letter ISO 3166-1 country code, for example `AE`. `metadata.shippingCountry` is accepted instead; `metadata.country` is used if both are sent.
`metadata.customerBirthDate`	Yes	Customer's date of birth, a past date in `YYYY-MM-DD` format.
`metadata.billingStreet1`, `metadata.billingCity`, `metadata.billingPostcode`	Yes	Customer's address. `metadata.shippingStreet1`, `metadata.shippingCity`, and `metadata.shippingPostcode` are accepted instead.
`metadata.billingState`	No	Customer's state or region for the address. 2-letter code for US and Canada.
`metadata.billingCountry`	No	2-letter ISO 3166-1 country code of the address. If sent, it must match `metadata.country`.
`metadata.state`	Yes for US customers	2-letter US state code, for example `CA`.
`Idempotency-Key`	Yes	Reuse the same key and unchanged request when retrying; use a new key for a new payment.

onRampExperience is not needed.

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
  }
}

Redirect the customer to data.hostedPaymentUrl. BXNK Checkout handles identity verification and Apple Pay.

If BXNK already holds an approved identity for the same PSP, MID, environment, and customer email, the response returns requiresKyc: false and checkout skips identity verification, taking the customer straight to Apple Pay.

Customer experience

The customer opens hostedPaymentUrl and completes identity verification. Returning customers with an approved identity skip this step.
If more information is needed for payment eligibility, checkout asks only for the missing details or documents, such as proof of address, an identity document, or a selfie.
Checkout shows the Apple Pay button.
The customer confirms the payment with Face ID, Touch ID, or their device passcode.
BXNK confirms the result, shows the final status, and redirects the customer to your configured URL.

Device and browser requirements

Apple Pay is available in Safari on iPhone, iPad, or Mac with Apple Wallet set up. If it isn't available, checkout shows the customer one of these messages instead of the Apple Pay button:

Situation	Message shown to the customer
Unsupported browser	Open the page in Safari on an iPhone, iPad, or Mac to pay with Apple Pay.
Outdated device software	Update the device software and try again.
Apple Wallet not set up	Set up Apple Wallet and reload the page.
Apple Pay not configured for the checkout	Apple Pay is temporarily unavailable; try again later or contact support.

Confirm the result

Confirm the final result through your 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.