Faster Payouts Webhooks (1.0)

API - Webhooks Notifications

Introduction

An event is an occurrence of something that could be of interest to the biller or client within Faster Payouts. When this happens, Faster Payouts sends an Event object to the client using a Webhook. Clients can subscribe to the events of their choice. The Webhook invocation involves authenticating to the client system and making a POST request with the Event object to the URL specified by the client. An event posting is considered to be successful if it gets an HTTP Response code of 200. In case Faster Payouts does not receive a successful response for an event posting, the event will be re-posted every hour for a maximum of 3 days. In case of re-posting of an event, the event id will be the same as in the original posting.

Authentication

Faster Payouts Event posting supports different authentication schemes.

API Keys over Custom HTTP Headers

In this authentication scheme, Faster Payouts would send API Keys, in the form of HTTP headers, as part of the webhook. These API Keys must be configured in Faster Payouts by the client. A client can specify upto a maximum of 5 API keys to be sent in a webhook. The client can check for the authenticity of the webhook by comparing the API keys and values received in the webhook with the ones configured in Faster Payouts.

  Example :

  test_header1:value1
  test_header2:value2
  test_header3:value3
  test_header4:value4
  test_header5:value5

HTTP Basic Authentication

With Basic Authentication, Faster Payouts sends a Base64-encoded string that contains the user name and password for the client in the Authorization header of the HTTP request. The client must configure the username and password for the basic authentication in Faster Payouts. The client can check for the authenticity of the webhook by verifying the username and password received in the webhook with the ones configured in Faster Payouts. Please note that Base64 is not a form of encryption and is similar to sending the user name and password in clear text.

  Example :

  Below  dXNlcm5hbWU6cGFzc3dvcmQ=   refers to Base64 encoded string of the provided username and password ( username:password )
  (  : ( colon ) is appended in-between username and password before it is being encoded)
  Authorization:Basic dXNlcm5hbWU6cGFzc3dvcmQ=

OAuth 2.0

Faster Payouts supports Open Authorization Protocol 2.0 with Auth scheme as “Bearer”. The client/biller needs to run an authorization server at its end. The client needs to configure the client id, the client secret, the token endpoint (URL) and the Auth scope in Faster Payouts. The Grant Type to be used is "client_credentials". Faster Payouts sends the token read from the token endpoint in the Authorization header of the webhook.

  Example :

  Below 4484e52dc4744374aced826a4543cd28948816ff   refers to the access token issued by Autherization server.
  Authorization:Bearer 4484e52dc4744374aced826a4543cd28948816ff

Request Headers

Every API call should include the following request headers to define the context in which the API is invoked.

Request Header Parameters:
client_key
required
string <= 10 characters ^[a-zA-Z0-9]{1,10}$

The unique identifier assigned by the Faster Payouts to the client.
Example:CLIAAADDD0910

product
required
string <= 100 characters ^[a-zA-Z0-9_.& -]{1,100}$

The product identifier corresponding to the API.
Possible values:payouts

payment_channel
required
string <= 100 characters ^[a-zA-Z0-9_.& -]{1,100}$

The FI channel vide which the API is invoked.
Possible values:online

idempotent_request_key
required
string <= 50 characters ^[a-zA-Z0-9_=-]{1,50}$

The unique token that clients can generate and maintain in order to identify an API request. This is used to identify duplicate requests and retrials.
Example:6bc5f0f49ee2412a93b0596d6a3c4eca

timestamp
required
string <ISO 8601 DateTime with offset YYYY-MM-DDThh:mm:ss.sss+/-hh:mm>

The UTC datetime when the API is invoked, in the ISO 8601 format
Example:2020-09-18T17:31:34.000-05:30

Webhooks

Payout Status Update Event

This Webhook event is sent to a party to update the payout status.

Request Body schema: application/json
id
string [ 0 .. 20 ] characters [a-zA-Z0-9]+

Webhook id

data
object
event_type
string [ 0 .. 50 ] characters [0-9a-zA-Z._-]{0,50}
Value: "fasterpayouts.payout.status_updated"

Responses

200

Success

400

Bad Request

500

System Error.

502

Server Error.

post/<client-url>
https://<client-domain>/<client-url>

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
}