> 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-off-ramp/initiate.md). # Initiate Off-Ramp Initiate an off-ramp transaction for an existing customer. Initiates a crypto-to-fiat off-ramp transaction for a customer that already exists in your IvoryPay account. ## Endpoint ``` POST /v1/offramp/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 ` | ## Request body | Field | Type | Required | Description | | --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `email` | string | Yes | Existing customer's email address | | `phoneNumber` | string | No | Customer's phone number (E.164 format) | | `accountNumber` | string | Yes | Recipient bank account number or mobile money number | | `bankCode` | string | No | Bank code for NGN bank payouts (use [List Banks](/ivorypay-on-off-ramp-documentation/api-reference-banks/list-banks.md) to get valid codes). Not required for mobile money payouts | | `blockchain` | string | Yes | Blockchain network | | `reference` | string | Yes | Your unique reference (must be a UUID) | | `token` | string | Yes | Cryptocurrency the user will send | | `fiatCurrency` | string | Yes | Fiat currency for payout | | `fiatAmount` | number | No\* | Fiat amount to be paid out | | `cryptoAmount` | number | No\* | Crypto amount to be sent | | `businessFeeInCrypto` | number | No | Your business fee in crypto. Pair with `cryptoAmount` | | `businessFeeInFiat` | number | No | Your business fee in fiat. Pair with `fiatAmount` | | `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 %} ## Example request {% tabs %} {% tab title="Bank (NGN)" %} ```bash curl -X POST https://ramp-api.ivorypay.io/api/v1/offramp/initiate \ -H "Authorization: your_api_key" \ -H "Content-Type: application/json" \ -d '{ "email": "chidi@example.com", "accountNumber": "0123456789", "bankCode": "058", "blockchain": "BSC_MAINNET", "reference": "660e8400-e29b-41d4-a716-446655440001", "token": "USDT", "fiatCurrency": "NGN", "fiatAmount": 100000 }' ``` {% endtab %} {% tab title="Mobile Money (UGX)" %} ```bash curl -X POST https://ramp-api.ivorypay.io/api/v1/offramp/initiate \ -H "Authorization: your_api_key" \ -H "Content-Type: application/json" \ -d '{ "email": "chidi@example.com", "phoneNumber": "+256772882926", "accountNumber": "256772882926", "blockchain": "STARKNET_MAINNET", "reference": "660e8410-f23c-41c4-a628-838625530891", "token": "USDT", "fiatCurrency": "UGX", "cryptoAmount": 1.5, "businessFeeInCrypto": 0.001 }' ``` {% endtab %} {% tab title="Node.js" %} ```javascript const response = await fetch("https://ramp-api.ivorypay.io/api/v1/offramp/initiate", { method: "POST", headers: { "Authorization": "your_api_key", "Content-Type": "application/json", }, body: JSON.stringify({ email: "chidi@example.com", accountNumber: "0123456789", bankCode: "058", blockchain: "BSC_MAINNET", reference: "660e8400-e29b-41d4-a716-446655440001", token: "USDT", fiatCurrency: "NGN", fiatAmount: 100000, }), }); 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/offramp/initiate", headers={ "Authorization": "your_api_key", "Content-Type": "application/json", }, json={ "email": "chidi@example.com", "accountNumber": "0123456789", "bankCode": "058", "blockchain": "BSC_MAINNET", "reference": "660e8400-e29b-41d4-a716-446655440001", "token": "USDT", "fiatCurrency": "NGN", "fiatAmount": 100000, }, ) 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": "chidi@example.com", "accountNumber": "0123456789", "bankCode": "058", "blockchain": "BSC_MAINNET", "reference": "660e8400-e29b-41d4-a716-446655440001", "token": "USDT", "fiatCurrency": "NGN", "fiatAmount": 100000, }) req, _ := http.NewRequest("POST", "https://ramp-api.ivorypay.io/api/v1/offramp/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": "Chidi", "lastName": "Nwankwo", "email": "chidi@example.com", "refCode": "xyz789abc0", "reference": "660e8400-e29b-41d4-a716-446655440001", "transferDetails": { "token": "USDT", "blockchain": "BSC_MAINNET", "amountPayable": 62.5, "businessFee": 0, "platformFee": 0.3, "walletAddress": "0xIvoryPayDepositAddress...", "createdAt": "2026-03-26T12:00:00.000Z", "fiatAmount": 100000, "expiresAt": "2026-03-26T13:00:00.000Z", "sessionId": "session_xyz789", "duration": 3600 } } } ``` ## Sandbox behaviour {% hint style="info" %} Off-ramp token access is provisioned per API key. If your sandbox key has not been enabled for a specific token/blockchain combination, you will receive: `ONOFFRAMP0024 — "You do not have access to this token, please contact support"` Contact support to request that specific tokens and networks be enabled for your sandbox key. See [Supported Networks & Tokens](/ivorypay-on-off-ramp-documentation/resources/supported-blockchains.md) for the full list of available sandbox combinations. {% endhint %} ## Error cases | Error code | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `ONOFFRAMP0053` | Customer not found — use the [with-customer endpoint](/ivorypay-on-off-ramp-documentation/api-reference-off-ramp/initiate-with-customer.md) | | `ONOFFRAMP0033` | Invalid bank code | | `ONOFFRAMP0024` | Token not enabled for your account — contact support to enable the token/blockchain pair |