Quickstart

Get a payment running in under 10 minutes. RiverPay's API is REST-based with JSON request/response bodies. The shape is intentionally similar to Stripe — most migrations take a day or less.

Alpha note

You'll receive your API keys by email within 24 hours of applying. Sandbox keys are prefixed rp_test_; live keys are rp_live_.

bash
# Create a payment intent
curl https://api.riverpay.com.au/v1/payments \
  -H "Authorization: Bearer rp_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "aud",
    "description": "Order #1042",
    "metadata": { "order_id": "1042" }
  }'

# Response
{
  "id": "pay_abc123",
  "status": "pending",
  "amount": 5000,
  "currency": "aud",
  "checkout_url": "https://checkout.riverpay.com.au/pay_abc123",
  "created_at": "2026-04-14T12:00:00Z"
}

Authentication

All API requests are authenticated with a Bearer token in the Authorization header. Keep your secret key server-side only — never expose it in client-side code or public repos.

bash
Authorization: Bearer rp_test_abc123xyz
rp_test_…Sandbox

No real money moves. Safe for development and CI.

rp_live_…Live

Real transactions. Available after alpha review.

Payments

The payments API follows a create-then-redirect flow. Create a payment intent on your server, redirect the customer to the hosted checkout, then listen for the webhook event.

Endpoints

POST/v1/paymentsCreate a payment intent
GET/v1/payments/:idRetrieve a payment
GET/v1/paymentsList payments (paginated)
POST/v1/payments/:id/refundRefund a payment
POST/v1/payments/:id/captureCapture an authorised payment

Payment object

json
{
  "id":           "pay_abc123",
  "status":       "paid",          // pending | paid | failed | refunded
  "amount":       5000,            // cents (AUD)
  "currency":     "aud",
  "fee":          70,              // 1.0% + 20¢ = $0.70 for $50
  "net":          4930,
  "description":  "Order #1042",
  "checkout_url": "https://checkout.riverpay.com.au/pay_abc123",
  "settled_at":   "2026-04-14T17:00:00Z",
  "metadata":     { "order_id": "1042" },
  "created_at":   "2026-04-14T12:00:00Z"
}

Webhooks

RiverPay sends signed POST requests to your endpoint for every payment event. Verify the X-RiverPay-Signature header using your webhook secret.

Event types

payment.paidCustomer completed payment successfully
payment.failedPayment attempt declined
payment.refundedRefund issued (partial or full)
settlement.completeFunds settled to your bank account
dispute.openedCustomer initiated a chargeback

Signature verification

typescript
import crypto from 'crypto';

export function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// In your Next.js route handler:
export async function POST(req: Request) {
  const body = await req.text();
  const sig  = req.headers.get('x-riverpay-signature') ?? '';
  if (!verifyWebhook(body, sig, process.env.RIVERPAY_WEBHOOK_SECRET!)) {
    return new Response('Invalid signature', { status: 401 });
  }
  const event = JSON.parse(body);
  if (event.type === 'payment.paid') {
    await fulfillOrder(event.data.metadata.order_id);
  }
  return new Response('ok');
}

Crypto Payments

Accept BTC, ETH, SOL, USDC, and USDT. RiverPay's neural rate lock converts to AUD at transaction time and settles via NPP same-day. Zero FX risk to you.

bash
# Create a crypto payment intent
curl https://api.riverpay.com.au/v1/payments \
  -H "Authorization: Bearer rp_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "aud",
    "payment_method_types": ["crypto"],
    "crypto": {
      "assets": ["USDC", "ETH", "BTC"],
      "rate_lock_seconds": 60
    }
  }'

# The checkout_url will show a crypto address and rate-locked AUD amount
# Rate refreshes every 60s if unpaid
₿ USDC / USDT
0.5% (Starter) / 0.3% (Pro)
Recommended for merchants — minimal volatility
₿ ETH / SOL
0.5% (Starter) / 0.3% (Pro)
60-second neural rate lock, AUD settled via NPP
₿ BTC
0.5% (Starter) / 0.3% (Pro)
10-minute confirmation window, then NPP settlement

SDKs & Libraries

Official SDKs ship with alpha access. The Node.js SDK is available in private preview now.

Node.js / TypeScript
npm install @riverpay/nodePrivate preview
Python
pip install riverpayComing Q2 2026
PHP
composer require riverpay/phpComing Q3 2026

Stripe migration

RiverPay's API shape closely mirrors Stripe's. For most integrations, replacing the Stripe client with the RiverPay client and updating your keys is all that's needed. Our team reviews your integration before go-live.