API Documentation

Everything you need to integrate ShaafiPay into your product — payments, VTU, and virtual cards through one REST API.

All requests are made over HTTPS and return JSON. The base URL for every request is:

https://api.shaafipay.com/v1

Authentication

Every request must include your secret API key as a Bearer token in the Authorization header. You'll receive your keys once your merchant application is approved.

curl https://api.shaafipay.com/v1/banks \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxx"

Sandbox & Production

Every approved merchant gets a sandbox environment for testing before going live. Sandbox keys are prefixed sk_test_, production keys are prefixed sk_live_ and are issued after your application is reviewed and approved.

GET/v1/banks

Returns the list of banks and wallets currently supported for transfers and payouts.

curl https://api.shaafipay.com/v1/banks \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxx"

Example response 200 OK

{
  "status": "success",
  "message": "Banks retrieved successfully",
  "data": [
    {
      "id": "paga",
      "name": "Paga",
      "code": "327",
      "type": "mobile_wallet"
    },
    {
      "id": "palmpay",
      "name": "PalmPay",
      "code": "999991",
      "type": "mobile_wallet"
    },
    {
      "id": "opay",
      "name": "OPay",
      "code": "999992",
      "type": "mobile_wallet"
    },
    {
      "id": "wema-bank",
      "name": "Wema Bank",
      "code": "035",
      "type": "commercial_bank"
    },
    {
      "id": "fidelity-bank",
      "name": "Fidelity Bank",
      "code": "070",
      "type": "commercial_bank"
    }
  ]
}

Payments

Initiate charges, verify transactions, and issue refunds through the payments resource.

VTU Services

Sell airtime, data, cable TV, and electricity to your customers — powered through our Paga partnership.

Virtual Cards

Issue Naira or Dollar virtual cards for your users and manage them programmatically.

Webhooks

Subscribe to real-time events instead of polling. Configure your webhook URL from the merchant dashboard once it's live.

• payment.initiated
• payment.successful
• payment.failed
• payment.reversed
• refund.created

Errors

ShaafiPay uses standard HTTP status codes. Error responses include a message you can show or log.