Webhooks
A Guide to Real-Time Notifications
The Verto API generates and sends webhook messages to your defined URL responding to specific events, providing real-time updates and notifications. These webhook events ensure that you stay informed about important activities related to FX orders, beneficiaries, payments, and inward payments.
By setting up webhooks, you can automate responses, trigger workflows, and maintain a seamless and efficient operational process.
Webhook events
- FX Status Changes:
- FX Order Created: A new FX (foreign exchange) order is initiated.
- Inward FX Order Confirmed: Confirmation that an inward FX order has been successfully received and acknowledged.
- Outward FX Order Completed: An outward FX order has been successfully executed and completed.
- FX Order Archived: An FX order has been moved to an archived state, indicating no longer active.
- FX Order Disputed: An FX order has encountered a dispute and requires further action or resolution.
- Beneficiary Status Changes:
- Beneficiary Created (Pending): A new beneficiary has been created with a pending status and is awaiting approval or further verification.
- Beneficiary Approved: A beneficiary has been reviewed and approved, making it active and available for transactions.
- Beneficiary Rejected: A beneficiary has been reviewed and rejected, preventing it from being used for transactions.
- Payment (Payout) Status Changes:
- Payment Request Initiated: A payment request has been initiated and is awaiting processing.
- Payment Request Completed: A payment request has been successfully processed and completed.
- Payment Request Refunded: A previously completed payment request has been refunded to the original payer.
- Payment Request Archived: A payment request has been moved to an archived state, indicating no longer active.
- Inward Payment (Inbound) Status Changes:
- Inward Payment Received (requested): Funds have been successfully received by Verto from an external source. This may be through Verto's global and local accounts feature or directly from another business within the Verto network. However, inward payments received at Verto are not immediately added to your wallet; they must first clear the necessary compliance checks to ensure security and regulatory compliance.
- Funds Added to Wallet (completed): The inward payment has been processed and successfully added to your wallet, making the funds available for use.
Webhook notification limitationsWe don’t notify on any actions taken by the VertoFX admin team, but only for requests created by you or your customers. These would include actions like a manual credit into your wallet done by the verto operations team in order to check balance use the wallet listing APIs.
Receiving webhooks
To configure the webhooks from your account
-
Login to the production or sandbox account
-
Go to Verto API on sidebar
-
Go to webhook settings
-
Save and continue
-
Once you’re done configuring the callback URLs it should look something like this
Webhook Logs
The section discusses webhook logs, which track the webhooks sent and the corresponding responses received from the client.
Attributes | Description |
|---|---|
type | [ PAYMENT_STATUS_CHANGE, FX_STATUS_CHANGE, BENEFICIARY_STATUS_CHANGE ][ PAYMENT_STATUS_CHANGE, FX_STATUS_CHANGE, BENEFICIARY_STATUS_CHANGE ] You can expect to have 3 enum values |
payload | The payload is based on the type of response received |
Status | The webhook was successfully consumed or received |
Response Body | What was received after consuming the webhook |
Response Time | The time it took to receive the webhook response |
Authorization
Verto API does not require authorization for callbacks. However, it is recommended to whitelist specific IP addresses for both Sandbox and Production environments to ensure proper functionality.
The suggested IP addresses are:
- 18.157.51.166
- 18.198.227.220
- 18.235.242.90
- 3.208.60.185
Webhook Payloads
The payload in the response would have the object for a successful API call for getting the corresponding data type.
//Example of the web hooks structure
{
"payload": {
//Response for API goes here
}
}
//Example response for a Beneficiary Approved
{
"payload": {
"id": 9734,
"accountNumber": "121212184874848",
"bankName": "Punjab National Bank",
"beneficiaryAddress": "Plot No 4, Sector -10 Dwarka",
"beneficiaryCity": "New Delhi",
"beneficiaryCompanyName": "Test 3 ",
"beneficiaryCountryCode": "IN",
"beneficiaryEntityType": "company",
"beneficiaryPostcode": "110075",
"country": "India",
"reference": "RP-09112022-006",
"nationalId": "PUNB0657700",
"currency": "INR",
"clientReference": "",
"status": "approved"
}
}
//Example response for a payment outward approved
{
"payload": {
"id": 6548,
"amount": "200000.00",
"reference": "TO-22092024-005",
"state": "completed",
"currency": "NGN",
"paymentId": null,
"type": "wallet_to_account",
"clientReference": null,
"account": {
"id": 4369,
"accountNumber": "9079135431",
"bankName": "MONIEPOINT MICROFINANCE BANK",
"beneficiaryAddress": "",
"beneficiaryCity": "",
"beneficiaryCompanyName": "",
"beneficiaryCountryCode": "",
"beneficiaryEntityType": "individual",
"beneficiaryPostcode": "",
"beneficiaryEmail": "",
"country": "Nigeria",
"reference": "RP-19062024-003",
"beneficiaryFirstName": "Daniel",
"beneficiaryLastName": "Torkura",
"nationalId": "090405",
"currency": "NGN",
"clientReference": "",
"status": "approved"
},
"walletId": 2561,
"createdDate": "2024-09-22T14:26:07.000Z",
"completedDate": "2024-09-22T14:26:46.018Z",
"archivedDate": null
}
}
//Example response for an inward payment to wallet from an external entity
{
"payload": {
"id": 47987,
"amount": "234017.00",
"reference": "TO-12022025-4367",
"state": "requested",
"currency": "NGN",
"paymentId": null,
"type": "iban_to_wallet",
"account": {
"id": 44197,
"accountNumber": "12345678919",
"bankName": null,
"beneficiaryAddress": null,
"beneficiaryCity": null,
"beneficiaryCompanyName": "Test",
"beneficiaryCountryCode": "NG",
"beneficiaryEntityType": "company",
"beneficiaryPostcode": null,
"beneficiaryEmail": null,
"country": null,
"reference": "RP-12022025-406",
"beneficiaryFirstName": null,
"beneficiaryLastName": null,
"nationalId": "ACCTY67",
"currency": "NGN",
"clientReference": null,
"status": "approved"
},
"walletId": 28993,
"clientReference": "testsubmorning2:Test:12345678919:ACCTY67",
"bankingPartner": "Paga",
"receivingAccount": "9079135413",
"createdDate": "2025-02-12T06:23:55.000Z",
"completedDate": null,
"archivedDate": null,
"companyId": "4574"
}
}
//"clientReference": "customReferenceLabel : "vendorReferenceId : ultimateDebitorName : ultimateDebitorIdentifier : ultimateDebitorFinancialInstitution"
//vendorReferenceId - Sender reference (e.g Collaboration 09087).
//ultimateDebitorName - Sender’s name.
//ultimateDebitorIdentifier - Sender’s account number.
//ultimateDebitorFinancialInstitution - Sender’s Bank.
//Example response for an FX order being inward confirmed
{
"payload": {
"id": 3791,
"reference": "EN-22092024-004",
"amountFrom": "10000000.00",
"amountTo": "7506100.00",
"rate": "0.7506100000",
"transactionState": "outward_remittance_complete",
"status": "deposit_recorded",
"createdDate": "2024-09-22T14:18:51.000Z",
"completedDate": "2024-09-22T14:20:08.278Z",
"archivedDate": null,
"clientReference": null,
"currencyFrom": "USD",
"currencyTo": "GBP"
}
}
// Wallet to wallet inbound webhook
{
"payload": {
"id": 6547,
"amount": "20000.00",
"reference": "TO-22092024-004",
"state": "completed",
"currency": "USD",
"paymentId": null,
"type": "wallet_to_wallet",
"clientReference": null,
"walletId": 3063,
"transactionType": "credit",
"toWalletId": 3063,
"fromWalletId": 2558,
"createdDate": "2024-09-22T14:13:51.000Z",
"completedDate": "2024-09-22T14:13:51.000Z",
"archivedDate": null
}
}
// Wallet to wallet outbound webhook
{
"payload": {
"id": 6547,
"amount": "20000.00",
"reference": "TO-22092024-004",
"state": "completed",
"currency": "USD",
"paymentId": null,
"type": "wallet_to_wallet",
"clientReference": null,
"walletId": 2558,
"transactionType": "debit",
"toWalletId": 3063,
"fromWalletId": 2558,
"createdDate": "2024-09-22T14:13:51.000Z",
"completedDate": "2024-09-22T14:13:51.000Z",
"archivedDate": null
}
}Captured Events by Type
Captured Events by Type refers to the different kinds of events that have been recorded.
Event | Type | Transaction Status | Description |
|---|---|---|---|
Payment request created from client | PAYMENT_STATUS_CHANGE | Requested | This is the initial status received by the first request the system makes to Verto API |
Payments made to a beneficiary by Verto | PAYMENT_STATUS_CHANGE | Completed | The transaction has been successfully completed. |
Payments are archived and refunded | PAYMENT_STATUS_CHANGE | Archived | The transaction has been achieved |
When payments are disputed | PAYMENT_STATUS_CHANGE | disputed | When the payment request did not result in a pay in into our accounts |
Payments received from other entities (Into your Global account or wallet) | PAYMENT_STATUS_CHANGE | Requested | Whenever a payment from an external entity, you get a webhook for the request being created |
Payments received from other entities | PAYMENT_STATUS_CHANGE | Completed | Whenever you receive a payment from an external entity or transfer money into your wallet, you get a webhook for the request completed. |
When an FX order is created | FX_STATUS_CHANGE | inward_remittance_pending | This is the initial status received by the first request that the system makes to Verto API.
|
When an FX order is confirmed | FX_STATUS_CHANGE | inward_remittance_confirmed | The order was acknowledged and confirmed.
|
When an FX order is disputed | FX_STATUS_CHANGE | inward_remittance_disputed | The inward FX transaction is disputed |
When the FX conversion is completed and paid out | FX_STATUS_CHANGE | outward_remittance_complete | The payment is completed |