API REFERENCE

Transfers

Create a payout and retrieve its current status. Transfer processing is asynchronous.

Create a transfer

POST /transactions/createTransaction

API access tokenIdempotency key required

After accepting the request, CAPSEND:

validates the MTO, wallet, amount, sender, and beneficiary;
reserves the transfer amount with a wallet hold;
records the configured fee separately without deducting it from the wallet balance;
queues and processes the bank payment; and
sends a signed terminal webhook.

Headers

Header	Value
`Authorization`	`Bearer ACCESS_TOKEN`
`Content-Type`	`application/json`
`idempotency-key`	A UUID unique to this logical transfer

Required fields

Field	Type	Description
`amount`	decimal string	Positive transfer amount with up to four decimal places.
`currency`	string	Three-letter currency matching your CAPSEND wallet.
`transactionType`	string	Must be `PAYOUT`.
`crAccount`	string	Beneficiary account number.
`beneficiaryBankName`	string	Beneficiary bank name.
`beneficiaryBankCode`	string	Required for an other-bank transfer; omit for the same-bank path.
`beneficiaryName`	string	Beneficiary full name.
`beneficiaryAddress`	string	Beneficiary address.
`senderName`	string	Sender full name.
`senderAddress`	string	Sender address.
`country`	string	Sender country; an ISO country code is recommended.
`stateCode`	string	Sender state or region code.
`narration`	string	Transfer narration, up to 500 characters.

externalReference is optional and should contain your own unique transfer reference. It is useful for reconciliation and wallet-history search.

Staging transfer accounts

CAPSEND staging connects to the Zenith test environment. Use these supplied accounts only in staging:

Test path	Bank	Bank code	Account number
Zenith-to-Zenith	Zenith Bank	Omit	`2020478975`
Other-bank	Sudo Bank	`999998`	`0000014575`

The first account is the supplied Zenith debit test account for the same-bank path. Never use either test account in production.

Request

bash

curl --request POST "${BASE_URL}/transactions/createTransaction" \
  --header "Authorization: Bearer ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
  --data '{
    "amount": "100.0000",
    "currency": "USD",
    "transactionType": "PAYOUT",
    "crAccount": "0000014575",
    "narration": "Transfer INV-1001",
    "country": "NG",
    "senderAddress": "100 Market Street",
    "senderName": "Jane Sender",
    "beneficiaryBankName": "Sudo Bank",
    "beneficiaryBankCode": "999998",
    "beneficiaryName": "John Beneficiary",
    "beneficiaryAddress": "12 Marina Road, Lagos",
    "stateCode": "LA",
    "externalReference": "INV-1001"
  }'

Response

json

{
  "transactionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "reference": "CAP-8E5A19E0D3394E55A3CE4FBC876A514B",
  "status": "PENDING"
}

Save both identifiers. transactionId is used for API lookup; reference is CAPSEND's financial reference.

Common create errors

Status	Meaning
`400`	A required field, amount, bank code, or staging rule is invalid.
`401`	The token is missing, expired, invalid, or belongs to the other environment.
`402`	The production wallet does not have enough available funds.
`404`	No wallet exists for the requested currency.
`409`	The idempotency key is already linked to different request data.

Get transfer status

GET /transactions/get/:id

API access token

Use the transactionId returned when the transfer was created.

Request

bash

curl "${BASE_URL}/transactions/get/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  --header "Authorization: Bearer ACCESS_TOKEN"

Response

json

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "reference": "CAP-8E5A19E0D3394E55A3CE4FBC876A514B",
  "status": "SUCCESS",
  "createdAt": "2026-10-25T09:00:00.000Z",
  "failureReason": null,
  "processedAt": "2026-10-25T09:00:03.000Z",
  "succeededAt": "2026-10-25T09:00:06.000Z",
  "failedAt": null
}

The endpoint returns 404 when the ID is unknown or does not belong to the authenticated MTO. Use it for recovery, customer-support lookup, and reconciliation rather than aggressive polling.