Getting started

Get from zero to your first payout in under 10 minutes.

If you don’t already have a Swappr account, sign up at app.swappr.me/sign-up. You’ll need to complete KYC before live mode is enabled, but you can use sandbox immediately.

Generate an API key

From your dashboard, go to API & Webhooks → click + Generate new key. Pick Sandbox or Live, give the key a label, and add at least one IP address to the allowlist (mandatory).

You’ll see the secret once — store it securely. The dashboard only shows the first 12 characters going forward.

API keys look like:

Sandbox: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx
Live: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

⚠️

Never commit API keys to source control. Use environment variables or a secrets manager.

Make your first request

Try a balance check — read-only, no idempotency key needed:

curl https://api.swappr.me/v1/balances \
  -H "Authorization: Bearer sk_test_..."

const response = await fetch('https://api.swappr.me/v1/balances', {
  headers: {
    'Authorization': `Bearer ${process.env.SWAPPR_API_KEY}`,
  },
});
 
const balances = await response.json();
console.log(balances.data);

import os
import requests
 
response = requests.get(
    'https://api.swappr.me/v1/balances',
    headers={'Authorization': f"Bearer {os.environ['SWAPPR_API_KEY']}"},
)
 
balances = response.json()
print(balances['data'])

You should get back a list of your wallets with current balances.

Send your first payout

Sandbox payouts use simulated providers — no real money moves. NGN payouts only need an account number + bank code; the recipient name is auto-resolved via NUBAN.

curl https://api.swappr.me/v1/payouts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_minor": "5000",
    "currency": "NGN",
    "recipient": {
      "account_number": "0690000032",
      "bank_code": "044"
    },
    "merchant_reference": "TEST_001"
  }'

import { randomUUID } from 'crypto';
 
const response = await fetch('https://api.swappr.me/v1/payouts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SWAPPR_API_KEY}`,
    'Idempotency-Key': randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount_minor: '5000', // ₦50.00 in kobo
    currency: 'NGN',
    recipient: {
      account_number: '0690000032',
      bank_code: '044',
    },
    merchant_reference: 'TEST_001',
  }),
});
 
const payout = await response.json();
console.log(payout.id, payout.status, payout.recipient_name);

import os
import uuid
import requests
 
response = requests.post(
    'https://api.swappr.me/v1/payouts',
    headers={
        'Authorization': f"Bearer {os.environ['SWAPPR_API_KEY']}",
        'Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json',
    },
    json={
        'amount_minor': '5000',  # ₦50.00 in kobo
        'currency': 'NGN',
        'recipient': {
            'account_number': '0690000032',
            'bank_code': '044',
        },
        'merchant_reference': 'TEST_001',
    },
)
 
payout = response.json()
print(payout['id'], payout['status'], payout['recipient_name'])

The response includes:

id — internal cuid
reference — merchant-facing reference (po_xxx)
status — usually paid in sandbox (simulated success), or processing for live
recipient_name — bank-of-record name auto-resolved via NUBAN
provider — which rail dispatched the payout

Set up a webhook

Webhooks notify you when payouts complete, virtual accounts are credited, etc. Go to API & Webhooks → + Add webhook endpoint, paste your HTTPS URL, pick the events you care about.

You’ll get a signing secret ONCE on creation — store it. Every webhook delivery includes an X-Swappr-Signature header you verify against this secret.

# Test the endpoint with a synthetic event:
curl https://api.swappr.me/v1/webhook_endpoints/whe_xxx/test \
  -X POST \
  -H "Authorization: Bearer sk_test_..."

See Webhooks for the full signing scheme + verification examples.

Go live

When you’re ready for production:

Complete KYC at app.swappr.me/settings/compliance
Wait for compliance approval (1-3 business days)
Generate a Live API key (sk_live_)
Switch your code to use https://api.swappr.me/v1 (same hostname, live keys auto-route)
Whitelist your production IPs

What’s next?

Authentication details
Bulk payouts guide — push 150 payouts in one call
Idempotency — handle network retries safely
Webhooks — verify signatures + handle deliveries

Introduction Authentication