Webhooks

The specific webhook event type triggered. For example, 'virtualcard.created.failed' indicates a failed attempt to create a virtual card.

Unique identifier for the failed virtual card creation attempt. Useful for referencing the failed transaction in logs or support cases.

Detailed message describing why the virtual card creation failed. Often used for debugging or notifying the user about the issue.

The unique identifier of the company that initiated the virtual card creation request.

A unique identifier for the specific card creation request. This can be used to cross-reference requests in internal systems.

Type of webhook event. Indicates the creation of a virtual card was successful. This helps identify the nature of the action that triggered the webhook.

The unique identifier of the newly created virtual card. This ID can be used to retrieve card details, track card-related activities, or reference the card in support tickets and internal systems.

Current status of the virtual card. Typically 'active' if successfully created. This indicates whether the card is ready for transactions or needs further activation steps.

The UUID of the company associated with the newly created card. It links the virtual card to the specific organization that initiated the creation request.

Unique reference string used to identify the card creation request. It can be used for deduplication, auditing, reconciliation, and tracking purposes across systems.

Status of the creation process. Should be 'success' if the card was created without issues. This field provides a final confirmation of the card generation outcome and can be used to validate the process.

Webhook event type. This event indicates that a virtual card was successfully topped up. It is useful for identifying the nature of the transaction and triggering downstream actions.

Unique identifier for the top-up transaction. This can be used to reference the transaction in your database, audit logs, or support queries.

The amount that was credited to the virtual card. This value is typically in the card’s currency and reflects the exact top-up amount.

The unique identifier of the virtual card that was topped up. This allows you to associate the transaction with the correct card and user account.

Status of the top-up transaction. Expected value: 'success'. Helps confirm that the transaction was completed and funds are available.

The UUID of the company that owns the virtual card. Useful for identifying which organization's card was involved in the top-up.

A brief description or note for the top-up transaction. This may include the purpose of the top-up or additional metadata for internal reporting.

A unique reference ID used to trace the top-up event. Helpful for reconciling transactions and resolving issues if they arise.

Webhook event type indicating a successful virtual card withdrawal (virtualcard.withdrawal.success). This is useful for filtering or routing webhook handling logic.

Overall status of the withdrawal transaction. Expected value is 'success', confirming the operation completed without errors.

Unique identifier of the virtual card from which funds were withdrawn. This helps identify the specific card affected by the transaction.

Unique identifier for this withdrawal transaction. It can be used for transaction lookup, reconciliation, and auditing.

UUID of the company that owns the virtual card. This helps associate the withdrawal with the correct organizational context.

Amount of money that was successfully withdrawn from the virtual card. This reflects the debit value for the transaction.

Unique reference ID used to trace or correlate the withdrawal event across systems and logs.

A brief note, description, or purpose for the withdrawal. It can aid in reporting or user-facing transaction histories.

Indicates whether the virtual card was terminated following the withdrawal. A value of 'false' means the card is still active.

The webhook event type for a debit transaction. This helps you identify and route this webhook (e.g., 'virtualcard.transaction.debit').

The unique identifier of the debit transaction. Useful for reconciliation and tracking in transaction history.

The amount of money that was debited from the virtual card as part of this transaction.

The unique identifier of the virtual card that was charged in this debit transaction.

The explanation or note regarding the debit transaction, if any. May be null if no specific reason is provided.

The outcome of the transaction. Typically 'success', but may vary depending on processing results.

The unique identifier of the company that owns the virtual card associated with this transaction.

A human-readable description of the transaction, often including the merchant or payment processor name.

A unique reference string assigned to this transaction. It can be used to trace or query the transaction across systems.

The webhook event type for a failed withdrawal. Example: 'virtualcard.withdrawal.failed'. This helps identify the nature of the webhook event.

The unique identifier for the specific withdrawal attempt. Useful for transaction logging and debugging.

The amount that was attempted to be withdrawn from the virtual card. This value was not successfully debited.

The identifier of the virtual card involved in the withdrawal attempt. Links the failed transaction to the card.

The status of the withdrawal transaction. Expected value for this event is 'failed'.

The UUID of the company that owns the virtual card. Helps map the transaction back to a specific business account.

A brief human-readable description of the transaction, such as the transaction purpose or source.

A unique reference string associated with this withdrawal transaction. Useful for reconciliation and tracking.

Indicates whether the card was terminated as a result of the failed withdrawal. 'false' means the card remains active.

