EBPP API Webhooks - Multi Profile Account (1.0.0)

EBPP API - Webhooks Notifications of Multi Profile Account Model

Introduction

An event is an occurrence of something that could be of interest to the biller or client within EBPP. When this happens, EBPP 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 EBPP 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

EBPP Event posting supports different authentication schemes.

API Keys over Custom HTTP Headers

In this authentication scheme, EBPP would send API Keys, in the form of HTTP headers, as part of the webhook. These API Keys must be configured in EBPP 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 EBPP.

  Example :

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

HTTP Basic Authentication

With Basic Authentication, EBPP 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 EBPP. 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 EBPP. 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

EBPP 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 EBPP. The Grant Type to be used is "client_credentials". EBPP 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

Event

This section outlines the API required to exchange and manage event information being posted to the client vide Webhooks. The Event object contains the type of event that occurred and the domain object that pertains to the event. Possible events objects are PaymentEvent, PaymentSetupEvent, RefundEvent.

Listed below are the possible event types and the relevant domain object that would be sent as part of the Event object.

Event Type Description Data
payment.created Triggered when a payment is scheduled or
an instance of a PaymentSetup is created.		 Payment
payment.processing Triggered when a payment processing is initiated. Payment
payment.processed Triggered when a payment processing is completed. This does not mean the funds are settled. The funds will be settled at a later time depending upon the payment method. Payment
payment.updated Triggered when a pending payment is updated. Payment
payment.cancelled Triggered when a pending payment is cancelled or an instance of a PaymentSetup is rejected due to limit violations. Payment
payment.declined Triggered when a card payment is declined by the card issuer. Payment
payment.returned Triggered when a bank payment is returned by the ACH gateway. Payment
payment.rejected Triggered when a payment or an instance of a PaymentSetup is rejected due to business rule voilations. Payment
payment.chargedback Triggered when a chargeback is received on a card. Payment
refund.created Triggered when the refund of a payment is initiated. Refund
refund.processing Triggered when a refund processing is initiated. Refund
payment_setup.created Triggered when a customer enrolls for an Autopay , Recurring or a Payment Plan Setup. PaymentSetup
payment_setup.updated Triggered when a customer edits an Autopay , Recurring or a Payment Plan Setup. PaymentSetup
payment_setup.draft.created Triggered when a new bill amount or due date is applied to a customer account for which the customer has an active payment setup. The new bill amount or due date for a customer account could come in the Account Master File or could be applied using the Payments API. PaymentSetup
payment_setup.draft.skipped Triggered when a zero bill amount is applied to a customer account that has an active payment setup. In this case, the payment instance is not created or is skipped for the payment setup. PaymentSetup
payment_setup.cancelled Triggered when a customer cancels an Autopay , Recurring or a Payment Plan Setup. PaymentSetup

Publish Events

The Publish Event API is used to push notifications from EBPP to it's clients, via webhooks. EBPP sends notifications for a number of events ranging from bill due to payments. The clients who wish to consume these notifications need to specify the URL at which they want the notifications to be posted.

Payment Event

api_version
required
string

The number or reference to the version of the webhooks API.

channel
required
string

The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.

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

The unique identifier assigned by EBPP to the client.

data
required
object
id
required
string <= 50 characters [a-zA-Z0-9-_]{1,50}

The unique identifier assigned by EBPP to the event being posted.

pending_webhooks
required
string [0-9]{1,2}

The number of webhooks notifications that the client failed to process and that EBPP needs to resend for the event type.

source_id
string [a-zA-Z0-9]{1,20}

The unique identifier assigned by EBPP to the source that originated the event. For e.g., The source_id is null or empty if the event is triggered by system. It is the id of the customer, if the source_type is customer and user login id if the source_type is user or external_user.

source_type
required
string
Enum: "customer" "user" "external_user"

The type of source that originated the event.

timestamp
required
string

The UTC timestamp, in ISO8601 format, for the moment when the event is posted to the client.
For e.g., 2019-08-13T09:21:34.359+0000

type
required
string
Enum: "payment.created" "payment.processing" "payment.processed" "payment.updated" "payment.cancelled" "payment.declined" "payment.returned" "payment.rejected" "payment.chargedback"

The type of the event that triggered the webhooks notification.In the event 'payment.created', the prefix 'payment' indicates the Data object in the context and the verb 'created' indicates the operation performed on the object.

Copy
 Expand all Collapse all
{
}

Payment Setup Event

api_version
required
string

The number or reference to the version of the webhooks API.

channel
required
string

The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.

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

The unique identifier assigned by EBPP to the client.

data
required
object
id
required
string <= 50 characters [a-zA-Z0-9-_]{1,50}

The unique identifier assigned by EBPP to the event being posted.

pending_webhooks
required
string [0-9]{1,2}

The number of webhooks notifications that the client failed to process and that EBPP needs to resend for the event type.

source_id
string [a-zA-Z0-9]{1,20}

The unique identifier assigned by EBPP to the source that originated the event. For e.g., The source_id is null or empty if the event is triggered by system. It is the id of the customer, if the source_type is customer and user login id if the source_type is user or external_user.

source_type
required
string
Enum: "customer" "user" "external_user"

The type of source that originated the event.

timestamp
required
string

The UTC timestamp, in ISO8601 format, for the moment when the event is posted to the client.
For e.g., 2019-08-13T09:21:34.359+0000

type
required
string
Enum: "payment_setup.created" "payment_setup.updated" "payment_setup.cancelled" "payment_setup.draft.created" "payment_setup.draft.skipped"

The type of the event that triggered the webhooks notification.In the event 'payment.created', the prefix 'payment' indicates the Data object in the context and the verb 'created' indicates the operation performed on the object.

Copy
 Expand all Collapse all
{
}

Refund Event

api_version
required
string

The number or reference to the version of the webhooks API.

channel
required
string

The channel through which the API is invoked. Please contact support@billerpayments.com to configure channels.

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

The unique identifier assigned by EBPP to the client.

data
required
object
id
required
string <= 50 characters [a-zA-Z0-9-_]{1,50}

The unique identifier assigned by EBPP to the event being posted.

pending_webhooks
required
string [0-9]{1,2}

The number of webhooks notifications that the client failed to process and that EBPP needs to resend for the event type.

source_id
string [a-zA-Z0-9]{1,20}

The unique identifier assigned by EBPP to the source that originated the event. For e.g., The source_id is null or empty if the event is triggered by system. It is the id of the customer, if the source_type is customer and user login id if the source_type is user or external_user.

source_type
required
string
Enum: "customer" "user" "external_user"

The type of source that originated the event.

timestamp
required
string

The UTC timestamp, in ISO8601 format, for the moment when the event is posted to the client.
For e.g., 2019-08-13T09:21:34.359+0000

type
required
string
Enum: "refund.created" "refund.processing"

The type of the event that triggered the webhooks notification.In the event 'payment.created', the prefix 'payment' indicates the Data object in the context and the verb 'created' indicates the operation performed on the object.

Copy
 Expand all Collapse all
{
}