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 Bridge-backed collection flow.

Supported partners

The currently supported account-issuing partners are:

VFD Microfinance Bank
Bridge 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)

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 identity, address, document, source of funds, and supporting document details required for USD account issuance.

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 Bridge-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. 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",
    "nin": "12345678901",
    "tax_number": "12345678901",
    "date_of_birth": "1994-04-12",
    "employment_status": "EMPLOYED",
    "account_designation": "PERSONAL",
    "income_band": "UNDER_10000",
    "source_of_income": "SALARY",
    "address": {
      "street": "12 Admiralty Way",
      "city": "Lagos",
      "state": "Lagos",
      "country": "Nigeria",
      "zip_code": "100001"
    },
    "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 to Bridge, creates or reuses the Bridge customer profile, and issues the 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