Rivoner REST API
Accept credit and debit cards (Visa & Mastercard) programmatically. Every completed transaction converts and settles automatically to your chosen crypto wallet (USDT, USDC, BTC, etc.) with a flat 1.5% fee and zero rolling reserves.
https://api.rivoner.com/v1
API Key Authentication
Authenticate requests by providing your Secret Key in the X-API-Key request header. Live keys start with riv_live_ and test keys start with riv_test_.
X-API-Key: riv_live_eb9f676265e94e335223e08d...
X-API-Key: riv_live_...(Recommended)Authorization: Bearer riv_live_...- HTTP Basic Auth username:
curl -u riv_live_...: https://api.rivoner.com/v1/...
How Settlement Works
POST /v1/charges with the USD amount. The API returns a hosted 3DS2 checkout URL.
Creates a credit card payment invoice. Returns a 24-character charge ID and a hosted 3DS2 checkout link (checkout_url) to redirect your customer or embed in an iframe.
| Field | Type | Description |
|---|---|---|
amount |
number | Required. The charge amount in USD (between 1.00 and 50000.00). |
title |
string | Required. Order title or product name displayed to the customer. |
customer_email |
string | Optional. Customer email address for card transaction confirmation. |
description |
string | Optional. Order details or internal reference memo. |
currency |
string | Optional. Settlement base currency. Default: USD. |
curl -X POST https://api.rivoner.com/v1/charges \
-H "X-API-Key: riv_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"amount": 100.00,
"title": "Cloud Hosting - Plan Pro",
"customer_email": "[email protected]"
}'
const response = await fetch('https://api.rivoner.com/v1/charges', {
method: 'POST',
headers: {
'X-API-Key': 'riv_live_your_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: 100.00,
title: 'Cloud Hosting - Plan Pro',
customer_email: '[email protected]'
})
});
const charge = await response.json();
console.log('Customer Checkout Link:', charge.checkout_url);
{
"id": "7a8f192b4c10e8293d014fbc",
"object": "charge",
"amount": 100.00,
"currency": "USD",
"fee": 1.50,
"net_settlement": 98.50,
"settle_asset": "USDT",
"title": "Cloud Hosting - Plan Pro",
"customer_email": "[email protected]",
"status": "pending",
"checkout_url": "https://rivoner.com/pay/7a8f192b4c10e8293d014fbc",
"created_at": "2026-10-13T20:10:00Z"
}
Retrieves the real-time status and settlement details for a specific charge by its 24-character hex ID.
curl -H "X-API-Key: riv_live_your_key_here" \
https://api.rivoner.com/v1/charges/7a8f192b4c10e8293d014fbc
{
"id": "7a8f192b4c10e8293d014fbc",
"object": "charge",
"title": "Cloud Hosting - Plan Pro",
"amount": 100.00,
"currency": "USD",
"fee": 1.50,
"status": "paid",
"customer_email": "[email protected]",
"paid_at": "2026-10-13T20:12:45Z",
"created_at": "2026-10-13T20:10:00Z",
"checkout_url": "https://rivoner.com/pay/7a8f192b4c10e8293d014fbc"
}
Returns your 50 most recent charges, sorted in descending order by creation date.
curl -H "X-API-Key: riv_live_your_key_here" \
https://api.rivoner.com/v1/charges
{
"object": "list",
"data": [
{
"id": "7a8f192b4c10e8293d014fbc",
"object": "charge",
"title": "Cloud Hosting - Plan Pro",
"amount": 100.00,
"currency": "USD",
"status": "paid",
"customer_email": "[email protected]",
"paid_at": "2026-10-13T20:12:45Z",
"created_at": "2026-10-13T20:10:00Z",
"checkout_url": "https://rivoner.com/pay/7a8f192b4c10e8293d014fbc"
}
],
"has_more": false
}
Retrieves cumulative merchant financials: total settled crypto volume, platform fees paid, and cleared charge count.
curl -H "X-API-Key: riv_live_your_key_here" \
https://api.rivoner.com/v1/balance
{
"object": "balance",
"settle_asset": "USDT",
"payout_network": "TRC20",
"payout_wallet": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"total_settled": 4826.50,
"gross_volume": 4900.00,
"fees_paid": 73.50,
"cleared_charges": 49
}
Returns the authenticated merchant's business details, activation status, payout network, and receiving wallet address.
curl -H "X-API-Key: riv_live_your_key_here" \
https://api.rivoner.com/v1/me
{
"id": 14,
"business_name": "Acme SaaS Ltd",
"email": "[email protected]",
"is_activated": true,
"settle_asset": "USDT",
"payout_network": "TRC20",
"payout_wallet": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"environment": "live"
}
Checks gateway health and system operational status. Open to public clients without API key authentication.
Click "Execute Ping" to test live connectivity.
Webhooks & IPN
When your customer completes their card payment on 3DS2 checkout, Rivoner dispatches an automated HTTP POST notification to your configured webhook endpoint.
Rivoner signs all webhook payloads with HMAC-SHA512 using your Webhook Secret. Verify the signature against the x-nowpayments-sig header on incoming requests before fulfilling customer orders.
<?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_NOWPAYMENTS_SIG'] ?? '';
$secret = 'YOUR_WEBHOOK_SECRET';
$expected = hash_hmac('sha512', $payload, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(400);
exit('Invalid signature');
}
$event = json_decode($payload, true);
if (($event['payment_status'] ?? '') === 'finished') {
// Payment confirmed — deliver product or activate customer subscription
}
http_response_code(200);
echo 'OK';