Payment Management

The Crypto Payment Gateway includes powerful tools to manage, track, and analyze your payments.

Payment List

Get a paginated list of all payments for your business with filtering options.

Endpoint

http

GET /api/v1/checkout/list

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by status (`pending`, `paid`, `expired`, `failed`)
`payment_method`	string	No	Filter by method (`crypto`, `fiat`)
`page`	integer	No	Page number (default: 1)
`limit`	integer	No	Results per page (default: 50, max: 100)

Request Example

cURLJavaScriptPython

bash

curl -X GET 'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/checkout/list?status=paid&page=1&limit=50' \
  -H "X-API-Key: YOUR_API_KEY"

javascript

const response = await fetch(
  'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/checkout/list?status=paid&page=1&limit=50',
  {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  }
);

const data = await response.json();
console.log(`Total payments: ${data.total}`);

python

import requests

response = requests.get(
    'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/checkout/list',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    params={'status': 'paid', 'page': 1, 'limit': 50}
)

data = response.json()
print(f"Total payments: {data['total']}")

Response

json

{
  "payments": [
    {
      "id": 123,
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "reference": "ORDER-12345",
      "amount": 100.00,
      "currency": "USDT",
      "network": "BSC",
      "status": "paid",
      "payment_method": "crypto",
      "deposit_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "blockchain_tx_hash": "0x123abc...",
      "customer_email": "customer@example.com",
      "created_at": "2025-12-29T10:00:00Z",
      "paid_at": "2025-12-29T10:05:23Z",
      "expires_at": "2025-12-29T10:15:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 50
}

Payment Statistics

Get comprehensive statistics about your payment volume and performance.

Endpoint

http

GET /api/v1/checkout/stats

Request Example

cURLJavaScript

bash

curl -X GET 'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/checkout/stats' \
  -H "X-API-Key: YOUR_API_KEY"

javascript

const response = await fetch(
  'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/checkout/stats',
  {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  }
);

const stats = await response.json();
console.log('Total Volume:', stats.total_volume);

Response

json

{
  "total_payments": 250,
  "pending_payments": 15,
  "paid_payments": 200,
  "expired_payments": 25,
  "failed_payments": 10,
  "total_volume": {
    "USDT": 50000.00,
    "USDC": 30000.00,
    "NGN": 5000000.00
  },
  "today_volume": {
    "USDT": 5000.00,
    "USDC": 3000.00
  },
  "this_month_volume": {
    "USDT": 25000.00,
    "USDC": 15000.00,
    "NGN": 2500000.00
  },
  "crypto_payments": 180,
  "fiat_payments": 70
}

Understanding the Stats

Field	Description
`total_payments`	All-time payment count
`pending_payments`	Currently awaiting payment
`paid_payments`	Successfully paid
`expired_payments`	Expired before payment (15 min timeout)
`failed_payments`	Payment failed or rejected
`total_volume`	All-time volume by currency
`today_volume`	Today's volume by currency
`this_month_volume`	Current month volume
`crypto_payments`	Crypto payment count
`fiat_payments`	Fiat payment count

Checkout Session Expiry

All checkout sessions expire 15 minutes after creation to prevent stale addresses and ensure timely payments.

Important Notes

⏰ Expiry Time: 15 minutes from session creation
🔄 Automatic Handling: Expired sessions are automatically marked as expired
📧 No Notifications: Customers should complete payment quickly
♻️ New Session: Create a new checkout if the old one expires

Example: Checking Expiration

javascript

const checkout = await createCheckout({...});

console.log('Created:', checkout.created_at);
console.log('Expires:', checkout.expires_at);

// Calculate time remaining
const expiresAt = new Date(checkout.expires_at);
const now = new Date();
const minutesRemaining = Math.floor((expiresAt - now) / 60000);

console.log(`Time remaining: ${minutesRemaining} minutes`);

Best Practices

Display Countdown: Show remaining time to customers
Quick Checkout: Design UI for fast payment completion
Handle Expiry: Gracefully handle expired sessions
Auto-Refresh: Optionally create new session if expired

Download Invoice

Generate and download professional PDF invoices for completed payments.

Endpoint

http

GET /api/v1/invoice/:checkoutID

Request Example

cURLJavaScriptPython

bash

curl -X GET 'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/invoice/123' \
  -H "X-API-Key: YOUR_API_KEY" \
  --output invoice.pdf

javascript

// Download invoice
const response = await fetch(
  'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/invoice/123',
  {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  }
);

const blob = await response.blob();
const url = window.URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'invoice.pdf';
a.click();

python

import requests

response = requests.get(
    'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/invoice/123',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)

with open('invoice.pdf', 'wb') as f:
    f.write(response.content)

Invoice Features

✅ Professional Design - RACH FINANCE branded invoices
✅ Complete Details - Payment info, amounts, transaction hashes
✅ Multi-Currency - Supports all payment currencies
✅ Crypto Transactions - Includes blockchain TX hash
✅ Status Indicators - Color-coded payment status
✅ PDF Format - Standard A4 printable format

Invoice Contents

Company branding and logo
Invoice number (checkout reference)
Payment date and status
Business details
Payment breakdown
Total amount in original currency
Crypto transaction hash (if applicable)
Payment method information

Refunds

Process full refunds for completed payments.

Endpoint

http

POST /api/v1/refunds

Request Parameters

Parameter	Type	Required	Description
`checkout_id`	integer	Yes	ID of the paid checkout
`amount`	string	Yes	Refund amount (must be ≤ original)
`reason`	string	Yes	Reason for refund
`refund_method`	string	Yes	`crypto` or `fiat`
`refund_address`	string	If crypto	Customer's refund address
`bank_code`	string	If fiat	Bank code for fiat refund
`account_number`	string	If fiat	Account number
`account_name`	string	If fiat	Account holder name

Request Example

cURL - Crypto RefundJavaScript

bash

curl -X POST 'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/refunds' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "checkout_id": 123,
    "amount": "100.00",
    "reason": "Customer requested refund",
    "refund_method": "crypto",
    "refund_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  }'

javascript

const response = await fetch(
  'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/refunds',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      checkout_id: 123,
      amount: '100.00',
      reason: 'Customer requested refund',
      refund_method: 'crypto',
      refund_address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
    })
  }
);

