Payment Hub API - Webhooks (1.0)

Contact: support@billerpayments.com License: © Alacriti Inc

Introduction

An event is an occurrence of something that could be of interest to the client within the Payment Hub API. Payments Hub posts the event 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 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 the case if it does not receive a successful response for an event posting, the event will repeated at the agreed frequency beteen the client system and the Hub.

Request Headers

Every webhook event is invoked using the following request headers to define the context in which the event is invoked.

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

The unique identifier assigned by the Payment Hub to the client.
Example:CLIAAADDD0910

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

The product identifier corresponding to the API.
Allowed values:A2A, payouts, retail_transfers, business_transfers, account_opening, collections, cosmos

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

The FI channel vide which the API is invoked.
Allowed values:retail_banking, commercial_banking, bank_bos, atm, kiosk, pos, mobile_banking, csm, online, hosted_portal

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

This is the internal channel through which the API is invoked.
Example:web_portal, agent

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

Identifies the requestor type for the API request.
Possible values:party, client_agent, system, external_agent

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

The identifier for the requestor of the API, in the client system. Either the client_requestor_reference or the requestor must be available in every API request for audit purposes.

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

The identifier for the requestor of the API, in the Payment Hub. Either the client_requestor_reference or the requestor must be available in every API request for audit purposes.

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

To be used if there is a need to provide additional contextual information. For future use.

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

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

The unique reference that can be used for tracing and debugging an API call.
Example:trace49ee2412a93b0596d6a3c4eca

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

X-PAAS-Headers
string

For additional context information such as end user IP address, session information and so on. The content is a list of key-value pairs separated by semicolon (;) where key and value are separated by equals sign(=).
Example:session=SADKAS2131312;ip_address=10.112.25.45

Initiate Customer Credit Transfer

Account Debited

The Debtor or the account owner receives a Notice of Debit Webhook after specific amount given in the instruction is debited from the Debtor's account.
Event name initiate_customer_credit_transfer.account_debited

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:camt.054.001.08>
<Document>

Account Debit Reversed

The 'Notice of Credit' message is a Webhook event sent by the account servicer to an account owner or to a party authorised by the account owner to receive the message. It is used to inform the account owner, or authorised party, of credit entries reported to the account.
Event name initiate_customer_credit_transfer.account_debit_reversed

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:camt.054.001.08>
<Document>

Credit Settlement Completed

Event to notify thet the credit settlement is complete.
Event name initiate_customer_credit_transfer.accepted_settlement_completed

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:pain.002.001.10>
<Document>

Account Credited Posting Pending.

Event ot notify that the payment instruction is accepted witohout posting.
Event name initiate_customer_credit_transfer.account_credited_posting_pending

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:pain.002.001.10>
<Document>

Payment Acknowledged

Event to notify that the payment has been acknowledged by the end party
Event name initiate_customer_credit_transfer.payment_acknowledged

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:pain.002.001.10>
<Document>

Unable to Apply Payment

Event to notify that the requested payment cannot be applied.
Event name receive_rfi.unable_to_apply_payment

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:camt.026.001.07>
<Document>

Send Unable to Apply RFP

Received Additional RFP Info

Event to notify that additional RFP info has received
Event name send_rfi.received_additional_rfp_info

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:camt.028.001.09>
<Document>

Send RROF

Send RROF Accepted

Event to notify that the request to return of funds accepted
Event name send_rrof.accepted

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:camt.056.001.08>
<Document>

Send RROF Rejected

Event to notify that request to return of funds rejected.
Event name send_rrof.rejected

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:camt.031.001.06>
<Document>

Receive RFP

RFP Cancelled

Event to notify that RFP cancelled
Event namereceive_rfp.cancelled

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:camt.055.001.08>
<Document>

RFP Received

Event to notify that RFP received
Event name receive_rfp.received

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:pain.013.001.07>
<Document>

Receive Customer Credit Transfer

Account Credited

Event to notify that the account has been credited.
Event name receive_payment.account_credited

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:camt.054.001.08>
<Document>

Account Credit Reversed

Event to notify that the account credit is reversed.
Event Name receive_payment.account_credit_reversed

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:camt.054.001.08>
<Document>

System Reversal

Event to notify that the payment has been reversed by the system.
Event Name receive_payment.system_reversal

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:pacs_002.001.10>
<Document>

Account Credited Posting Pending

Event to notify that the payment is accepted without posting.
Event name receive_payment.account_credited_posting_pending

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:pacs_002.001.10>
<Document>

Payment Settlement Completed

Event to notify that the payment is accepted and settlement completed.
Event name receive_payment.accepted_settlement_completed

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:pacs_002.001.10>
<Document>

Send Unable to Apply Payment

Received Additional Payment Info

Event to notify that additional payment info has received
Event name send_rfi.received_additional_payment_info

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:camt.028.001.09>
<Document>

Receive Unable to Apply RFP

Received Unable to Apply RFP

Event to notify that the requested RFP cannot be applied.
Event name receive_rfi.unable_to_apply_rfp

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:camt.026.001.07>
<Document>

Send RFP

RFP Accepted

Event to notify that the RFP request has been accepted.
Event name send_rfp.accepted

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:pain.014.001.07>
<Document>

RFP Rejected

Event to notify that RFP request is rejected
Event namesend_rfp.rejected

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:pain.014.001.07>
<Document>

Receive RROF

RROF Received

Event to notify that the requested RROF has been assigned to the creditor.
Event name receive_rrof.assigned_to_creditor

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:camt.030.001.05>
<Document>

Remittance Advice

Reveived Remittance Advice

Event to notify that the remittance advice has been received.
Event name receive_remittance_advice.received

Request Body schema: application/xml
Document
required
object

Request samples

Content type
application/xml
Copy
 Expand all Collapse all
<?xml version="1.0" encoding="UTF-8"?> <Document xmlns=urn:iso:std:iso:20022:tech:xsd:remt.001.001.04>
<Document>