Webhooks

Introduction

Webhooks are setup in the Console. Currently, 'payment sent' and 'payment failed' are available. These have identical payloads containing a full PaymentSession. The key difference is the status (see below).

Payment Sent

Triggered when a PaymentSession is successfully authorised via the Payer's account.

This does not signify that has been received successfully by the Payee. Please check the status for more details.

Example 'sent' webhook payload

-x- CODE language-json -x- {
 "amount": 1,
 "created_at": "2019-10-31 16:45:34 UTC",
 "currency": "GBP",
 "end_to_end_id": null,
 "error_url": "https://example.com/error",
 "id": "a6941fd1-f5cb-4948-814d-df03540149fb",
 "line_items": [
   {
     "amount_cents": 1,
     "currency": "GBP",
     "description": null,
     "name": "Candle",
     "quantity": 1
   }
 ],
 "live": true,
 "payee": {
   "account_number": "12345678",
   "name": "Gerard Wiley",
   "sort_code": "123456"
 },
 "reference": "Illuminate",
 "state": "awaiting_payer",
 "success_url": "https://example.com/success",
 "url": "https://banked.me/pay/a6941fd1-f5cb-4948-814d-df03540149fb"
}

Payment Failed

Triggered when a PaymentSession is not authorised via the Payer's account.

Example 'failed' webhook payload

-x- CODE language-json -x- {
 "amount": 1,
 "created_at": "2019-10-31 16:45:34 UTC",
 "currency": "GBP",
 "end_to_end_id": null,
 "error_url": "https://example.com/error",
 "id": "a6941fd1-f5cb-4948-814d-df03540149fb",
 "line_items": [
   {
     "amount_cents": 1,
     "currency": "GBP",
     "description": null,
     "name": "Candle",
     "quantity": 1
   }
 ],
 "live": true,
 "payee": {
   "account_number": "12345678",
   "name": "Gerard Wiley",
   "sort_code": "123456"
 },
 "reference": "Illuminate",
 "state": "failed",
 "success_url": "https://example.com/success",
 "url": "https://banked.me/pay/a6941fd1-f5cb-4948-814d-df03540149fb"
}

Signature

Each request we POST to your webhook will contain a digital signature, that allows you to verify that the request and payload came from Banked.

When you create the webhook in the developer console, you will need to provide a signature key. Banked will use this to digitally sign the payload of the request, and then provide that signature in a Banked-Signature HTTP header.

To verify the signature, you can follow these steps:

1. Split the header using a period as the separator. The leading value will be a unix timestamp, and the second value is the signature.
2. Concatenate the timestamp, a single period character and the payload of the request to generate the text to be signed.
i.e. text to sign = timestamp + "." + raw request payload
3. Sign the text using HMAC-sha256, and your signature key that you set up earlier in the console.
4. Verify the generated value matches the signature extracted from step one.
5. You can also optionally choose to validate that the age of the timestamp is within an acceptable range.