Introduction

The OvoCheckout API follows RESTful architecture standards, offering clear and consistent resource-based endpoints. All requests and responses are transmitted in JSON format, leveraging standard HTTP verbs, status codes, and authentication protocols to enable secure, efficient, and scalable integrations.

API Base URL

Please note that OvoCheckout does not provide a sandbox or test environment. All API requests are processed in the live environment, so ensure that all request data and parameters are accurate before making any calls.

https://preview.ovosolution.com/ovocheckout/demo/api

Authentication

All requests to the OvoCheckout API require authentication. Each API request must include a valid client-id and client-secret to the request header, which can be obtained from your OvoCheckout Dashboard under Developer Tools.

In addition to credentials, OvoCheckout enforces IP-based security. You must register and enable your server’s public IP address in the IP Whitelist section of the dashboard. Requests originating from non-whitelisted IP addresses will be automatically rejected.

Both valid API credentials and an approved IP address are mandatory. Without completing these two steps, authentication will fail and API access will not be granted.

Response Format

All responses from the OvoCheckout API are returned in JSON format. Each response follows a consistent structure and includes a status indicator, message, and relevant data payload when applicable. Standard HTTP status codes are used to represent the outcome of each request.

Sample Success Response

{
"status": "success",
"remark": "invoice_created",
"message":[
    "Invoice created successfully"
],
"data": {
   ...you get all data here
    }
}

Error Sample Response

{
    "remark": "Unauthorized",
    "status": "error",
    "message": [
        "The client secret is required"
    ]
}

 {
    "remark": "Unauthorized",
    "status": "error",
    "message": [
        "Access to this API endpoint is restricted to IP addresses that have been explicitly whitelisted.",
        "In order to access this API endpoint, please add your IP address (::1) to the white list from the user dashboard."
    ]
}


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://preview.ovosolution.com/ovocheckout/demo/api/invoice-list',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Get Invoice List

This endpoint allows you to retrieve a complete list of invoices associated with your OvoCheckout account. Each invoice includes a status and a type. Please refer to the definitions below:

Invoice Status:
Unpaid = unpaid
Paid = paid
Partially Paid = partially_paid
Expired = expired

Invoice Type:
Crypto Invoice = crypto
Fiat Invoice = fiat

GET

invoice-list

Query Parameters

Query parameters that allow you to customize the API response.

Name	Description	Required	Default
`page`	Specifies the page number to retrieve.	No	1
`paginate`	Defines the number of items returned per page.	No	20
`search`	Search by invoice ID.	No	-

Sample Response

{
    "remark": "all_invoices",
    "status": "success",
    "message": ["Invoice records fetched successfully"],
    "data": {
        "invoices": {
            "current_page": 1,
                    "data": [
                {
                    "invoice_id": "INV-1712345678",
                    "amount": "100.00",
                    "paid_amount": "0.00",
                    "status": "unpaid",
                    "created_at": "2026-06-24T12:00:00.000000Z",
                    "merchant_trx": "TX123456",
                    "type": "crypto",
                    "currency_code": "USD",
                    "payments": [
                        {
                            "amount": "50.00",
                            "name": "John Doe",
                            "email": "[email protected]",
                            "mobile": "1234567890",
                            "status": "success",
                            "created_at": "2026-06-24T12:00:00.000000Z",
                            "trx": "TX-ABC-123"
                        }
                    ]
                }
            ],
            "per_page": 20,
            "total": 1
        }
    }
}


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://preview.ovosolution.com/ovocheckout/demo/api/invoice-details/:invoice_id',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Invoice Detail

This endpoint allows you to retrieve a invoice & related payments associated with your OvoCheckout account.

GET

invoice-details/{invoice_id}

Sample Response