The webhook event type indicating that a previous debit transaction on a virtual card has been successfully reversed. Event value: 'virtualcard.transaction.reversed'.

The unique identifier for the reversal transaction. This ID helps trace the specific reversal event in your records.

The amount of money that was refunded back to the virtual card as part of the reversal.

The unique identifier of the virtual card involved in the reversed transaction.

An optional field that may include a short explanation or code detailing the cause of the reversal. Can be null if not provided.

Indicates the outcome of the reversal process. Expected value: 'success'.

The UUID of the company that owns or issued the virtual card involved in the reversal.

A human-readable description of the transaction. Typically includes the merchant name or reason for the original charge.

A unique reference identifier that ties this reversal transaction to the original debit or purchase transaction.

The webhook event type indicating that a virtual card transaction was declined and the card was frozen as a result. Typically triggered for security reasons such as suspected fraud.

The unique identifier of the virtual card that was frozen due to the declined transaction. This ID allows you to track or take further action on the affected card.

A descriptive message explaining why the card was frozen. Example: 'Suspected Fraud' or 'Multiple failed attempts'.

The UUID of the company that owns or issued the virtual card. Useful for identifying which business account the frozen card belongs to.

A unique reference ID associated with the declined transaction that triggered the card freeze. It can be used for logging or auditing purposes.

The webhook event type indicating that a virtual card transaction was declined and the card was frozen as a result. Typically triggered for security reasons such as suspected fraud.

The unique identifier of the virtual card that was frozen due to the declined transaction. This ID allows you to track or take further action on the affected card.

A descriptive message explaining why the card was frozen. Example: 'Suspected Fraud' or 'Multiple failed attempts'.

The UUID of the company that owns or issued the virtual card. Useful for identifying which business account the frozen card belongs to.

A unique reference ID associated with the declined transaction that triggered the card freeze. It can be used for logging or auditing purposes.

Balance available before the card was terminated.

The webhook event type for a failed authorization transaction. Indicates that a virtual card transaction could not be completed during the authorization phase.

Unique identifier for the failed authorization attempt. Useful for tracking and debugging.

The amount that was attempted during the failed authorization.

The unique ID of the virtual card used in the failed authorization attempt.

Explanation for why the authorization failed. Example: 'insufficient funds'.

The transaction status field. May still return 'success' for webhook delivery even if authorization failed.

Unique identifier of the company that owns the virtual card involved in the transaction.

Unique reference string to help trace the failed transaction in logs or support tickets.

The webhook event type for a cross-border charge. Indicates that a fee was applied due to an international transaction.

The original amount of the transaction that triggered the cross-border charge. This is the actual purchase amount before fees.

The unique identifier of the virtual card used in the cross-border transaction.

The processing status of the cross-border charge (e.g., 'success' if the charge was applied successfully).

The unique ID of the company that owns the virtual card used in the transaction.

The merchant name or description associated with the transaction. This typically helps identify the vendor or service.

The specific amount deducted as a cross-border fee from the wallet or card.

The webhook event name triggered when a virtual card is created successfully. Typically: 'virtualcard.created.success'.

The unique identifier assigned to the newly created virtual card. Useful for referencing and tracking the card.

The current operational status of the virtual card. Usually 'active' immediately after a successful creation.

The unique identifier of the company or organization that owns the newly created virtual card.

A unique string reference generated during the card creation process. Used for tracking and reconciliation.

The outcome of the card creation request. A value of 'success' indicates the card was issued without errors.

The webhook event name indicating a successful KYC verification for a virtual card user. Typically: 'virtualcard.user.kyc.success'.

A unique identifier for the KYC record associated with the user verification event.

The unique ID of the company that owns or manages the virtual card user undergoing KYC.

Boolean value indicating the result of the KYC process. A value of 'true' confirms the user passed verification.

A unique identifier representing the virtual card customer whose KYC status was updated.

A unique identifier for a previously registered user in your system. It could be an email address or user id.

Webhook event name indicating that a refund was issued for a transaction on a terminated virtual card. Typically: 'virtualcard.transaction.terminated.refund'.

A unique identifier representing the refund transaction. Used for tracking and reconciliation.

The timestamp when the refund was processed, formatted in ISO 8601 (e.g., '2024-08-04T20:51:57.290Z').

The monetary amount refunded to the cardholder or company account. Represented as a string to maintain precision.

