Rivoner API v1
Merchant Portal Get API Keys

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.

Base URL 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_.

HTTP Header
X-API-Key: riv_live_eb9f676265e94e335223e08d...
Supported authentication formats:
  • 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

1
Create Charge
Call POST /v1/charges with the USD amount. The API returns a hosted 3DS2 checkout URL.
2
Card Payment
Customer pays securely via Visa or Mastercard. 3DS2 confirms cardholder identity with issuing bank.
3
Crypto Settlement
Funds land directly in your crypto vault or auto-disburse to your wallet address with zero rolling reserves.
POST /v1/charges

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.

FieldTypeDescription
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
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]"
  }'
Node.js / TypeScript
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);
Sample Response (201 Created)
{
  "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"
}
GET /v1/charges/{id}

Retrieves the real-time status and settlement details for a specific charge by its 24-character hex ID.

cURL
curl -H "X-API-Key: riv_live_your_key_here" \
  https://api.rivoner.com/v1/charges/7a8f192b4c10e8293d014fbc
Sample Response (200 OK)
{
  "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"
}
GET /v1/charges

Returns your 50 most recent charges, sorted in descending order by creation date.

cURL
curl -H "X-API-Key: riv_live_your_key_here" \
  https://api.rivoner.com/v1/charges
Sample Response (200 OK)
{
  "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
}
GET /v1/balance

Retrieves cumulative merchant financials: total settled crypto volume, platform fees paid, and cleared charge count.

cURL
curl -H "X-API-Key: riv_live_your_key_here" \
  https://api.rivoner.com/v1/balance
Sample Response (200 OK)
{
  "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
}
GET /v1/me

Returns the authenticated merchant's business details, activation status, payout network, and receiving wallet address.

cURL
curl -H "X-API-Key: riv_live_your_key_here" \
  https://api.rivoner.com/v1/me
Sample Response (200 OK)
{
  "id": 14,
  "business_name": "Acme SaaS Ltd",
  "email": "[email protected]",
  "is_activated": true,
  "settle_asset": "USDT",
  "payout_network": "TRC20",
  "payout_wallet": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "environment": "live"
}
GET /v1/status

Checks gateway health and system operational status. Open to public clients without API key authentication.

Live Gateway Status Check
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.

HMAC-SHA512 Signature Verification:

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 Verification Snippet
<?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';
Copied to clipboard!