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 and Network 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.

📘
Manual Input Network Right now, the API doesn't have a list of all banks available in all countries. Manual Input network is available to help with this, when you call the Get Networks endpoint and you filter by your selected channelId, you'll have one network left with network name "Manual Input". Pass this Network ID, alongside other destination input sent to the submit payment endpoint.

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": "28281f21-4705-431f-a752-9a485628c76a",
    "accountType": "bank",
    "accountName": "Acme GmbH",
    "outboundTransactionType": "SWIFT",
    "swiftCode": "COBADEFFXXX",
    "iban": "DE89370400440532013000",
    "city": "Berlin",
    "postalCode": "10115",
    "country": "DE",
    "address": "Friedrichstraße 100",
    "memo": "test payment"
  },
  "channelId": "efff976c-a53b-4baa-b81b-ec26f2121c7d",
  "sequenceId": "23444444339949949494949",
  "amount": 10,
  "reason": "other",
  "forceAccept": true
}

Key Request Fields

Field	Required	Description
`source.accountType`	Yes	Set to `bank` for virtual account payouts
`channelId`	Yes	The virtual bank channel ID retrieved from the Channels endpoint
`networkId`	Yes	The ID of the manual input network
`sequenceId`	Yes	Your unique idempotency key for this payment
`sender`	Yes	Sender KYC details
`destination`	Yes	Recipient bank account details
`destination.accountName`	Yes	Name on the recipient bank account
`destination.outboundTransactionType`	Yes	Transfer type: `ACH`, `WIRE`, or `SWIFT`
`destination.address`	Yes	Street address of the recipient
`destination.city`	Yes	City of the recipient
`destination.postalCode`	Yes	Postal/ZIP code of the recipient
`destination.country`	Yes	ISO country code of the recipient
`destination.countryArea`	When `destination.country` is `US`	State/province code
`destination.routingNumber`	When `ACH` or `WIRE`	Bank routing number
`destination.accountNumber`	When `ACH` or `WIRE`; or one of `accountNumber`/`iban` when `SWIFT`	Bank account number
`destination.swiftCode`	When `SWIFT`	SWIFT/BIC code
`destination.iban`	One of `accountNumber`/`iban` when `SWIFT`	IBAN — accepted in place of `accountNumber` for `SWIFT`
`destination.memo`	No	An optional description for the payment and passed through to the recipient’s bank statement
`amount`	Yes	The send amount
`reason`	Yes	The reason for the send
`forceAccept`	Yes	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": "28281f21-4705-431f-a752-9a485628c76a",
    "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.