The unique identifier of the virtual card that was terminated and refunded.

An optional field that provides additional context on why the refund was issued. Can be null if no specific reason is recorded.

Indicates the final status of the refund process. Example: 'success'.

The UUID of the company that owns the terminated virtual card.

A short description or message associated with the refund transaction, providing context for the refund.

A unique reference code used to trace and audit the refund operation.

The name of the webhook event that was triggered. In this case, it indicates that a beneficiary's status has changed (e.g., 'beneficiary.status.changed').

A unique identifier for the beneficiary object. This ID can be used to retrieve more details about the beneficiary or to reconcile data with your internal records.

Represents the current state of the beneficiary. For example, 'pending' if the beneficiary is being processed, or 'success' if the beneficiary is ready to receive funds.

A unique string used to link this webhook notification to the original beneficiary creation request.

An optional URL that was provided during the beneficiary creation process for receiving callbacks. If set, the system may attempt to notify this URL after processing is complete. If not provided, this will be null.

The unique identifier of the company to which the beneficiary belongs. This value can help you ensure the webhook data is scoped correctly to the right organization within a multi-tenant system.

Indicates the type of webhook event triggered. In this case, it signifies that the beneficiary status is in a 'pending' state after being added.

The unique identifier of the company that owns or initiated the creation of the beneficiary.

A unique identifier assigned to the newly added beneficiary for tracking and reference purposes.

A unique reference string used to trace and identify the specific beneficiary setup request.

Represents the current status of the beneficiary setup. Typically set to 'pending' at this stage until processing is complete.

Specifies the webhook event type. In this case, it confirms the beneficiary was successfully added.

A unique identifier for the company that owns or added the beneficiary.

The unique ID assigned to the beneficiary. Useful for lookup or future reference.

A unique string used to track and identify the beneficiary setup request.

The current state of the beneficiary. For successful creation, this will be 'success'.

An optional URL provided to receive asynchronous updates about the beneficiary setup outcome.

Webhook event name that indicates a successful payout transfer.

Represents the fee charged for processing the payout transaction.

The nature of the transaction. Typically set to 'debit' for outgoing funds.

The total amount transferred in the payout transaction.

Status of the payout operation. For successful transactions, this is usually 'success'.

The medium or route used for processing the payout. Commonly 'payout'.

A unique identifier for tracing or reconciling the payout event.

Describes the specific type of payout action, such as 'ngn_account_payout'.

The unique ID assigned to the payout transaction for tracking.

The UUID of the company that initiated or owns the payout transaction.

Optional URL provided for receiving asynchronous callbacks or status updates.

Webhook event type indicating a successful receipt of USDT stablecoin. This value helps you programmatically identify and handle this specific webhook event (e.g., 'stablecoin.usdt.received.success').

Unique identifier for the stablecoin transaction record. This ID can be used to reference or look up the transaction within your system or for auditing purposes.

Fee applied to the transaction, typically represented as a string. This value is usually '0' for incoming transfers, but may vary depending on your pricing or network conditions.

Blockchain transaction hash that uniquely identifies the transaction on the chain. Useful for transaction verification and external blockchain explorers.

Specifies the transaction direction. For receipts, this will always be 'credit', indicating an incoming transaction to the specified wallet address.

The blockchain network where the transaction was processed. Common values include 'tron', 'ethereum', or other supported chains.

Defines the nature of the event. For this webhook, it’s typically 'receive_usdt', which helps differentiate between send and receive flows.

The exact amount of USDT received, represented as a string for precision. This is the gross amount before any fees are deducted.

The recipient's wallet address that received the USDT. This address belongs to the end user or the company’s account.

The method of delivery. 'onchain' indicates that this transaction occurred directly on the blockchain, not via an internal or off-chain route.

Fee charged for the transaction in the smallest currency unit (e.g., cents). Enables precise accounting for transaction costs.

Unique identifier of the company associated with this transaction. This allows mapping the transaction to a specific business account within your system.

A system-generated unique reference string used to track and correlate this transaction across logs, databases, or customer support tickets.

The total amount received, represented in the smallest denomination (e.g., cents or satoshis), ensuring accurate financial record-keeping.

A brief message or purpose related to the transaction. Typically contains user-friendly information like 'Received USDT payment'.

The number of blockchain confirmations at the time the webhook was sent. A higher number of confirmations means a more secure and irreversible transaction.