{
    "remark": "invoice_detail",
    "status": "success",
    "message": ["Invoice details fetched successfully"],
                    "data": {
        "invoice": {
            "invoice_id": "INV-1712345678",
            "amount": "100.00",
            "paid_amount": "50.00",
            "status": "paid",
            "created_at": "2026-06-24T12:00:00.000000Z",
            "merchant_trx": "TX123456",
            "type": "crypto",
            "currency_code": "USD",
            "payments": [
                {
                    "amount": "50.00",
                    "name": "John Doe",
                    "email": "[email protected]",
                    "mobile": "1234567890",
                    "status": "success",
                    "created_at": "2026-06-24T12:00:00.000000Z",
                    "trx": "TX-ABC-123"
                }
            ]
        }
    }
}

Error Response

{
    "remark": "invoice_not_found",
    "status": "error",
    "message": ["The invoice is not found"]
}


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://preview.ovosolution.com/ovocheckout/demo/api/invoice-status/:invoice_id',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Invoice Payment Status

This endpoint allows you to retrieve a invoice status associated with your OvoCheckout account.

GET

invoice-status/{invoice_id}

Sample Response

{
    "remark": "invoice_status",
    "status": "success",
    "message": ["Invoice status retrieved successfully"],
                    "data": {
        "invoice": {
            "invoice_id": "INV-1712345678",
            "status": "unpaid"
        }
    }
}

Error Response

{
    "remark": "invoice_not_found",
    "status": "error",
    "message": ["The invoice is not found"]
}


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://preview.ovosolution.com/ovocheckout/demo/api/payment-list',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Get Payment List

This endpoint allows you to retrieve a complete list of payments associated with your OvoCheckout account and with invoice. Each payment includes a status. Please refer to the definitions below:

Payment Status:
Initiated = initiated
Success = success
Failed = rejected

GET

payment-list

Query Parameters

Query parameters that allow you to customize the API response.

Name	Description	Required	Default
`page`	Specifies the page number to retrieve.	No	1
`paginate`	Defines the number of items returned per page.	No	20
`search`	Search by payment ID/TRX.	No	-

Sample Response

{
    "remark": "all_payments",
    "status": "success",
    "message": ["Payments records fetched successfully"],
    "data": {
        "payments": {
            "current_page": 1,
                    "data": [
                {
                    "amount": "50.00",
                    "name": "John Doe",
                    "email": "[email protected]",
                    "mobile": "1234567890",
                    "status": "success",
                    "created_at": "2026-06-24T12:00:00.000000Z",
                    "trx": "TX-ABC-123",
                    "invoice": {
                        "invoice_id": "INV-1712345678",
                        "amount": "100.00",
                        "paid_amount": "50.00",
                        "status": "paid",
                        "merchant_trx": "TX123456",
                        "type": "crypto",
                        "currency_code": "USD"
                    }
                }
            ],
            "per_page": 20,
            "total": 1
        }
    }
}


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://preview.ovosolution.com/ovocheckout/demo/api/payment-status/payment_id',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Payment Status

This endpoint allows you to retrieve a payment status associated with your OvoCheckout account.

GET

payment-status/{payment_id}

Sample Response

{
    "remark": "payment_status",
    "status": "success",
    "message": ["Payment status retrieved successfully"],
                    "data": {
        "payment": {
            "status": "success",
            "amount": "50.00",
            "trx": "TX-ABC-123"
        }
    }
}

Error Response

{
    "remark": "payment_not_found",
    "status": "error",
    "message": ["The payment is not found"]
}


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://preview.ovosolution.com/ovocheckout/demo/api/supported-currencies',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Get Platform Supported Currencies

This endpoint allows you to retrieve a complete list of OvoCheckout supported currencies. You can use this endpoint at any time to get all currently supported currencies with their types and limits. Below is the full list of currencies you can accept payments in:

