Payment Services
The Payment Services API covers outbound payments from a Verto wallet to an external beneficiary, internal wallet-to-wallet transfers, and document upload for supporting payment flows.
All payments are initiated asynchronously — the create endpoint returns immediately with a status of requested, and the payment progresses through subsequent states as it is processed. Webhooks are the recommended approach for tracking status changes in real time rather than polling.
Payment statuses
| Status | Description |
|---|---|
requested | The payment has been accepted and the source wallet debited. This is the status returned at the point of creation. |
completed | Verto has sent the funds to the beneficiary. Note this confirms the payment has left Verto — it does not guarantee the beneficiary's bank has credited the account, particularly for SWIFT payments where correspondent banks exist. |
refunded | A completed payment was reversed and funds returned to the source wallet. Terminal. |
archived | The payment was cancelled or failed. Ledger entries are reversed and funds returned to the source wallet. Terminal. The reason is given in the archiveReason field. |
Webhooks are recommended for real-time status updates. See the Webhooks guide and Wallet to Account webhooks for event details and payload structure.
archiveReason
When a payment moves to archived, the archiveReason field in the response and webhook payload provides the reason for cancellation or failure. Common reasons include compliance review rejection, invalid beneficiary account details, and rejection by the recipient bank.
If a payment is archived unexpectedly, contact [email protected] with the paymentId for investigation.
Idempotency
All payment creation requests accept a paymentId field — a UUID you generate and supply. This acts as an idempotency key. If the same paymentId is submitted more than once, only one payment will be created. You should generate a unique paymentId per payment and store it on your side to allow for safe retries without risk of duplicate payments.
Sender object
For fintech and FI clients making payments on behalf of underlying customers from a master wallet, a sender object must be included in the payment request. This is not required for corporate principal-basis payments or payments initiated from a sub-account.
See the Sender object guide for full details.
| Endpoint | Description |
|---|---|
POST Create a payment request | Initiate an outbound payment from a Verto wallet to an external beneficiary across SWIFT, Local Payment Networks & Stablecoin. |
POST Initiate a transfer to another wallet | Move funds between Verto wallets — same account (instant) or between Verto accounts (real-time). |
GET Retrieve payment details | Fetch the current status and details of a payment by paymentId |
GET Get payment tracking details | Retrieve the scheme-level tracking reference for a completed payment — UETR for SWIFT, Session ID for NGN, or tracking ID for KES. Use this before raising a payment investigation or SWIFT tracing. |
GET List payment purpose codes | Retrieve the list of valid purpose codes for your account |
POST Generate document upload link | Generate a pre-signed URL to upload a supporting document for attachment to a payment |