API Reference

Authentication

All API requests must include your secret key in the Authorization header. Keep your secret key on the server — never expose it in client-side code or browsers.

Authorization: Bearer sk_live_YOUR_SECRET_KEY

Create a payment link

POST https://payments.afriversedao.org/api/payment-links
Authorization: Bearer sk_live_...
Content-Type: application/json

{
  "email": "customer@example.com",
  "amount": 25000,
  "redirectTo": "https://yourapp.com/order/complete"
}

Request body

Response

{
  "id": "clx4f2g0000abc123",
  "url": "https://payments.afriversedao.org/pay/clx4f2g0000abc123",
  "reference": "PAY-1A2B3C4D",
  "amount": 25000,
  "email": "customer@example.com"
}

Redirect your customer to url. They will see the exact transfer amount and bank account details. Store reference against your order — you'll receive it back in the webhook.

Payment lifecycle

A payment moves through the following statuses. Your webhook fires on approved and declined.

Virtual accounts

Programmatically create a dedicated bank account (powered by Flutterwave) tied to a specific amount and expiry. Show the returned account number to your customer — when they transfer the exact amount, the account is funded and your charge.success webhook fires.

POST https://payments.afriversedao.org/api/virtual-accounts
Authorization: Bearer sk_live_...
Content-Type: application/json

{
  "amount": 25000,
  "email": "customer@example.com",
  "expirySeconds": 900
}

Request body

Response

{
  "id": "clx9v1a0000va0001",
  "reference": "va3f9c2a1b8d4e6f0...",
  "provider": "flutterwave",
  "amount": 25000,
  "currency": "NGN",
  "status": "pending",
  "accountNumber": "7824822527",
  "bankName": "WEMA BANK",
  "email": "customer@example.com",
  "expiresAt": "2026-06-16T13:54:21.546Z",
  "paidAt": null,
  "createdAt": "2026-06-16T13:39:21.546Z"
}

Display accountNumber and bankName to your customer. Store reference against your order — you'll receive it back in the charge.success webhook when the account is funded.

Retrieve a virtual account

An account is pending until funded (paid), or becomes expired if the expiry elapses with no transfer.

Create a withdrawal

POST https://payments.afriversedao.org/api/withdrawal
Authorization: Bearer sk_live_...
Content-Type: application/json

{
  "email": "customer@example.com",
  "accountName": "John Doe",
  "accountNumber": "0123456789",
  "bank": "GTBank",
  "amount": 15000,
  "transactionId": "your-unique-tx-id-001"
}

Request body

Response

{
  "id": "clx4g1h0000xyz789",
  "status": "requested",
  "amount": 15000,
  "bank": "GTBank",
  "accountNumber": "0123456789"
}

Webhooks

Settlr sends a signed POST request to your webhook URL when a payment or withdrawal status changes. Configure your webhook URLs and secrets in the dashboard settings.

Payment webhook — charge.success

{
  "event": "charge.success",
  "data": {
    "reference": "PAY-1A2B3C4D"
  }
}

Virtual account fundings fire the same charge.success event, with extra fields — match on reference:

{
  "event": "charge.success",
  "data": {
    "reference": "va3f9c2a1b8d4e6f0...",
    "amount": 25000,
    "accountNumber": "7824822527",
    "provider": "flutterwave",
    "providerTxId": "chg_Hq4oBRTJ4r"
  }
}

Withdrawal webhook

{
  "transactionId": "your-unique-tx-id-001",
  "amount": 15000,
  "status": "sent"   // or "declined"
}

Verifying signatures

Every webhook request includes a signature header. Always verify it before processing the event.

import { createHmac } from "crypto";

function verifyPaymentWebhook(rawBody: string, signature: string, secret: string) {
  const expected = createHmac("sha512", secret)
    .update(rawBody)
    .digest("hex");
  return signature === expected;
}

import { createHmac } from "crypto";

function verifyWithdrawalWebhook(rawBody: string, signature: string, secret: string) {
  const expected = createHmac("sha512", secret)
    .update(rawBody)
    .digest("hex");
  return signature === expected;
}

Responding to webhooks

Return a 200 status as quickly as possible. Do your processing asynchronously — if your endpoint takes too long or returns a non-2xx status, delivery may be retried.

Errors

All errors return a JSON object with an error field describing the problem.

// Example error response
{
  "error": "amount is required and must be a positive integer"
}