The Event object represents a change of state to an api object. Each event type will have a specialized schema to best describe the changes to the object.

The Webhooks object represents information on how to communicate to an api user about useful api events. Allowing the api to contact the api user, bypassing the need of constant polling by the api user.

Webhooks are signed using a similar HMAC schema as found in the authentication documentation. A few minor differences exist noted below.

The signature is calculated using the following fields:

Using this algorithm:

1. Let + be a function that concatenates strings, and let "\n" indicate a newline character;
2. Let HMAC be a function that calculates an HMAC from a string and a secret key, and let HEX be a function that returns the string hexadecimal representation of its input; then
3. The signature is:
   

     HEX( HMAC( your_secret_key,
                timestamp + "\n"
                method + "\n" +
                url + "\n" +
                body ))

For more information on HMAC signing, see the section on authentication documentation.

 There are three VCN related events that can be triggered. Following events can be tracked using webhooks. 

Request:

GET /v1/events/types

Response:

200 OK List of event type resources.

Example request:

curl "https://api.svb.com/v1/events/types" \
    -H "Authorization: Bearer YOUR_API_KEY"

Example response:

{
  "data": [
    { 
      "id": 11, 
      "name": "virtualcard.purchasetemplate.created" 
    },
    {
      "id": 7,
      "name": "virtualcard.clearings"
    },
    {
      "id": 6,
      "name": "virtualcard.realtime.auths"
    },
    {
      "id": 5,
      "name": "ach.status"
    },
    {
      "id": 4,
      "name": "onboarding.company.status"
    },
    {
      "id": 3,
      "name": "virtualcard.deleted"
    },
    {
      "id": 2,
      "name": "virtualcard.created"
    },
    {
      "id": 1,
      "name": "all"
    }
  ]
}

VCN Created Event Type

When a VCN transaction is created, that event can be tracked using webhooks.

Example virtualcard.created webhook payload: 

{
  "data": {
    "date": "2017-08-21T16:34:26.330Z",
    "event-id": 101,
    "payload": {
      "id": 123,
      "available_balance": 123445,
      "currency": "USD",
      "per_transaction_max": 123445,
      "per_transaction_min": 0,
      "rcn_id": 123456,
      "rcn_alias": "Test Account 1",
      "recurring": null,
      "status": "Approved",
      "transactions_max": 1,
      "total_card_amount": 123445,
      "valid_starting_on": "2017-08-27",
      "valid_ending_on": "2017-08-29"
    },
    "previous": null,
    "type": "virtualcard.created"
  }
}

VCN Realtime Authorization Event Type

When a VCN transaction is authorized, that event can be tracked using webhooks.

Sample response for the "virtualcard.realtime.iccp.all" event type:

{
    "data": {
      "date": "2020-10-22T22:09:20.656Z",
      "event-id": 83471,
      "payload": {
         "advice_reason_code": null,
         "approval_code": "222222",
         "banknet_reference_number": "HACZRV",
         "billing_amount": 100,
         "billing_currency": "USD",
         "card_holder_transaction_type_code": "00",
         "card_number": "****************4321",
         "company_id": 340122,
         "financial_network_code": "MCF",
         "issuer_response": "Approved",
         "mcc": "4000",
         "mcc_description": "Description of the MCC",
         "merchant_amount": 100,
         "merchant_city": "Malibu",
         "merchant_currency": "USD",
         "merchant_id": "123456789123456",
         "merchant_name": "Sample Merchant",
         "merchant_state_or_country_code": "CA ",
         "message_type_indicator": "Reversal Request",
         "pos_transaction_status": "0",
         "purchase_request_company_guid": "SENTTYD123D3B12345696798CAB57A34F1",
         "purchase_request_issuer_guid": "KENTTY20E04C1234ADC1AE810AB5BC12345",  
         "rcn_alias": "SAMPLE ALIAS",
         "replacement_amounts.billing_amount": null,
         "replacement_amounts.settlement_amount": null,
         "replacement_amounts.transaction_amount": null,
         "settlement_date": "1022",
         "system_trace_audit_number": "123456",
         "trace_id": "MCFL4RSBL12345 ",
         "transaction_date_time": "2020-10-22T21:43:08.000Z",
         "vcn_id": 64780133,
         "vcn_response": "Valid"
      },
      "type": null
   }
}

VCN Clearings Event Type

When a VCN transaction is cleared, that event can be tracked using webhooks.

Clearing information appears in the clearings key of virtual card responses. Clearings appear when transactions are settled, generally several days after a transaction is authorized.

