Table of Contents
Event Types
Each event type designates a specific change to an api object. The event type describes the api object being changed as well as the change occurring.
ID | NAME | DESCRIPTION |
---|---|---|
1 | all | Matches all event types. |
2 | virtualcard.created | Triggered when a new virtual card is created. |
3 | virtualcard.deleted | Triggered when a virtual card is cancelled. |
5 | ach.status | Triggered when an ACH transfer fails. |
6 | virtualcard.realtime.auths | Triggered when authorization notification is received from MasterCard. |
8 | virtualcard.clearings | Triggered when a clearing notification is received from MasterCard. |
10 |
virtualcard.realtime.iccp.all |
Triggered when realtime authorization, advice or reversal notification is received from MasterCard ICCP. |
13 | ach.status.advice | Triggered for non-critical ACH status updates (status other than failed or corrected). |
Events
Event objects encapsulate detailed changes on an api object.
NAME | TYPE | DESCRIPTION |
---|---|---|
id | string | Uniquely identifies each event object. |
event_type | string | Name of event type (see event types). |
payload | object | Current state of the api object. |
previous | object | Previous state of the api object. |
created_at | datetime | Date and time event was created in default ISO 8601 format. |
Both the payload and previous json fields will contain an id which refers to the api object whose data has changed. When previous is null, it indicates no previous version of the object exists and the api object was created.
Example Event object:
{
"id": "101",
"event_type": "all",
"payload": {
"id": "201",
"status": "failed"
},
"previous": null,
"created_at": "2017-21-08T13:19:09.776Z",
"type": "event",
"url": "/v2/events/101"
}
Filtering:
This endpoint supports filtering. Depending on the event type, below parameters can be used to filter list of queried events. For more details on filtering, please refer to documentation on Conventions page.
PARAMETER | RANGE SUPPORT |
---|---|
merchant_amount |
Filter by range is supported |
approval_code |
N/A |
banknet_ref_num |
N/A |
billing_amount |
Filter by range is supported |
card_number |
N/A |
financial_network_code |
N/A |
mcc_description |
N/A |
mcc | N/A |
merchant_name |
N/A |
rcn_alias |
N/A |
rcn_id | N/A |
transaction_date_time |
Filter by range is supported |
transaction_type |
N/A |
vcn_id | N/A |
id | N/A |
status | N/A |
Merchant amount, banknet_ref_num and transaction_date_time fields support searches by a range. Below is an example query using transaction_date_time parameter:
Example with filtering:
{{URL}}/v2/events?page[limit]=1000& filter[payload.transaction_date_time]=[2020-07-10,2020-07-11]
Example response:
Header: "Prefer: return-minimal"
{
"data": [
{
"id": 123,
"type": "event",
"url": "/v2/events/123"
},
{
"id": 122,
"type": "event",
"url": "/v2/events/122"
},
{
"id": 121,
"type": "event",
"url": "/v2/events/121"
}
],
"links": {
"first": "/v2/events",
"next": null
}
}
Example response:
{
"data": [
{
"created_at": "2018-10-23T19:15:28.976Z",
"event_type": "ach.$$limit.exceeded",
"id": 25473,
"payload": {
"id": 340455
},
"previous": null,
"type": "event",
"url": "/v2/events/25473"
},
{
"created_at": "2020-08-17T02:03:11.205Z",
"event_type": "virtualcard.realtime.auths",
"id": 77012,
"payload": {
"acquirer_ica": "003286",
"approval_code": "020936",
"billing_amount": 4245,
"billing_currency": "USD",
"card_number": "556338######2882",
"issuer_response": "Approved",
"mcc": "8931",
"mcc_description": "ACCOUNTING, AUDITING AND BOOKKEEPING SERVICES",
"merchant_amount": 9090,
"merchant_currency": "USD",
"merchant_id": "242661000053360",
"merchant_name": "SQ *DELTA TOWING SAN ANTONIO TX",
"transaction_date_time": "2020-07-11T16:53:11.000Z",
"transaction_type": "Authorization Advice",
"vcn_id": 3090180,
"vcn_response": "Valid"
},
"previous": null,
"type": "event",
"url": "/v2/events/77012"
},
{
"created_at": "2019-10-25T10:20:03.696Z",
"event_type": "ach.status",
"id": 75773,
"payload": {
"id": 5956,
"return_code": "R01",
"status": "failed"
},
"previous": {
"id": 5956,
"return_code": null,
"status": "processing"
},
"type": "event",
"url": "/v2/events/75773"
},
{
"created_at": "2020-08-18T19:22:22.680Z",
"event_type": "onboarding.company.status",
"id": 77083,
"payload": {
"id": 28827,
"status": "pending"
},
"previous": null,
"type": "event",
"url": "/v2/events/77083"
},
{
"created_at": "2020-08-18T19:22:07.671Z",
"event_type": "virtualcard.created",
"id": 77081,
"payload": {
"available_balance": 12345,
"currency": "USD",
"id": "3188156",
"per_transaction_max": 12345,
"per_transaction_min": 0,
"rcn_alias": "Test Account 1",
"rcn_id": 126507,
"status": "Approved",
"total_card_amount": 12345,
"transactions_max": 41,
"valid_ending_on": "2021-12-31",
"valid_starting_on": "2020-08-17"
},
"previous": null,
"type": "event",
"url": "/v2/events/77081"
}
]
}
Test a Webhook
To help aid in debugging whether a webhook has been configured correctly, the test route can be used to manually trigger a webhook.
The response status of the callback url will be returned.
Note: - both active
and inactive
webhooks will be triggered by the test route - event type ids attached to the webhook are ignored - a test type “webhooks.test” will be attached to the webhook payload - an event id of 0 will be attached to the payload, indicating test data - the payload data will return data from the webhook being tested
Request:
GET /v2/webhooks/:id/test
Response:
200 OK
Test webhook resource response.
Example response:
{
"data": {
"status": 200
}
}
Example test webhook request body:
{
"data": {
"date": "2017-08-21T16:34:26.330Z",
"event-id": 0,
"payload": {
"id": 123,
"callback_url": "https://www.api-svb.com/svb-webhooks",
"event_type_ids": [1],
"status": "active"
},
"type": "webhooks.test"
}
}
Webhook Retries
Webhooks will be retried anytime we do not receive a successful response from the destination url/server, in other words, if we receive a 5xx response. We will send the retries a total of 5 times with the following spacing:
ATTEMPT | TIME |
---|---|
First attempt | 0 |
Second attempt | 10minutes |
Third attempt | 28 minutes |
Fourth Attempt | 78 minutes |
Fifth Attempt | 108 minutes |