Name	Code	Type	Min Limit	Max Limit
Bangladeshi Taka	`BDT`	fiat	100	100,000
US Dollar	`USD`	fiat	10	1,000
Bitcoin	`BTC`	crypto	0	2.85
Ethereum	`ETH`	crypto	0.003	71.768
Euro	`EUR`	fiat	10	10,000
Nigerian Naira	`NGN`	fiat	1,000	1,000,000
Saudi Rial	`SAR`	fiat	100	10,000
Tether TRC	`USDTTRC20`	crypto	14.592	253,683.448
Tether Ton	`USDTTON`	crypto	9.712	84,561.932
Solana	`SOL`	crypto	0.076	1,666.281
Dogecoin	`DOGE`	crypto	85.672	354,232.947
British Pound	`GBP`	fiat	10	10,000
Australian Dollar	`AUD`	fiat	50	10,000
Brazilian Real	`BRL`	fiat	10	100,000
Canadian dollar	`CAD`	fiat	5	10,000
Japanese yen	`JPY`	fiat	500	500,000
xrp	`XRP`	crypto	5.279	69,938.132
Litecoin	`LTC`	crypto	0.134	1,476.771
Bitcoin Cash	`BCH`	crypto	0.016	144.033
TRON	`TRX`	crypto	25.347	447,640.847
Paypal USD	`PYUSD`	crypto	7.448	630.578
Cardano	`ADA`	crypto	26.837	231,445.608

Currency Type:
Crypto Currency = crypto
Fiat Currency = fiat

GET

supported-currencies

Query Parameters

Query parameters that allow you to customize the API response.

Name	Description	Required	Default
`page`	Specifies the page number to retrieve.	No	1
`paginate`	Defines the number of items returned per page.	No	20
`search`	Search by currency name or code.	No	-

Sample Response

{
    "remark": "success",
    "status": "success",
    "message": ["Currencies fetched successfully"],
    "data": {
        "currencies": {
            "current_page": 1,
            "data": [
                {
                    "name": "US Dollar",
                    "code": "USD",
                    "type": "fiat",
                    "invoice_max_limit": "10000.00",
                    "invoice_min_limit": "1.00"
                },
                {
                    "name": "Bitcoin",
                    "code": "BTC",
                    "type": "crypto",
                    "invoice_max_limit": "10.00",
                    "invoice_min_limit": "0.0001"
                }
            ],
            "per_page": 20,
            "total": 2
        }
    }
}


$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://preview.ovosolution.com/ovocheckout/demo/api/payment-initiate',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_POST => true, // <- Use POST
    CURLOPT_POSTFIELDS => array(
        'amount'            => 100,
        'currency_code'     => 'USD',
        'merchant_trx'      => 'TX123456',
        'success_url'       => 'https://example.com/success',
        'failed_url'        => 'https://example.com/failed',
        'ipn_url'           => 'https://example.com/ipn',
        'description' => 'Payment for Order #9876',
    ),
    CURLOPT_HTTPHEADER => array(
        'client-id: YOUR-CLIENT-ID',
        'client-secret: YOUR-CLIENT-SECRET',
    ),
));

$response = curl_exec($curl);
curl_close($curl);
echo $response;

Create Invoice

This endpoint allows you to create an invoice on OvoCheckout to collect payment from your customers.

POST

payment-initiate

Required Fields

The following fields are required to create a new contact in the system.

Name	Required	Description
`amount`	Required	The total amount to be charged for the invoice.
`currency_code`	Required	The currency code (e.g., USD) in which the invoice will be processed.
`merchant_trx`	Required	A unique transaction reference provided by the merchant.
`success_url`	Required	The URL where the customer will be redirected after a successful payment.
`failed_url`	Required	The URL where the customer will be redirected if the payment fails.
`ipn_url`	Required	The endpoint URL that will receive Instant Payment Notification (IPN) callbacks. This URL is only called when payment is successful. The URL must accept POST method and exclude CSRF verification. See the IPN Setup section for full details.
`description`	Required	A brief description of the order or service associated with this invoice.

Sample Response

{
    "remark": "success",
    "status": "success",
    "message": ["Invoice created successfully"],
    "data": {
        "invoice_id": "244349350090663",
        "amount": "100.00000000",
        "currency_code": "USD",
        "status": "unpaid",
        "type": "fiat",
        "merchant_trx": "TX123456",
        "order_id": null,
        "description": "Payment for Order #9876",
        "payment_link": "https://example.com/payment/init/244349350090663"
    }
}

Error Responses

The following error responses may be returned:


{
    "remark": "validation_error",
    "status": "error",
    "message": [
        "The amount field is required.",
        "The currency_code field is required."
    ]
}


