🇳🇬 NGN Transfers

Overview

The Capera B2B API allows you to send money to any Nigerian bank account. The transfer process involves three main steps:

List Banks - Get available Nigerian banks
Resolve Account - Verify account details
Initiate Transfer - Send the money

List Banks

GET /v1/banks

Get all available Nigerian banks for transfers.

Authentication

No authentication required.

Response

Returns an array of bank objects.

[
  {
    "id": "bank_001",
    "name": "First Bank of Nigeria",
    "slug": "first-bank"
  },
  {
    "id": "bank_002",
    "name": "United Bank for Africa", 
    "slug": "uba"
  },
  {
    "id": "bank_003",
    "name": "Guaranty Trust Bank",
    "slug": "gtb"
  }
]

Bank Object

Attribute	Type	Description
`name`	string	Full name of the bank
`slug`	string	Bank identifier used in API calls

Example Request

curl -X GET https://api.withcapera.com/b2b/v1/banks

Resolve Account

GET /v1/bank/resolve

Verify account details and get the account holder's name.

Authentication

Required. Include your API key in the Authorization header.

Parameters

Parameter	Type	Required	Description
`accountNumber`	string	Required	10-digit bank account number
`bankSlug`	string	Required	Bank identifier from List Banks

Response

Returns the account holder's name if valid.

{
  "accountName": "John Doe"
}

Errors

Status	Error	Resolution
`400`	Account number is required	Include accountNumber parameter
`400`	Bank slug is required	Include bankSlug parameter
`400`	Bank not found	Use valid bank slug from List Banks
`400`	Account not found	Verify account number is correct
`401`	Unauthorized	Check API key is valid

Example Request

curl -X GET "https://api.withcapera.com/b2b/v1/bank/resolve?accountNumber=1234567890&bankSlug=first-bank" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Initiate Transfer

POST /v1/transfers/initiate

Send NGN to a Nigerian bank account.

Authentication

Required. Include your API key in the Authorization header.

Request Body

Field	Type	Required	Description
`reference`	string	Required	Unique reference (must be unique per merchant)
`amount`	integer	Required	Amount in kobo (₦1 = 100 kobo)
`bankSlug`	string	Required	Bank identifier from List Banks
`accountNumber`	string	Required	10-digit account number
`accountName`	string	Required	Account holder name
`narration`	string	Optional	Transfer description (max 100 chars)

Amount in Kobo

All amounts are specified in kobo (minor currency units):

₦1 = 100 kobo
₦100 = 10,000 kobo
₦1,000 = 100,000 kobo

Request Example

{
  "reference": "TRF-2024-001",
  "amount": 50000,
  "bankSlug": "first-bank", 
  "accountNumber": "1234567890",
  "accountName": "John Doe",
  "narration": "Payment for services"
}

Response

Returns initial transfer status.

{
  "status": "PENDING"
}

Errors

Status	Error	Resolution
`400`	Session not found	Check API key is valid
`400`	Invalid request body	Verify JSON format
`400`	Amount must be greater than 0	Use positive amount
`400`	Bank not found	Use valid bank slug
`400`	Reference already exists	Use unique reference
`401`	Unauthorized	Check API key

Example Request

curl -X POST https://api.withcapera.com/b2b/v1/transfers/initiate \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "TRF-2024-001",
    "amount": 50000,
    "bankSlug": "first-bank",
    "accountNumber": "1234567890", 
    "accountName": "John Doe",
    "narration": "Payment for services"
  }'

Get Transfer Status

GET /v1/transfers/{reference}

Check the status of a transfer.

Authentication

Required. Include your API key in the Authorization header.

Path Parameters

Parameter	Type	Required	Description
`reference`	string	Required	Transfer reference

Response

Returns transfer details and current status.

{
  "reference": "TRF-2024-001",
  "status": "SUCCESS", 
  "amount": 50000,
  "fee": 50
}

Transfer Object

Attribute	Type	Description
`reference`	string	Unique transfer reference
`status`	string	Current transfer status
`amount`	integer	Transfer amount in kobo
`fee`	integer	Transfer fee in kobo

Status Values

Status	Description
`PENDING`	Transfer is queued
`PROCESSING`	Transfer is being processed
`SUCCESS`	Transfer completed successfully
`FAILED`	Transfer failed
`CANCELLED`	Transfer was cancelled

Errors

Status	Error	Resolution
`400`	Reference is required	Include reference in path
`400`	Transfer not found	Check reference is correct
`401`	Unauthorized	Check API key

Example Request

curl -X GET https://api.withcapera.com/b2b/v1/transfers/TRF-2024-001 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Complete Workflow

Here's the recommended flow for sending a transfer:

1. Get Banks (Optional - Cache Results)

curl -X GET https://api.withcapera.com/b2b/v1/banks

2. Resolve Account

curl -X GET "https://api.withcapera.com/b2b/v1/bank/resolve?accountNumber=1234567890&bankSlug=first-bank" \
  -H "Authorization: Bearer YOUR_API_KEY"

3. Initiate Transfer

curl -X POST https://api.withcapera.com/b2b/v1/transfers/initiate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "TRF-2024-001",
    "amount": 50000,
    "bankSlug": "first-bank",
    "accountNumber": "1234567890",
    "accountName": "John Doe"
  }'

4. Check Status

curl -X GET https://api.withcapera.com/b2b/v1/transfers/TRF-2024-001 \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

Reference Generation

Generate unique references to avoid duplicates:

Use timestamp: TRF-{timestamp}
Include order ID: ORDER-{orderId}
Add random suffix: TRF-{timestamp}-{random}

Amount Validation

Convert Naira to kobo (multiply by 100)
Minimum: ₦1 (100 kobo)
Validate amount is positive

Account Verification

Always resolve account details before initiating transfers to ensure accuracy.

Caching

Banks don't change frequently. Cache the bank list for 24 hours to reduce API calls.

Testing

Test Account Numbers

Bank	Account Number	Account Name
`first-bank`	`1234567890`	`Test User One`
`gtb`	`0987654321`	`Test User Two`
`uba`	`1122334455`	`Test Business`

Test Amounts

NGN	Kobo	Expected Result
₦1	100	Success
₦100	10000	Success
₦0	0	Validation error

Test Scenarios

Valid Transfer - Use test account details above
Invalid Account - Use non-existent account number
Duplicate Reference - Use same reference twice
Invalid Bank - Use non-existent bank slug