Confirm On-Ramp Checkout

Confirm a pending on-ramp from the hosted checkout (called by the checkout UI).

Confirms a PENDING on-ramp created via Initiate On-Ramp Checkout. On success the transaction moves to INITIATED and the response contains the virtual account / payment details the customer pays into.

You usually do not call this endpoint. The IvoryPay hosted checkout calls it on the customer's behalf after they authenticate (email OTP → customer JWT). It's documented here so you understand the lifecycle, and for the case where you build your own checkout UI on top of the API.

Endpoint

POST /v1/onramp/:reference/checkout/confirm

:reference is the reference returned by checkout/initiate.

Authentication

Protected by HybridCheckoutHTTPAuthGuard — accepts any of:

Credential type	Header value	Notes
Customer JWT	Authorization: Bearer <jwt>	The standard hosted-checkout path
Business-user JWT	Authorization: Bearer <jwt>	When a dashboard user drives checkout
Merchant API key	Authorization: <api_key>	Server-to-server

Under a customer JWT, the on-ramp is scoped to that customer — they can only confirm their own transactions. See Customer authentication.

Request body

Field	Type	Required	Description
walletAddress	string	No	Override the destination wallet. If omitted, the address supplied at checkout/initiate is used.
phoneNumber	string	Conditional	Required for mobile-money currencies (UGX, GHS, KES, …) when the customer has no phone number on file. Persisted to the customer for future on-ramps.

For bank-transfer currencies (NGN, ZAR, USD) no extra fields are needed — an empty body {} is valid if the wallet address was set at initiate.

Example request

Bank transfer (NGN)

curl -X POST \
  https://ramp-api.ivorypay.io/api/v1/onramp/550e8400-e29b-41d4-a716-446655440000/checkout/confirm \
  -H "Authorization: Bearer <customer_jwt>" \
  -H "Content-Type: application/json" \
  -d '{}'

Mobile money (UGX)

Example response

Returns 200 OK. The transferDetails are now fully populated.

{
  "success": true,
  "message": "On-ramp confirmed",
  "data": {
    "firstName": "Amina",
    "lastName": "Okafor",
    "email": "[e-mail]",
    "phoneNumber": "[phone]",
    "refCode": "abc123def4",
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "transferDetails": {
      "accountName": "IvoryPay - Amina Okafor",
      "accountNumber": "1234567890",
      "bank": "Providus Bank",
      "amountPayable": 50000,
      "expiresAt": "2026-03-26T13:00:00.000Z",
      "currency": "NGN",
      "businessFee": 0,
      "platformFee": 250,
      "gasFee": 0.5,
      "createdAt": "2026-03-26T12:00:00.000Z",
      "checkoutUrl": "https://checkout.ivorypay.io/pay/abc123",
      "cryptoAmount": 31.25,
      "status": "INITIATED",
      "blockchain": "POLYGON",
      "token": "USDT",
      "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68"
    }
  }
}

For mobile-money currencies, the customer pays from their wallet rather than a bank account — accountNumber/bank may be absent and the customer is directed via checkoutUrl / an in-app prompt instead. Always render whichever of accountNumber / checkoutUrl is present.

Response fields

Field	Type	Description
firstName, lastName, email, phoneNumber	string	Customer identity
refCode	string	IvoryPay's customer reference
reference	string	Your transaction reference
transferDetails.accountName	string	Virtual account holder name (bank-transfer rails)
transferDetails.accountNumber	string	Virtual account number to pay into
transferDetails.bank	string	Bank name for the virtual account
transferDetails.amountPayable	number	Exact fiat amount to pay
transferDetails.expiresAt	string	ISO 8601 expiry of the payment session
transferDetails.currency	string	Fiat currency
transferDetails.businessFee	number	Your fee
transferDetails.platformFee	number	IvoryPay platform fee
transferDetails.gasFee	number	Blockchain gas fee
transferDetails.checkoutUrl	string	Hosted payment page (used for mobile-money / card-style collection)
transferDetails.cryptoAmount	number	Crypto the customer receives
transferDetails.status	string	INITIATED after a successful confirm
transferDetails.blockchain	string	Destination blockchain
transferDetails.token	string	Destination token
transferDetails.walletAddress	string	Destination wallet (post-override)

Getting a customer JWT

The hosted checkout obtains a customer JWT via email OTP. If you're building your own UI:

1. POST /v1/auth/customer-twofactor — body { "email": "...", "context": "LIVE" }. Emails a 6-digit code.

2. POST /v1/auth/customer-twofactor/verify — body { "token": "123456" }. Returns data.jwt.accessToken.

Send that token as Authorization: Bearer <accessToken> on the confirm call.

Errors

HTTP	When
401 CUSTOMER_CONTEXT_REQUIRED	No customer context (confirm requires a customer JWT under the customer path)
404	No PENDING on-ramp matches this reference for the caller
403 CUSTOMER_KYC_REQUIRED	KYC re-check failed
400	Mobile-money currency but no phone number on file or in the body

Related

• Initiate On-Ramp Checkout

• Get On-Ramp Status

• Hosted Checkout guide