{
    "remark": "invalid_amount",
    "status": "error",
    "message": [
        "The amount must be greater than or equal to invoice minimum limit"
    ],
    "data": {
        "min_limit": "1.00"
    }
}


{
    "remark": "duplicate_merchant_trx",
    "status": "error",
    "message": [
        "The merchant transaction number has been already taken"
    ]
}

IPN (Instant Payment Notification)

The Instant Payment Notification (IPN) is a server-to-server callback that notifies your application in real-time when a payment is successfully processed.

How IPN Works

When a customer completes a payment for an invoice created via the API, our system sends an HTTP POST request to the ipn_url you provided during invoice creation. This happens automatically after the payment is confirmed.

IPN is only triggered for successful payments.
The IPN is sent once per successful payment.
The notification is sent server-to-server, so there is no browser session or CSRF token involved.

Setting Up Your IPN Endpoint

Your IPN endpoint must meet the following requirements:

Requirement	Details
HTTP Method	POST
Content Type	`application/json`
CSRF Protection	Must be excluded. The IPN is a server-to-server call with no browser session.
Authentication	Optional. You may verify the request by checking the `trx` or `merchant_trx` against your records.

IPN Payload

When a payment is successful, our system sends the following JSON payload to your ipn_url:

{
    "status": "success",
    "payment_status": "success",
    "invoice_status": "paid",
    "type": "crypto",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "1234567890",
    "message": "Payment processed successfully",
    "data": {
        "invoice_id": "INV-1712345678",
        "trx": "TX-ABC-123",
        "merchant_trx": "TX123456",
        "order_id": null,
        "amount": "50.00",
        "charge": "2.50",
        "method": "PayPal",
        "currency": {
            "code": "USD",
            "name": "US Dollar"
        },
        "date": "2026-06-24 12:00:00"
    }
}

Payload Fields Reference

Field	Type	Description
`status`	string	Always `success`. Indicates the IPN notification itself is valid.
`payment_status`	string	The payment status. Possible values: `initiated`, `success`, `pending`, `rejected`, `refunded`.
`invoice_status`	string	The invoice status. Possible values: `unpaid`, `paid`, `partially_paid`, `expired`.
`type`	string	The invoice type. Possible values: `fiat`, `crypto`.
`name`	string	The customer's name who made the payment.
`email`	string	The customer's email address.
`data.invoice_id`	string	The unique invoice ID.
`data.trx`	string	The system transaction ID for this payment.
`data.merchant_trx`	string	The merchant's transaction reference provided at invoice creation.
`data.order_id`	string	The merchant's order ID (if provided at invoice creation).
`data.amount`	number	The amount paid.
`data.charge`	number	The processing fee charged.
`data.method`	string	The payment method used (e.g., PayPal, Stripe, or Crypto Payment).
`data.currency.code`	string	The currency code (e.g., USD, BTC).
`data.date`	string	The date and time when the payment was processed.

Verifying IPN Requests

To ensure the IPN request is authentic, you can verify the trx or merchant_trx value against your records. The merchant_trx is your own reference, so matching it confirms the payment corresponds to the correct invoice.

A basic PHP example to handle the IPN:


$payload = json_decode(file_get_contents('php://input'), true);

if ($payload['status'] !== 'success') {
    http_response_code(400);
    exit;
}

$merchantTrx = $payload['data']['merchant_trx'];
$invoiceId   = $payload['data']['invoice_id'];
$amount      = $payload['data']['amount'];
$trx         = $payload['data']['trx'];

// Match merchant_trx with your records
if ($merchantTrx !== 'YOUR_STORED_REFERENCE') {
    http_response_code(400);
    exit;
}

// Update your order as paid
http_response_code(200);
echo 'OK';

Redirect vs IPN

After payment, the customer is redirected to your success_url or failed_url with query parameters. The IPN is sent separately to your ipn_url as a server-to-server call. You should rely on the IPN as the authoritative notification, since the customer's browser redirect can be intercepted or the customer may close the browser before the redirect completes.