Settlr|API Reference
v1Dashboard →

API Reference

The Settlr API lets you create payment links, request withdrawals, and receive real-time webhook events when transactions complete.

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
Your secret key is shown once when generated. If you lose it, revoke it and generate a new one from your dashboard settings.

Create a payment link

POSThttps://payments.afriversedao.org/api/payment-links

Creates a new pending payment and returns a hosted checkout URL to redirect your customer to.

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

emailrequiredstringThe customer's email address. They'll receive a confirmation when payment is detected.
amountrequiredintegerAmount in Naira (NGN). Must be a whole number — no decimals. E.g. 25000 for ₦25,000.
redirectTorequiredstringURL to redirect the customer to after their payment is confirmed.

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.

pending

Payment created. Waiting for customer to transfer.

approved

Transfer detected and confirmed. Webhook fires with charge.success.

declined

Payment was manually declined by the gateway. Webhook fires with charge.failed.

abandoned

No transfer received within 30 minutes. No webhook is sent.

Create a withdrawal

POSThttps://payments.afriversedao.org/api/withdrawal

Requests a payout to a bank account. The withdrawal is queued for processing and you'll receive a webhook when it's sent or declined.

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

emailrequiredstringRecipient's email address. They'll be notified when the withdrawal is processed.
accountNamerequiredstringExact name on the bank account.
accountNumberrequiredstring10-digit NUBAN account number.
bankrequiredstringBank name. E.g. GTBank, Access Bank, OPay.
amountrequiredintegerAmount in Naira to withdraw.
transactionIdrequiredstringYour unique identifier for this withdrawal. Used for idempotency — submitting the same ID twice returns the original.

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"
  }
}

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.

Payment webhook — header: x-nexgen-signature

import { createHmac } from "crypto";

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

Withdrawal webhook — header: x-nexgen-withdrawal-signature

import { createHmac } from "crypto";

function verifyWithdrawalWebhook(rawBody: string, signature: string, secret: string) {
  const expected = createHmac("sha512", secret)
    .update(rawBody)
    .digest("hex");
  return signature === expected;
}
Always verify signatures. Never credit a user or fulfill an order based on a webhook that hasn't been verified. Treat all webhooks as idempotent — the same event may be delivered more than once.

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.

StatusMeaning
400Bad request — a required field is missing or malformed.
401Unauthorized — your API key is missing or invalid.
403Forbidden — your key doesn't have permission for this action.
404Not found — the requested resource doesn't exist.
409Conflict — a resource with this ID already exists (e.g. duplicate transactionId).
429Rate limited — slow down and retry after a short delay.
500Server error — something went wrong on our end. Contact support if it persists.
// Example error response
{
  "error": "amount is required and must be a positive integer"
}