Billing amount in the clearing object is the amount in your card’s billing currency of the transaction. Settlement amount in the clearing object is the amount in your card’s billing currency of the transaction plus any fees assessed on top of the transaction (e.g. a foreign transcation fee). For USD transactions, the merchant amount and billing amount should be the same.

The settlement date is the same as the transaction date and they both reflect the date as to which MasterCard processes the record from clearing.

Sample response for the "virtualcard.clearings" event type:

{
    "mcc": "5734",
    "rcn_id": 7777,
    "vcn_id": 41155444,
    "rcn_alias": "SAMPLE COMPANY ALIAS",
    "card_number": "556123######1500",
    "merchant_id": "311136000111341",
    "acquirer_ica": "1184",
    "approval_code": "044095",
    "clearing_type": "Debit",
    "exchange_rate": "1.000000",
    "merchant_name": "SAMPLE MERCHANT ONLINE",
    "billing_amount": 2500,
    "mcc_description": "COMPUTER SOFTWARE STORES",
    "merchant_amount": 2500,
    "settlement_date": "2021-02-22T00:00:00.000Z",
    "billing_currency": "USD",
    "merchant_currency": "USD",
    "authorization_date": "2021-02-21T00:00:00.000Z",
    "acquirer_reference_data": "12222333S000GA44X",
    "banknet_reference_number": "MCBK12RR10221",
    "mastercard_financial_transaction_id": "000009654923137"
 }

Webhooks object consist of a url to which to post events occuring on the api.

Note: Webhooks only support one callback URL per event type. Maximum of one callback URL can be configured per event type.

Example Webhooks object:

{
    "id": "101",
    "event_type_ids": [1],
    "secret": "qwertyuipasdfghjklzxcvbnm1234567890",
    "status": "active",
    "callback_url": "https://www.somewhere.com/svb-webhooks",
    "type": "webhook",
    "url": "/v1/webhooks/101"
}

Request:

POST /v1/webhooks

Parameters:

Response:

200 OK The new webhook resource.

Example request:

curl "https://api.svb.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
        "data": {
          "callback_url": "https://www.somewhere.com/svb-webhooks",
          "event_type_ids": [1],
          "secret": "qwertyuipasdfghjklzxcvbnm1234567890",
          "status": "active"
        }
      }'

Example response:

{
  "data": {
    "id": "123",
    "callback_url": "https://www.somewhere.com/svb-webhooks",
    "event_type_ids": [1],
    "secret": "qwertyuipasdfghjklzxcvbnm1234567890",
    "status": "active",
    "type": "webhook",
    "url": "/v1/webhooks/123"
  }
}

For security reasons the hmac secret field is only returned on create.

Request:

GET /v1/webhooks/:id

Response:

200 OK The webhook resource.

Example request:

curl "https://api.svb.com/v1/webhooks/123" \
    -H "Authorization: Bearer YOUR_API_KEY"

Example response:

{
  "data": {
    "id": "123",
    "callback_url": "https://www.somewhere.com/svb-webhooks",
    "event_type_ids": [1],
    "secret": null,
    "status": "active",
    "type": "webhook",
    "url": "/v1/webhooks/123"
  }
}

Request:

PATCH /v1/webhooks/:id

Parameters:

Response:

200 OK The updated webhook resource.

Example request:

curl "https://api.svb.com/v1/webhooks/123" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -X PATCH \
    -d '{
          "data": {
            "status": "inactive"
          }
        }'

Example response:

{
  "data": {
    "id": "123",
    "callback_url": "https://www.somewhere.com/svb-webhooks",
    "event_type_ids": [1],
    "secret": null,
    "status": "inactive",
    "type": "webhook",
    "url": "/v1/webhooks/123"
  }
}

Request:

DELETE /v1/webhooks/:id

Response:

204 No Content

Example request:

curl "https://api.svb.com/v1/webhooks/123" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -X DELETE

Request:

GET /v1/webhooks

Response:

200 OK List of webhook resources.

Example request:

curl "https://api.svb.com/v1/webhooks" \
    -H "Authorization: Bearer YOUR_API_KEY"

Example response:

{
  "data": [
    {
      "id": 123,
      "type": "webhooks",
      "url": "/v1/webhooks/123"
    },
    {
      "id": 122,
      "type": "webhook",
      "url": "/v1/webhooks/122"
    },
    {
      "id": 121,
      "type": "webhook",
      "url": "/v1/webhooks/121"
    }
  ],
  "links": {
    "first": "/v1/webhooks",
    "next": null
  }
}

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 /v1/webhooks/:id/test

Response:

200 OK Test webhook resource response.

Example request:

curl "https://api.svb.com/v1/webhook/123/test" \
    -H "Authorization: Bearer YOUR_API_KEY"

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

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: