Initiate Sends

Overview

Sends are initiated from your virtual accounts using the Submit Payment Request endpoint. You can send payments from your primary virtual account or from a custom wallet virtual account.

Step 1: Get the Channel ID

Before initiating a send, retrieve the appropriate channelId by calling the Channels endpoint. Filter the results for:

channelType: virtualbank
country: The country matching your virtual account (e.g., US, NG)
currency: The currency matching your virtual account (e.g., USD, NGN)

The returned channelId is required when submitting the payment request.

Step 2: Submit the Send Request

Call the Submit Payment Request endpoint with the channelId, sender details, destination details, and the payment amount.

POST /business/payments

{
  "source": {
    "accountType": "bank"
  },
  "sender": {
    "name": "John Doe",
    "country": "France",
    "address": "12 North Street, 100001 Paris",
    "dob": "02/01/1997",
    "email": "[email protected]",
    "idNumber": "12345567",
    "idType": "license"
  },
  "destination": {
    "accountNumber": "0400440532013000",
    "networkId": "0400440532013000",
    "accountType": "bank",
    "accountName": "Acme GmbH",
    "outboundTransactionType": "SWIFT",
    "swiftCode": "COBADEFFXXX",
    "iban": "DE89370400440532013000",
    "city": "Berlin",
    "postalCode": "10115",
    "country": "DE",
    "address": "Friedrichstraße 100"
  },
  "channelId": "efff976c-a53b-4baa-b81b-ec26f2121c7d",
  "sequenceId": "23444444339949949494949",
  "amount": 10,
  "reason": "other",
  "forceAccept": true
}

Key Request Fields

Field	Description
`source.accountType`	Set to `bank` for virtual account payouts
`channelId`	The virtual bank channel ID retrieved from the Channels endpoint
`sequenceId`	Your unique idempotency key for this payment
`sender`	Sender KYC details
`destination`	Recipient bank account details
`destination.outboundTransactionType`	The transfer type (e.g., `SWIFT`, `ACH`, `WIRE`) - US sends only
`amount`	The send amount
`currency`	The send currency
`country`	The country code for the send
`reason`	The reason for the send
`forceAccept`	Set to `true` to auto-accept the payment

Sends from Custom Wallet Virtual Accounts

To initiate a send from a custom wallet virtual account instead of your primary virtual account wallet, include the walletId field in the request. The walletId is the id of the custom wallet returned when you created it.

POST /business/payments

{
  "source": {
    "accountType": "bank"
  },
  "walletId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sender": {
    "name": "John Doe",
    "country": "France",
    "address": "12 North Street, 100001 Paris",
    "dob": "02/01/1997",
    "email": "[email protected]",
    "idNumber": "12345567",
    "idType": "license"
  },
  "destination": {
    "accountNumber": "0400440532013000",
    "networkId": "0400440532013000",
    "accountType": "bank",
    "accountName": "Acme GmbH",
    "outboundTransactionType": "SWIFT",
    "swiftCode": "COBADEFFXXX",
    "iban": "DE89370400440532013000",
    "city": "Berlin",
    "postalCode": "10115",
    "country": "DE",
    "address": "Friedrichstraße 100"
  },
  "channelId": "efff976c-a53b-4baa-b81b-ec26f2121c7d",
  "sequenceId": "4555523234442444201",
  "amount": 10,
  "reason": "other",
  "forceAccept": true
}

The only difference from a standard send is the addition of the walletId field, which directs the send to be paid from the specified custom wallet's virtual account.

Payment Webhooks

Payment webhook events are sent as the payment progresses through its lifecycle. For details on payment webhook event types and statuses, refer to the Webhooks and Events page.