Initiate On-Ramp

Initiate an on-ramp transaction for an existing customer.

Initiates a fiat-to-crypto on-ramp transaction for a customer that already exists in your IvoryPay account.

Endpoint

POST /v1/onramp/initiate

Authentication

This endpoint accepts any one of three credentials in the Authorization header:

Credential	Header value
Merchant API key	Authorization: <api_key>
Business-user JWT	Authorization: Bearer <jwt>
Customer JWT	Authorization: Bearer <jwt>

When a customer JWT is used, the request is scoped to that customer.

Request body

Field	Type	Required	Description
email	string	Yes	Existing 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 (must be a UUID)
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
cryptoAmount	number	No*	Amount in crypto
businessFeeInFiat	number	No	Your business fee in fiat. Send 0 (or omit) if you are not charging a fee
businessFeeInCrypto	number	No	Your business fee in crypto. Pair with cryptoAmount
redirectUrl	string	No	Redirect URL after checkout
note	string	No	Transaction note

* Provide either fiatAmount + businessFeeInFiat OR cryptoAmount + businessFeeInCrypto. Mixing a fiat amount with a crypto fee (or vice versa) is rejected by validation. The reference must be a valid UUID on this endpoint.

fiatCurrency: "ZAR" — you must redirect the customer

For most BANK_TRANSFER currencies (NGN, USD) the response gives you a virtual account (accountName/accountNumber/bank) to display. ZAR is the exception: the fiat-payment provider hands back a hosted checkout page instead, so accountName/accountNumber/bank come back null and transferDetails.checkoutUrl is populated. You must redirect (or embed) the customer at checkoutUrl yourself — since you're on the direct endpoint rather than the hosted checkout flow, nothing does this for you. Always branch on which field is present rather than assuming NGN's shape applies to every BANK_TRANSFER currency.

Example request

cURL

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

Node.js

const response = await fetch("https://ramp-api.ivorypay.io/api/v1/onramp/initiate", {
  method: "POST",
  headers: {
    "Authorization": "your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "[e-mail]",
    walletAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68",
    blockchain: "BSC_MAINNET",
    reference: "550e8400-e29b-41d4-a716-446655440000",
    token: "USDT",
    fiatCurrency: "NGN",
    fiatAmount: 50000,
  }),
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    "https://ramp-api.ivorypay.io/api/v1/onramp/initiate",
    headers={
        "Authorization": "your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "email": "[e-mail]",
        "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68",
        "blockchain": "BSC_MAINNET",
        "reference": "550e8400-e29b-41d4-a716-446655440000",
        "token": "USDT",
        "fiatCurrency": "NGN",
        "fiatAmount": 50000,
    },
)

print(response.json())

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]interface{}{
		"email":         "[e-mail]",
		"walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68",
		"blockchain":    "BSC_MAINNET",
		"reference":     "550e8400-e29b-41d4-a716-446655440000",
		"token":         "USDT",
		"fiatCurrency":  "NGN",
		"fiatAmount":    50000,
	})

	req, _ := http.NewRequest("POST", "https://ramp-api.ivorypay.io/api/v1/onramp/initiate", bytes.NewBuffer(body))
	req.Header.Set("Authorization", "your_api_key")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}

Example response

Returns HTTP 201 Created.

{
  "success": true,
  "message": "Query successful",
  "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,
      "businessFee": 0,
      "platformFee": 250,
      "gasFee": 0.5,
      "expiresAt": "2026-03-26T13:00:00.000Z",
      "currency": "NGN",
      "checkoutUrl": null,
      "createdAt": "2026-03-26T12:00:00.000Z",
      "cryptoAmount": 31.25
    }
  }
}

For fiatCurrency: "ZAR", the shape flips — accountName/accountNumber/bank are null and checkoutUrl is populated:

{
  "success": true,
  "message": "Query successful",
  "data": {
    "firstName": "Amina",
    "lastName": "Okafor",
    "email": "[e-mail]",
    "refCode": "abc123def4",
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "transferDetails": {
      "accountName": null,
      "accountNumber": null,
      "bank": null,
      "amountPayable": 1000,
      "businessFee": 0,
      "platformFee": 5,
      "gasFee": 0.5,
      "expiresAt": "2026-03-26T13:00:00.000Z",
      "currency": "ZAR",
      "checkoutUrl": "https://checkout.ivorypay.io/onramp/550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-03-26T12:00:00.000Z",
      "cryptoAmount": 31.25
    }
  }
}

Redirect the customer to transferDetails.checkoutUrl to complete payment — there's no account number to display for ZAR.

Error cases

Error code	Description
ONOFFRAMP0053	Customer not found — use the with-customer endpoint instead