const refund = await response.json();
console.log('Refund ID:', refund.id);

Response

json

{
  "id": 45,
  "business_id": 10,
  "checkout_id": 123,
  "amount": "100.00",
  "currency": "USDT",
  "reason": "Customer requested refund",
  "refund_method": "crypto",
  "status": "manual_review",
  "status_message": "Requires manual transfer of 100.00 USDT to 0x742d35...",
  "network": "BSC",
  "to_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "created_at": "2025-12-29T15:30:00Z"
}

Refund Status Flow

pending → processing → completed/failed
               ↓
        manual_review (crypto refunds)

Refund Methods

Crypto Refunds:

Status: manual_review
Requires manual processing by admin
Customer receives to specified address
Same network as original payment

Fiat Refunds:

Status: processing → completed
Automated via NILOS integration
Converts crypto to fiat automatically
Bank transfer to customer account

Check Refund Status

http

GET /api/v1/refunds/:id

bash

curl 'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/refunds/45' \
  -H "X-API-Key: YOUR_API_KEY"

Next Steps

Checkout Flow - Create payment sessions
Webhooks - Real-time payment notifications
Integration Guide - Complete integration guide

Payment Management ​

Payment List ​

Endpoint ​

Query Parameters ​

Request Example ​

Response ​

Payment Statistics ​

Endpoint ​

Request Example ​

Response ​

Understanding the Stats ​

Checkout Session Expiry ​

Important Notes ​

Example: Checking Expiration ​

Best Practices ​

Download Invoice ​

Endpoint ​

Request Example ​

Invoice Features ​

Invoice Contents ​

Refunds ​

Endpoint ​

Request Parameters ​

Request Example ​

Response ​

Refund Status Flow ​

Refund Methods ​

Check Refund Status ​

Next Steps ​

Payment Management

Payment List

Endpoint

Query Parameters

Request Example

Response

Payment Statistics

Endpoint

Request Example

Response

Understanding the Stats

Checkout Session Expiry

Important Notes

Example: Checking Expiration

Best Practices

Download Invoice

Endpoint

Request Example

Invoice Features

Invoice Contents

Refunds

Endpoint

Request Parameters

Request Example

Response

Refund Status Flow

Refund Methods

Check Refund Status

Next Steps