Afripay Merchant API

Welcome to the Afripay Merchant Public API documentation. This API allows you to manage customers, issue virtual cards, create currency accounts, and track transactions.

Base URL:
https://business.goafripay.com/api/merchant

Authentication

All endpoints require Client Credentials, which can be obtained from the merchant developer dashboard, passed as HTTP headers.

Header	Value
`X-Client-Id`	`mch_test_OE***********************HB`
`X-Client-Secret`	`sk_test_69******************************IyH`
`Accept`	`application/json`
`Content-Type`	`application/json` (for POST/PATCH/PUT/DELETE)

Customers

1. List Customers

GET /api/merchant/baas/customers

Query Parameters

Parameter	Type	Description
`per_page`	integer	Items per page (default: 20, max: 100)

JSON Response (200 OK)

{
  "status": true,
  "message": "Customers fetched successfully",
  "data": [
    {
      "id": "1b04b3ff-b7f0-458d-b635-7e8b152977b9",
      "first_name": "Taiwo",
      "last_name": "Hassan",
      "email": "thaywo247@gmail.com",
      "phone": "+12345678490",
      "bvn": "12345678901",
      "nin": "98765432101",
      "secondary_id_type": "nin",
      "secondary_id_number": "98765432101",
      "status": "active",
      "address": {
        "city": "Lagos",
        "line1": "123 Main St",
        "state": "Lagos",
        "country": "NG"
      },
      "baas_provider": "afripay",
      "currency_accounts_count": 0,
      "cards_count": 0,
      "created_at": "2026-07-10T17:50:55Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 2
  }
}

2. Create Customer

POST /api/merchant/baas/customers

Request Body

{
  "first_name": "Taiwo",
  "last_name": "Hassan",
  "email": "taiwo@gmail.com",
  "phone": "+1234567890",
  "bvn": "12345678901",
  "secondary_id_type": "nin",
  "secondary_id_number": "98765432101",
  "address": {
    "line1": "123 Main St",
    "city": "Lagos",
    "state": "Lagos",
    "country": "NG"
  },
  "status": "active"
}

Validation Rules

bvn: Required, exactly 11 digits.
address.country: Required, exactly 2 chars (ISO code).
secondary_id_type: Optional. Used to specify customer identity documents (e.g. nin, drivers_license, passport, voters_card).
secondary_id_number: Required if secondary_id_type is provided. The document number (e.g. an 11-digit NIN).

3. Get Customer

GET /api/merchant/baas/customers/{customerUuid}

4. Update Customer

PATCH /api/merchant/baas/customers/{customerUuid}

All fields are optional for partial updates.

5. Delete Customer

DELETE /api/merchant/baas/customers/{customer}

Cards

6. List Cards

GET /api/merchant/baas/customers/{customer}/cards

Query Params: per_page, currency, label.

7. Create Card

POST /api/merchant/baas/customers/{customerUuid}/cards

Request Body

{
  "currency": "USD",
  "label": "Primary Card",
  "extra": {}
}

8. Get Card

GET /api/merchant/baas/customers/{customerUuid}/cards/{cardId}

9. Fund Card

POST /api/merchant/baas/customers/{customerUuid}/cards/{cardId}/fund

Request Body

{
  "amount": 10.00,
  "extra": {
    "note": "Top up"
  }
}

Validation: Amount must be numeric, min 0.00000001. We enforce min $5.00 and max $10,000.00.

10. Freeze / Unfreeze Card

PATCH /api/merchant/baas/customers/{customerUuid}/cards/{cardId}/freeze

Request Body

{
  "freeze": true
}

11. Card Secure Settings

PATCH /api/merchant/baas/customers/{customerUuid}/cards/{cardId}/secure-settings

Request Body

{
  "payload": {
    "contactless_enabled": false
  }
}

12. Close Card

POST /api/merchant/baas/customers/{customerUuid}/cards/{cardId}/close

Currency Accounts

13. List Currency Accounts

GET /api/merchant/baas/customers/{customerUuid}/currency-accounts

14. Create Currency Account

POST /api/merchant/baas/customers/{customerUuid}/currency-accounts

Request Body

{
  "currency": "NGN"
}

Validation: Currency must be exactly 3 uppercase characters.

Response (201 Created - NGN via PayRep)

{
  "status": true,
  "message": "Currency account created",
  "data": {
    "currency_account": {
      "id": "e2c83407-8802-11f1-8352-0e74f6457b17",
      "currency_code": "NGN",
      "account_number": "3504939056",
      "account_name": "Sandbox Individual Account",
      "bank_name": "Payrep MFB",
      "bank_code": "999",
      "status": "active",
      "label": "testmerchant/John Doe - NGN",
      "created_at": "2026-07-25T09:40:04Z",
      "customer": {
        "id": "1b04b3ff-b7f0-458d-b635-7e8b152977b9",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com"
      }
    }
  }
}

Response (201 Created - USD)

{
  "status": true,
  "message": "Currency account created",
  "data": {
    "currency_account": {
      "id": "a9b8c7d6-e5f4-3210-9876-543210fedcba",
      "currency_code": "USD",
      "account_number": "120049583091",
      "account_name": "John Doe",
      "bank_name": "Bank",
      "bank_code": "090",
      "status": "active",
      "label": "testmerchant/John Doe - USD",
      "created_at": "2026-07-25T09:40:04Z",
      "customer": {
        "id": "1b04b3ff-b7f0-458d-b635-7e8b152977b9",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com"
      }
    }
  }
}

15. Get Currency Account

GET /api/merchant/baas/customers/{customerUuid}/currency-accounts/{accountUuid}

16. Sync Account

POST /api/merchant/baas/customers/{customerUuid}/currency-accounts/{accountUuid}/sync

17. Update Account

PATCH /api/merchant/baas/customers/{customerUuid}/currency-accounts/{accountUuid}

Request Body

{
  "payload": {
    "label": "Updated account label"
  }
}

Payouts

18. Fetch Supported Banks

GET /api/merchant/baas/payouts/banks

Response (200 OK)

{
  "status": true,
  "message": "Banks fetched successfully",
  "data": {
    "banks": [
      {
        "bank_code": "090823",
        "bank_name": "Payrep MFB"
      },
      {
        "bank_code": "000013",
        "bank_name": "Access Bank"
      }
    ]
  }
}

19. Resolve Account Name

POST /api/merchant/baas/payouts/resolve

Request Body

{
  "account_number": "3504939056",
  "bank_code": "090823"
}

Response (200 OK)

{
  "status": true,
  "message": "Account resolved successfully",
  "data": {
    "account_number": "3504939056",
    "account_name": "Sandbox Individual Account",
    "bank_code": "090823",
    "bank_name": "Payrep MFB"
  }
}

20. Initiate Payout

POST /api/merchant/baas/payouts

Request Body

{
  "account_number": "3504939056",
  "bank_code": "090823",
  "amount": 5000.00,
  "reference": "merchant_ref_abc123",
  "remarks": "Services payment"
}

Response (201 Created)

{
  "status": true,
  "message": "Payout initiated and queued.",
  "data": {
    "payout": {
      "reference": "merchant_ref_abc123",
      "uuid": "e2c83407-8802-11f1-8352-0e74f6457b17",
      "trx_id": "PO982461972",
      "amount": "5000.00",
      "charges": "50.00",
      "status": "queued",
      "account_number": "3504939056",
      "bank_code": "090823",
      "bank_name": "Payrep MFB",
      "account_name": "Sandbox Individual Account",
      "created_at": "2026-07-25T14:40:00Z"
    }
  }
}

21. Payout Status Enquiry

GET /api/merchant/baas/payouts/{reference}

Response (200 OK)

{
  "status": true,
  "message": "Payout status retrieved successfully",
  "data": {
    "payout": {
      "reference": "merchant_ref_abc123",
      "uuid": "e2c83407-8802-11f1-8352-0e74f6457b17",
      "trx_id": "PO982461972",
      "amount": "5000.00",
      "charges": "50.00",
      "status": "success",
      "account_number": "3504939056",
      "bank_code": "090823",
      "bank_name": "Payrep MFB",
      "account_name": "Sandbox Individual Account",
      "created_at": "2026-07-25T14:40:00Z"
    }
  }
}

Transactions

22. List Transactions

GET /api/merchant/transactions/{slug?}

Transaction Types

Slug	Description
`money_out`	Money Out
`merchant_payment`	Merchant Payment
`received_payment`	Make Payment
`add_sub_balance`	Add / Subtract Balance
`pay_link`	Pay Link

Error Responses

401 Unauthorized

{
  "status": false,
  "message": "Client credentials are required.",
  "data": null
}

422 Validation Error

{
  "status": false,
  "message": "The bvn field is required.",
  "data": {
    "errors": {
      "bvn": ["The bvn field is required."],
      "address": ["The address field is required."]
    }
  }
}