Initiate On-Ramp Checkout

Create a hosted on-ramp checkout session and get a redirect URL.

Creates a PENDING on-ramp transaction and returns a hosted checkout URL. You call this from your backend, then redirect your customer to the returned checkoutUrl. The hosted checkout collects the rest, runs KYC, and provisions the payment details.

Use this when you want IvoryPay to host the payment experience. For a single server-to-server call that returns the virtual account directly, use Initiate On-Ramp instead. For the full lifecycle, see the Hosted Checkout guide.

Endpoint

POST /v1/onramp/checkout/initiate

Authentication

Protected by HybridHTTPAuthGuard — accepts either credential in the Authorization header:

Credential type

Header value

Use case

Merchant API key

Authorization: <api_key>

Server-to-server (recommended)

Business-user JWT

Authorization: Bearer <jwt>

Authenticated dashboard/business user

Request body

The customer must already exist in IvoryPay (resolved by email). To create a customer inline, use Initiate On-Ramp (with Customer).

Field

Type

Required

Description

email

string

Yes

Customer's email address. Must match an existing customer.

walletAddress

string

Yes

Destination crypto wallet address. The customer can override this at checkout.

blockchain

string

Yes

Blockchain network. See Supported Blockchains

reference

string (UUID)

Yes

Your unique reference for this transaction. Must be a UUID.

token

string

Yes

Cryptocurrency to receive. See Supported Networks & Tokens

fiatCurrency

string

Yes

Fiat currency the customer pays in. Determines the payment rail. See Supported Currencies

fiatAmount

number

No*

Amount in fiat the customer will pay

cryptoAmount

number

No*

Amount in crypto the customer will receive

businessFeeInFiat

number

Your fee in fiat. Omit or send 0 if not charging a fee

businessFeeInCrypto

number

Your fee in crypto (alternative to businessFeeInFiat)

phoneNumber

string

Customer phone (E.164). Required later at confirm for mobile-money currencies if the customer has none on file

redirectUrl

string

URL to send the customer to after they complete payment

note

string

Optional note attached to the transaction

* Provide either fiatAmount or cryptoAmount, not both.

Payment rail note

You don't pass the rail — it's derived from fiatCurrency:

NGN / ZAR / USD → bank transfer. At checkout the customer receives a virtual account to pay into.
UGX, GHS, KES, … → mobile money. The customer pays from their mobile-money wallet; a phone number is required at confirm.

See Payment method types.

Example request

curl -X POST https://ramp-api.ivorypay.io/api/v1/onramp/checkout/initiate \
  -H "Authorization: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "amina@example.com",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68",
    "blockchain": "POLYGON",
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "token": "USDT",
    "fiatCurrency": "NGN",
    "fiatAmount": 50000,
    "businessFeeInFiat": 0,
    "redirectUrl": "https://yourapp.com/payment/done"
  }'

const response = await fetch(
  "https://ramp-api.ivorypay.io/api/v1/onramp/checkout/initiate",
  {
    method: "POST",
    headers: {
      Authorization: "your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: "amina@example.com",
      walletAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68",
      blockchain: "POLYGON",
      reference: crypto.randomUUID(),
      token: "USDT",
      fiatCurrency: "NGN",
      fiatAmount: 50000,
      businessFeeInFiat: 0,
      redirectUrl: "https://yourapp.com/payment/done",
    }),
  },
);

const { data } = await response.json();
// Redirect your customer:
window.location.href = data.checkoutUrl;

import requests, uuid

response = requests.post(
    "https://ramp-api.ivorypay.io/api/v1/onramp/checkout/initiate",
    headers={
        "Authorization": "your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "email": "amina@example.com",
        "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68",
        "blockchain": "POLYGON",
        "reference": str(uuid.uuid4()),
        "token": "USDT",
        "fiatCurrency": "NGN",
        "fiatAmount": 50000,
        "businessFeeInFiat": 0,
        "redirectUrl": "https://yourapp.com/payment/done",
    },
)

print(response.json()["data"]["checkoutUrl"])

Example response

Returns 201 Created.

{
  "success": true,
  "message": "Query successful",
  "data": {
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "checkoutUrl": "https://checkout.ivorypay.io/onramp/550e8400-e29b-41d4-a716-446655440000",
    "status": "PENDING"
  }
}

Response fields

Field

Type

Description

reference

string

Your transaction reference (echoed back)

checkoutUrl

string

Hosted checkout page — redirect your customer here

status

string

Always PENDING at this stage

Idempotency

Retrying with the same reference while the transaction is still PENDING returns the same checkoutUrl and status. Once it has moved past PENDING, the same reference returns 409 DUPLICATE_TRANSACTION.

Errors

HTTP

When

404 CUSTOMER_NOT_FOUND

email doesn't match a customer — use Initiate On-Ramp (with Customer)

403 CUSTOMER_KYC_REQUIRED

Customer hasn't completed required KYC

409 DUPLICATE_TRANSACTION

reference already used past PENDING — generate a new UUID

400

fiatAmount and cryptoAmount both set (or both missing), or amount outside allowed limits

Next step

The hosted checkout calls Confirm On-Ramp Checkout on the customer's behalf. You're notified of the outcome via webhooks.

PreviousInitiate On-Ramp NextConfirm On-Ramp Checkout

Last updated 1 month ago