> For the complete documentation index, see [llms.txt](https://ivorypay.gitbook.io/ivorypay-on-off-ramp-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ivorypay.gitbook.io/ivorypay-on-off-ramp-documentation/api-reference-on-ramp/initiate.md). # 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: ` | | Business-user JWT | `Authorization: Bearer ` | | Customer JWT | `Authorization: Bearer ` | 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](/ivorypay-on-off-ramp-documentation/resources/supported-blockchains.md) | | `reference` | string | Yes | Your unique reference (must be a UUID) | | `token` | string | Yes | Cryptocurrency to receive. See [Supported Networks & Tokens](/ivorypay-on-off-ramp-documentation/resources/supported-blockchains.md) | | `fiatCurrency` | string | Yes | Fiat currency to pay in. See [Supported Currencies](/ivorypay-on-off-ramp-documentation/resources/supported-currencies.md) | | `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 | {% hint style="warning" %} **\*** 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. {% endhint %} ### `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](/ivorypay-on-off-ramp-documentation/guides/hosted-checkout.md) 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 {% tabs %} {% tab title="cURL" %} ```bash curl -X POST https://ramp-api.ivorypay.io/api/v1/onramp/initiate \ -H "Authorization: your_api_key" \ -H "Content-Type: application/json" \ -d '{ "email": "amina@example.com", "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68", "blockchain": "BSC_MAINNET", "reference": "550e8400-e29b-41d4-a716-446655440000", "token": "USDT", "fiatCurrency": "NGN", "fiatAmount": 50000 }' ``` {% endtab %} {% tab title="Node.js" %} ```javascript 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: "amina@example.com", 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); ``` {% endtab %} {% tab title="Python" %} ```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": "amina@example.com", "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68", "blockchain": "BSC_MAINNET", "reference": "550e8400-e29b-41d4-a716-446655440000", "token": "USDT", "fiatCurrency": "NGN", "fiatAmount": 50000, }, ) print(response.json()) ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "bytes" "encoding/json" "fmt" "io" "net/http" ) func main() { body, _ := json.Marshal(map[string]interface{}{ "email": "amina@example.com", "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)) } ``` {% endtab %} {% endtabs %} ## Example response Returns HTTP `201 Created`. ```json { "success": true, "message": "Query successful", "data": { "firstName": "Amina", "lastName": "Okafor", "email": "amina@example.com", "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: ```json { "success": true, "message": "Query successful", "data": { "firstName": "Amina", "lastName": "Okafor", "email": "amina@example.com", "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](/ivorypay-on-off-ramp-documentation/api-reference-on-ramp/initiate-with-customer.md) instead |