Initiate On-Ramp (with Customer)

Create a new customer and initiate an on-ramp transaction in a single call.

Creates a new customer record (or retrieves an existing one by email) and initiates a fiat-to-crypto on-ramp transaction.

Use this endpoint when you don't have a pre-existing customer in IvoryPay. If the customer already exists, use Initiate On-Ramp instead.

Endpoint

POST /v1/onramp

Authentication

Header	Value
x-api-key	Your API key

Request body

Field	Type	Required	Description
firstName	string	Yes	Customer's first name (min 1 character)
lastName	string	Yes	Customer's last name (min 1 character)
email	string	Yes	Customer's email address
phoneNumber	string	No	Customer's phone number (E.164 format)
walletAddress	string	Yes	Destination crypto wallet address
blockchain	string	Yes	Blockchain network. See Supported Blockchains
reference	string	Yes	Your unique reference for this transaction
token	string	Yes	Cryptocurrency to receive. See Supported Networks & Tokens
fiatCurrency	string	Yes	Fiat currency to pay in. See Supported Currencies
fiatAmount	number	No*	Amount in fiat the user will pay
cryptoAmount	number	No*	Amount in crypto the user will receive
businessFeeInFiat	number	No	Your business fee in fiat
redirectUrl	string	No	URL to redirect user after checkout payment
note	string	No	Optional note attached to the transaction

* You must provide either fiatAmount or cryptoAmount, but not both.

Example request

cURL

curl -X POST https://ramp-api.ivorypay.io/api/v1/onramp \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Amina",
    "lastName": "Okafor",
    "email": "[e-mail]",
    "phoneNumber": "[phone]",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68",
    "blockchain": "BSC_MAINNET",
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "token": "USDT",
    "fiatCurrency": "NGN",
    "fiatAmount": 50000
  }'

Node.js

Python

Go

Example response

{
  "statusCode": 200,
  "success": true,
  "message": "On-ramp initiated successfully",
  "data": {
    "firstName": "Amina",
    "lastName": "Okafor",
    "email": "[e-mail]",
    "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"
    }
  }
}

Response fields

Field	Type	Description
refCode	string	IvoryPay's unique customer reference
reference	string	Your transaction reference
transferDetails.accountName	string	Virtual bank account name for payment
transferDetails.accountNumber	string	Virtual bank account number
transferDetails.bank	string	Bank name for the virtual account
transferDetails.amountPayable	number	Exact fiat amount the user must pay
transferDetails.expiresAt	string	ISO 8601 expiry time for the payment session
transferDetails.currency	string	Fiat currency
transferDetails.businessFee	number	Your business fee
transferDetails.platformFee	number	IvoryPay platform fee
transferDetails.gasFee	number	Blockchain gas fee
transferDetails.checkoutUrl	string	Hosted checkout page URL
transferDetails.cryptoAmount	number	Crypto amount the user will receive

Related webhooks

• onramp.fiatPaymentReceived — Fiat payment confirmed

• onramp.cryptoPayoutProcessing — Crypto payout in progress

• onramp.success — Transaction completed

• onramp.failed — Transaction failed