Webhook Documentation

Inward Webhook Payload Details

Name	Description	Data Type	Values
id	The webhook id	number
amount	The amount received into the wallet	string
reference	The Verto unique reference for the payment	string
state	The current status of the payment	enum	Requested, archived, completed
currency	The currency of received into the wallet	string
paymentId	The unique id passed by the merchant. The value is null for inward payments.	string
type	The webhook type	enum	"type": "iban_to_wallet"
account	The full remitter details	object
account.id	The unique ID of the created remitter.	number
account.accountNumber	Indicates the remitter account number.	string
account.bankName	The name of the bank of the remitter.	string
account.beneficiaryAddress	The address of the remitter bank.	string
account.beneficiaryCity	The city of the remitter bank account.	string
account.beneficiaryCompanyName	The name of the remitter’s company.	string
account.beneficiaryCountryCode	2-character ISO 3166 country code.	string
account.beneficiaryEntityType	This denotes the type of the remitter.	string
account.beneficiaryPostcode	The ZIP code of the mailing address of the remitter	string
account.beneficiaryEmail	Email of the remitter	string
account.country	Name of the country of the remitter.	string
account.reference	Indicates the unique Verto reference number for the remitter created.	string
account.beneficiaryFirstName	First name of the remitter.	string
account.beneficiaryLastName	Last name of the remitter	string
account.nationalId	An identifier assigned to representing the remitter bank	string
account.currency	3-character ISO 4217 currency code representing the currency	string
account.clientReference	A client reference to be stored for this remitter	string
account.status	Indicates the current status of the given beneficiary.	string	pending, rejected, approved
walletId	The id of the wallet that received the funds	number
clientReference	The remitter details	string
bankingPartner	The banking partner Verto used to receive funds into the wallet	string
receivingAccount	The account number Verto used to receive funds into the wallet	string
createdDate	The date the transaction was created	datestring
completedDate	The date the transaction was completed	datestring
archivedDate	The date the transaction was archived	datestring
companyId	The id of the company	string

Inward Webhook Payload Details - Example

//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": null,
      "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": "null: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

FX Webhook Payload Details

Name	Description	Data Type	Values/Examples
id	The webhook id	number
reference	The Verto unique reference for the payment	string
amountFrom	The amount you’re converting	string
amountTo	The amount you or your beneficiary is receiving	string
rate	The full remitter details	number
transactionState	The current status of the payment	enum	outward_remittance_complete, inward_remittance_complete, inward_remittance_pending
status	The banking partner Verto used to receive funds into the wallet	enum	order_placed, deposit_recorded, archived, recipient_added, refunded
createdDate	The date the transaction was created	datestring
completedDate	The date the transaction was completed	datestring
archivedDate	The date the transaction was archived	datestring
clientReference	The remitter details	string
currencyFrom	The currency of received into the wallet	string
currencyTo	The unique id owned by the merchant	string

FX Webhook Payload Details - Example

{
  "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"
  }
}

Payout Webhook Payload Details

Name	Description	Data Type	Values
id	The webhook id	number
amount	The amount sent from the beneficiary from the wallet	string
reference	The Verto unique reference for the payment	string
state	The current status of the payment	enum	requested, archived, completed, refunded
currency	The currency of the wallet	string
paymentId	The unique id entered by the merchant	string
type	The webhook type	enum	"type": "wallet_to_account"
clientReference	The payment information entered by the sender when initiating the payment	string
account	The full beneficiary details	object
account.id	The unique ID of the created beneficiary.	number
account.accountNumber	Indicates the beneficiary's account number.	string
account.bankName	The name of the bank of the beneficiary.	string
account.beneficiaryAddress	The address of the beneficiary's bank.	string
account.beneficiaryCity	The city of the beneficiary's bank account.	string
account.beneficiaryCompanyName	The name of the beneficiary's company.	string
account.beneficiaryCountryCode	2-character ISO 3166 country code.	string
account.beneficiaryEntityType	This denotes the type of the beneficiary.	string
account.beneficiaryPostCode	The ZIP code of the mailing address of the beneficiary.	string
account.beneficiaryEmail	Email of the beneficiary	string
account.country	Name of the country of the beneficiary.	string
account.reference	Indicates the unique Verto reference number for the beneficiary created.	string
account.beneficiaryFirstName	First name of the beneficiary.	string
account.beneficiaryLastName	Last name of the beneficiary.	string
account.nationalId	A unique alphanumeric identifier that is used to identify the beneficiary bank.	string
account.currency	3-character ISO 4217 currency code representing the currency	string
account.clientReference	The narration to be stored for this beneficiary	string
account.status	Indicates the current status of the given beneficiary.	enum
walletId	The id of the wallet that sent the funds	number
completedDate	The date the transaction was completed	datestring
archivedDate	The date the transaction was archived	datestring

Payout Webhook Payload Details - Example

//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
  }
}

Wallet Statement Webhook

Name	Description	Data Type	Values
eventId	Unique identifier for this specific event.	string
eventType	Type of event	enum	`statement.ready`
createdAt	Timestamp when the webhook event was triggered (ISO 8601 format).	datestring
event	Event Object	object
event.walletId	ID of the wallet for which the statement was generated.	string
event.companyId	ID of the company to which the wallet belongs.	string
event.createdAt	When the statement was generated (same as createdAt above, but scoped to the payload).	datestring
event.dateFrom	Start of the statement period	datestring
event.dateTill	End of the statement period.	datestring
transactionCount	Number of transactions covered in this statement.	number
url	A direct link to download the PDF statement .	string

Wallet Statement Webhook - Example

{ 
  "eventId": "guid-string", 
  "eventType": "statement.ready", 
  "createdAt": "2025-04-14T12:00:00Z", 
  "event": { 
    "walletId": "wallet-123", 
    "companyId": "company-456", 
    "createdAt": "2025-04-14T12:00:00Z", 
    "dateFrom": "2025-01-01T00:00:00Z", 
    "dateTill": "2025-01-31T23:59:59Z", 
    "transactionCount": 128, 
    "url": "https://verto-cdn.com/statements/abc123.pdf" 
  } 
}

Refund Webhook

Name	Description	Data Type
eventId	Unique identifier for this specific event.	string
eventType	Type of event	enum
createdAt	Timestamp when the webhook event was triggered (ISO 8601 format).	datestring
event	Event Object	object
event.walletId	ID of the wallet where the original transaction was refunded from.	string
event.amount	Amount that was refunded, in minor units (check if it's cents or dollars based on context).	number
event.currency	Currency of the refunded amount, e.g., "USD".	string
event.reference	Transaction reference tied to the original operation.	string
event.refundedOn	Actual timestamp when the refund was processed.	datestring

Refund Webhook Example

{ 
  "eventId": "guid-string", 
  "eventType": "wallet.payment.refunded", 
  "createdAt": "2025-04-14T12:34:56Z", 
  "event": { 
    "walletId": "wallet-abc", 
    "amount": 1500, 
    "currency": "USD", 
    "reference": "txn-456789", 
    "refundedOn": "2025-04-14T12:30:00Z" 
  } 
}