Webhooks
As discussed in Webhook under Configuration in Understanding Dashboard Settings, a webhook (also called a web callback or HTTP push API) is an automated method that lets Token provide you with real-time updates regarding single immediate payment initiation status, refund status, standing order submission status, variable recurring payment initiation status, and variable recurring payment consent status. Consequently, configuring a Token webhook eliminates the need to poll for data to get the latest status.
When configured to do so, Token webhooks notify you when the status changes for the following:
- Single Immediate Payment
- Refund
- Standing Order Setup
- Variable Recurring Payment Initiation and Variable Recurring Payment Consent Setup
Final status may not be immediately known, so Token polls the bank periodically until the final status is available. Polling stops once the final status is received.
You can configure the webhook to receive notifications for transfers, refunds, standing order submissions, and variable recurring payment initiations. POST
notification will be sent to your configured webhook URL when its status changes or when the request status is still intermediate (pending/processing) but the bank payment status or bank standing order status changes.
The notification will contain a transactionId
(optional, depending on bank support), transferId
, refId
, and the current
transfer status
. At the bank's option, it may include the original payment status in bankPaymentStatus
or bankStandingOrderStatus
, respectively.
For a list of possible transfer states, see Payment initiation status.
You can configure your webhook(s) using either the dashboard or the API. For guidance on configuring a webhook using the dashboard, see Understanding Dashboard Settings >Configuration>Webhook. Configuring a webhook using the API is discussed below.
Setting Up Webhooks using the API
You'll need to configure the event(s) for which you wish to receive webhook notifications. This is often referred to as "event subscription."
To subscribe to an event, make a PUT /webhook/config call and place the details in the body, structured like this example:
{
"config"
: {
"type"
: [ "TRANSFER_STATUS_CHANGED", "STANDING_ORDER_STATUS_CHANGED"],
"url"
: "your-webhook-url.com"
}
}
The respective fields are defined in the following table:
Field | Description/Subfields | Required/Optional | |
---|---|---|---|
config | Contains the configuration parameters | Required | |
type | Specifies the types of webhook to configure; available values: TRANSFER_STATUS_CHANGED, STANDING_ORDER_STATUS_CHANGED, REFUND_STATUS_CHANGED, VRP_STATUS_CHANGED, or VRP_CONSENT_STATUS_CHANGED |
Required | |
url | Specifies the webhook URL that will receive status updates | Required |
Once configured, you can retrieve your current webhook configuration with a GET /webhook/config call. Because you are limited to one configuration, no request parameters are needed. The response will specify the type and url properties in the config object.
{
"config"
: {
"type"
: [ "TRANSFER_STATUS_CHANGED", "STANDING_ORDER_STATUS_CHANGED"],
"url"
: "your-webhook-url.com"
}
}
You can delete your webhook configuration at any time with a DELETE /webhook/config call. No request parameters are required. If successful, an empty 200 response is returned.
Receiving Webhook Notifications
For transfers, the webhook url you configure will receive an HTTP POST message with the following message Headers and transfer status payload:
// Token Headers
:84p7oxffpN6fui9FGCq8YWNYPAFqzJTEET_JtnddYRCnZl_Nt7J4QYBGAgJzVr_MK_DFi75CBOlzef0CWGEmBw
:TRANSFER_STATUS_CHANGED
// Body
{
"createdAtMs"
: "1624649550800",
"id"
: "c95dd32d-8248-48e8-bbc9-a6391377156e",
"transferStatusChanged"
: {
"refId"
: "4iWznLG7pgTSWAddN", // refId sent in the original transfer request
"bankPaymentStatus"
: "ACSC", // original status of submitted request
"status"
: "SUCCESS", // updated status
"statusReasonInformation"
: "AcceptedSettlementCompleted", // see Understanding Payment Initiation Status
"tokenRequestId"
: "rq:2a1M4FNGFceEUqe43zFJ1DcvFhfe:5zKtXEAq", // original token request ID
"transferId"
: "t:GDK27TpvHk7AqjfUMKKqD6RXpusXEztxWbN49Acw43qx:5zKZFPab",
"transactionId"
: "x:HLSpd8758wq43QYBGAgJzVr_MK_DFi75CBOlzef0CWGEmBw"
}
}
For refunds, the headers and payload change to a structure like this:
// Token Headers
:84p7oxffpN6fui9FGCq8YWNYPAFqzJTEET_JtnddYRCnZl_Nt7J4QYBGAgJzVr_MK_DFi75CBOlzef0CWGEmBw
:REFUND_STATUS_CHANGED
// Body
{
"createdAtMs"
: "1624649550800",
"id"
: "c95dd32d-8248-48e8-bbc9-a6391377156e",
"refundStatusChanged"
: {
"refundId"
: "t:7zetxHfMVGWGoRiXpbwsUpi9hPkTRcztHgN1pcB6NdFL:4hGHHfghRwL4vkbwQqf", // refundId sent in the original refund request
"memberId"
: "m:3x4aiZ1mg9foVJiJ9LVG1LybGUKA:5zKtXEAq", // memberID sent in the origination refund request
"status"
: "INITIATION_PROCESSING", // updated status
"bankTransactionID"
: "3321720220503", // bank generated unique identifier for the refund
"bankPaymentStatus"
: "AcceptedSettlementCompleted", // payment status returned by the bank
"transactionId"
: "x:HLSpd8758wq43QYBGAgJzVr_MK_DFi75CBOlzef0CWGEmBw",
}
}
For standing orders, the headers and payload change to a structure like this:
// Token Headers
:84p7oxffpN6fui9FGCq8YWNYPAFqzJTEET_JtnddYRCnZl_Nt7J4QYBGAgJzVr_MK_DFi75CBOlzef0CWGEmBw
:STANDING_ORDER_STATUS_CHANGED
// Body
{
"createdAtMs"
: "1624649550800",
"id"
: "c95dd32d-8248-48e8-bbc9-a6331977156e",
"standingOrderStatusChanged"
: {
"standingOrderStatus"
: {
"refId"
: "4iWznLG7pgTSWAddN", // refId sent in the original standing order request
"bankStandingOrderStatus"
: "PENDING", // original status of submitted requested
"status"
: "SUCCESS", // updated status
"submissionId"
: 3Psodjflg0ds9sGH9, // submission id of the standing order
"standingOrderId"
: "t:GDK27TpvHk7AqjfUMKKqD6RXpusXEztxWbN49Acw43qx:5zKZFPab", // bank-dependent standing order ID; optional
}
}
}
For variable recurring payments, the headers and payload change to a structure like this:
// Token Headers
:84p7oxffpN6fui9FGCq8YWNYPAFqzJTEET_JtnddYRCnZl_Nt7J4QYBGAgJzVr_MK_DFi75CBOlzef0CWGEmBw
:VRP_STATUS_CHANGED
// Body
{
"createdAtMs"
: "1624649550800",
"id"
: "c95dd32d-8248-48e8-bbc9-a6391377156e",
"vrpStatusChanged"
: {
"vrpId"
: "4iWznLG7pgTSWAddN", // vrpId sent in the original transfer request
"bankVrpId"
: "9iBznLG7pgGSWAdcZ", // bank generated unique identifier for the initiated payment
"consentId"
: "vc:kdakdhajsdah:kdjskjd", // VRP consent for which the payment was initiated
"status"
: "INITIATION_COMPLETED", // current status of the VRP
"bankVrpStatus"
: "AcceptedCreditSettlementCompleted", // payment status returned by the bank
}
}
If available, vrpStatusChanged.statusReasonInformation will display the status reason information returned by the bank.
For variable recurring payment consent setup, the headers and payload change to a structure like this:
// Token Headers
:84p7oxffpN6fui9FGCq8YWNYPAFqzJTEET_JtnddYRCnZl_Nt7J4QYBGAgJzVr_MK_DFi75CBOlzef0CWGEmBw
:VRP_CONSENT_STATUS_CHANGED
// Body
{
"createdAtMs"
: "1624649550800",
"id"
: "c95dd32d-8248-48e8-bbc9-a6391377156e",
"vrpConsentStatusChanged"
: {
"consentId"
: "vc:kdakdhajsdah:kdjskjd",// id of initiated VRP Consent
"bankVrpConsentId"
: "9iBznLG7pgGSWAdcZ",// bank generated unique identifier for the initiated VRP Consent
"status"
: "AUTHORIZED",// current status of the VRP Consent
"bankVrpConsentStatus"
: "AcceptedCreditSettlementCompleted",// VRP consent status returned by the bank
}
}
If available, vrpConsentStatusChanged.statusReasonInformation will display the status reason information returned by the bank.
See Swagger Object and Field Definitions for additional details on Single Immediate Payment, Standing Orders, and Refunds.
Please refer to the Token.io API reference for additional details.