Overview

The Collections API creates virtual accounts that businesses can use to receive payments and match incoming funds to customers. Use NGN for Naira virtual-account flows and USD for the Lead Bank-backed collection flow.

Supported partners

The currently supported account-issuing partners are:

Teerus Microfinance Bank for permanent (DEFAULT) NGN collection accounts
VFD Microfinance Bank for dynamic (ONE_TIME) NGN collection accounts
Lead Bank for USD collection accounts

Create Virtual Account

To create a virtual account, use the create collection endpoint. Parameters

string

The unique identifier for the customer who will own the collection account.

string

required

The three-letter ISO currency code in uppercase. Use NGN for Naira accounts and USD for USD collection accounts.

string

merchant name that will be displayed on the virtual account. Required for ONE_TIME (Temporary) virtual account.

string

required

virtual account type e.g DEFAULT (Permanent), ONE_TIME (Temporary)

Permanent NGN accounts created with DEFAULT are issued through Teerus Microfinance Bank. Dynamic NGN accounts created with ONE_TIME are issued through VFD Microfinance Bank.

number

amount expected to be paid into the virtual account. Required for ONE_TIME (Temporary) virtual account.

object

Required when currency is USD. This contains the customer’s source-of-funds answers, government document, and supporting-document details. Country, residential address, date of birth, phone number, and country-specific identifier are taken from the customer’s approved KYC profile.

Note: customer_id is required for DEFAULT permanent virtual accounts.

Request Body

{
    "customer_id": "user",
    "currency": "NGN",
    "merchant_name": "Swerv",
    "amount": 10,
    "type": "ONE_TIME"
}

USD collection accounts

USD collection accounts are issued through Swervpay’s Lead Bank-backed collection flow. Before creating a USD collection account, create the customer and submit customer KYC. Then create a DEFAULT collection with currency set to USD and include the required additional_information payload. Swerv uses the customer’s approved KYC profile as the source of truth for country, residential address, date of birth, phone number, and bank or national identifier. Review country availability before issuing in a new market. USD account issuance can be asynchronous. If the customer is already approved, the account details may be available shortly after creation. If additional review is required, listen for the collection.created or collection.created.failed webhook event.

USD Request Body

{
  "customer_id": "cus_123456789",
  "currency": "USD",
  "merchant_name": "Ada Okafor",
  "amount": 0,
  "type": "DEFAULT",
  "additional_information": {
    "account_type": "INDIVIDUAL",
    "employment_status": "EMPLOYED",
    "account_designation": "PERSONAL",
    "income_band": "UNDER_10000",
    "source_of_income": "SALARY",
    "document": {
      "type": "NIN",
      "number": "12345678901",
      "issue_date": "2020-01-01",
      "expiry_date": "2030-01-01",
      "urls": ["https://example.com/document-front.jpg"]
    },
    "utility_bill": "https://example.com/utility-bill.pdf",
    "bank_statement": "https://example.com/bank-statement.pdf"
  }
}

Swervpay securely submits the required customer data for compliance review and issues the Lead Bank USD deposit account when the customer is approved.

🔍 Get Collection Details

Retrieve detailed information about a collection with its unique identifier using the get collection endpoint. Path Parameters

string

required

The unique identifier of the collection to retrieve.

🔍 Get All Collections

Retrieve a list of all collections by sending a request to the get all collections endpoint. Query Parameters

integer

The page to return.

integer

The maximum number of results to return.

Response Example The collection endpoints return account objects with wallet-style fields such as account number, bank details, currency, balance, and status. Store the collection ID and account details returned by the API so you can match incoming payments to the correct customer.

Response

[
  {
    "account_name": "string",
    "account_number": "string",
    "account_type": "string",
    "balance": 100000, // Balance in the smallest currency unit
    "bank_address": "string",
    "bank_code": "string",
    "bank_name": "string",
    "created_at": "2024-01-01T00:00:00Z",
    "id": "wlt_123456789",
    "is_blocked": false,
    "pending_balance": 50000, // Pending balance in the smallest currency unit
    "reference": "string",
    "routing_number": "string",
    "total_received": 1500000, // Total amount received in the smallest currency unit
    "updated_at": "2024-01-02T00:00:00Z"
  }
  // ...other collections
]

🧾 Get Collection Transactions

Review payments received into a collection account with the collection transactions endpoint.

string

required

The unique identifier of the collection whose transactions you want to retrieve.

🧪 Simulate a Collection Credit

In sandbox only, simulate an incoming credit with the collection credit endpoint. Use this to test collection webhooks and reconciliation flows without moving real funds.

string

required

The unique identifier of the collection to credit.

Get Started

Wallet

Transaction

Customer

Card

Collection

FX

Payout

Webhook Events

Supported partners

Create Virtual Account

USD collection accounts

🔍 Get Collection Details

🔍 Get All Collections

🧾 Get Collection Transactions

🧪 Simulate a Collection Credit

​Supported partners

​Create Virtual Account

​USD collection accounts

​🔍 Get Collection Details

​🔍 Get All Collections

​🧾 Get Collection Transactions

​🧪 Simulate a Collection Credit

Supported partners

Create Virtual Account

USD collection accounts

🔍 Get Collection Details

🔍 Get All Collections

🧾 Get Collection Transactions

🧪 Simulate a Collection Credit