Initiate Off-Ramp Checkout

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

Creates a PENDING off-ramp transaction and returns a hosted checkout URL. You call this from your backend, then redirect your customer to the returned checkoutUrl. At the hosted page the customer selects (or adds) the bank / mobile-money account that receives the payout, then confirms.

Unlike Initiate Off-Ramp, you do not pass bank details here — the customer chooses a payout destination at checkout. For the full lifecycle, see the Hosted Checkout guide.

Endpoint

POST /v1/offramp/checkout/initiate

Authentication

Protected by APIKeyHTTPAuthGuard — merchant API key only:

Authorization: your_api_key

Request body

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

Field	Type	Required	Description
email	string	Yes	Customer's email address. Must match an existing customer.
blockchain	string	Yes	Blockchain the customer sends crypto from. See Supported Blockchains
reference	string (UUID)	Yes	Your unique reference for this transaction. Must be a UUID.
token	string	Yes	Cryptocurrency the customer sends. See Supported Networks & Tokens
fiatCurrency	string	Yes	Fiat currency the customer receives. Determines the payout rail. See Supported Currencies
fiatAmount	number	No*	Amount in fiat the customer will receive
cryptoAmount	number	No*	Amount in crypto the customer will send
businessFeeInFiat	number	No	Your fee in fiat. Omit or send 0 if not charging a fee
businessFeeInCrypto	number	No	Your fee in crypto (alternative to businessFeeInFiat)
phoneNumber	string	No	Customer phone (E.164)
note	string	No	Optional note attached to the transaction

* Provide either fiatAmount or cryptoAmount, not both.

No bank fields. accountNumber, bankCode, etc. are intentionally absent — the customer picks a saved payout account at confirm time.

Payout rail note

The rail is derived from fiatCurrency. At checkout the customer must select a saved account whose type matches:

fiatCurrency	Saved account type	Receives via
NGN, ZAR, USD	BANK_TRANSFER	Bank account (NGN NIBSS, ZAR EFT)
UGX, KES, …	MOBILE_MONEY	Mobile-money wallet

See Customer Bank Accounts for how those are created.

Example request

cURL

curl -X POST https://ramp-api.ivorypay.io/api/v1/offramp/checkout/initiate \
  -H "Authorization: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "blockchain": "POLYGON",
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "token": "USDT",
    "fiatCurrency": "UGX",
    "cryptoAmount": 10,
    "businessFeeInCrypto": 0
  }'

Node.js

const response = await fetch(
  "https://ramp-api.ivorypay.io/api/v1/offramp/checkout/initiate",
  {
    method: "POST",
    headers: {
      Authorization: "your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: "[e-mail]",
      blockchain: "POLYGON",
      reference: crypto.randomUUID(),
      token: "USDT",
      fiatCurrency: "UGX",
      cryptoAmount: 10,
      businessFeeInCrypto: 0,
    }),
  },
);

const { data } = await response.json();
window.location.href = data.checkoutUrl;

Python

import requests, uuid

response = requests.post(
    "https://ramp-api.ivorypay.io/api/v1/offramp/checkout/initiate",
    headers={
        "Authorization": "your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "email": "[e-mail]",
        "blockchain": "POLYGON",
        "reference": str(uuid.uuid4()),
        "token": "USDT",
        "fiatCurrency": "UGX",
        "cryptoAmount": 10,
        "businessFeeInCrypto": 0,
    },
)

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/offramp/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 PENDING returns the same checkoutUrl and status. Once past PENDING, the same reference returns 409 DUPLICATE_TRANSACTION.

Errors

HTTP	When
404 CUSTOMER_NOT_FOUND	email doesn't match a customer — use Initiate Off-Ramp (with Customer)
403 CUSTOMER_KYC_REQUIRED	Customer hasn't completed required KYC
403 OFFRAMP_NOT_ENABLED	Off-ramp isn't enabled for your business
409 DUPLICATE_TRANSACTION	reference already used past PENDING
400	fiatAmount and cryptoAmount both set (or both missing), or amount outside allowed limits

Next step

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