Get On-Ramp Status

Check the current status of an on-ramp transaction.

Retrieves the current status and details of an on-ramp transaction by its reference.

Endpoint

GET /v1/onramp/status/:reference

Authentication

This endpoint is protected by the HybridCheckoutHTTPAuthGuard, which accepts any of the following credential types in the Authorization header:

Credential type	Header value	Use case
Merchant API key	Authorization: <api_key>	Server-to-server calls from your backend
Business-user JWT	Authorization: Bearer <jwt>	Calls made by an authenticated dashboard/business user
Customer JWT	Authorization: Bearer <jwt>	Calls made by an authenticated end-customer

Path parameters

Parameter	Type	Description
reference	string	Your unique transaction reference

Example request

cURL

curl -X GET https://ramp-api.ivorypay.io/api/v1/onramp/status/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: your_api_key"

Node.js

const response = await fetch(
  "https://ramp-api.ivorypay.io/api/v1/onramp/status/550e8400-e29b-41d4-a716-446655440000",
  {
    method: "GET",
    headers: {
      "Authorization": "your_api_key",
    },
  }
);

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

Python

import requests

response = requests.get(
    "https://ramp-api.ivorypay.io/api/v1/onramp/status/550e8400-e29b-41d4-a716-446655440000",
    headers={
        "Authorization": "your_api_key",
    },
)

print(response.json())

Go

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://ramp-api.ivorypay.io/api/v1/onramp/status/550e8400-e29b-41d4-a716-446655440000", nil)
	req.Header.Set("Authorization", "your_api_key")

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

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

Example response

Returns 200 OK.

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

Response fields

Field	Type	Description
firstName	string	Customer's first name
lastName	string	Customer's last name
email	string	Customer's email address
refCode	string	IvoryPay's unique customer reference
reference	string	Your transaction reference
transferDetails.accountName	string | null	Virtual bank account name used for payment (NGN/USD). null for ZAR and mobile-money currencies
transferDetails.accountNumber	string | null	Virtual bank account number (NGN/USD). null for ZAR and mobile-money currencies
transferDetails.bank	string | null	Bank name for the virtual account (NGN/USD). null for ZAR and mobile-money currencies
transferDetails.amountPayable	number	Fiat amount the customer was required to 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.createdAt	string	ISO 8601 creation timestamp
transferDetails.checkoutUrl	string | null	Hosted checkout page URL. Populated for ZAR (there's no virtual account — redirect the customer here) and for mobile-money currencies; null for NGN/USD
transferDetails.cryptoAmount	number	Crypto amount delivered (or to be delivered)
transferDetails.status	string	Current transaction status (see below)

The sample response above is for NGN (checkoutUrl: null). For ZAR, accountName/accountNumber/bank come back null instead and checkoutUrl is populated — poll this endpoint (or wait for the webhook) and branch on whichever field is present rather than assuming every BANK_TRANSFER currency looks like NGN.

Transaction statuses

Status	Description
INITIATED	Transaction created, awaiting payment
PENDING	Payment session active
FIAT_PAYMENT_RECEIVED	Fiat payment confirmed
CRYPTO_PAYOUT_PROCESSING	Crypto being sent to wallet
SUCCESS	Crypto delivered — transaction complete
FAILED	Transaction failed
EXPIRED	Payment session expired
CANCELLED	Transaction was cancelled

While you can poll this endpoint, we strongly recommend using webhooks for real-time status updates.