Understand consumer messaging and webhooks

Consumer messaging API

The Payments Out Service consumer messaging API /api/msg-v1/ can create, query or delete debtors and creditors under an electronic payments provider subscription. It does this via a message to the payments provider based on the subscription ID you specify.

All the endpoints in the consumer messaging API are POSTs. They have the endpoint and message body describing the action you want to take. This is a messaging service rather than a direct endpoint, so the POST will return HTTP status code 202, with no response body. The payload is forwarded to the electronic payments provider for processing.

When the electronic payments provider processes the message they respond using the provider messaging API. This is sent as a webhook to an endpoint configured in Payments Out Service for you, as a consumer.

Operations available are:

• POST debtoraccountputs – This creates a bank account (from which outgoing payments will be made) with the payment provider.
• POST debtoraccountlistqueries – This retrieves bank account details from the payment provider.
• POST debtoraccountdeletes – This deletes a bank account held with the payment provider.
• POST creditorputs – This creates a vendor (an entity which will receive money) with the payment provider.
• POST creditorlistqueries – This retrieves vendor details from the payment provider.
• POST creditordeletes – This deletes a vendor held with the payment provider.

Consumer webhook notification API

To receive responses from the electronic payments provider, your application must implement the /notifications endpoint. This is defined in Consumer webhook notifications API reference.

Raise a Payments Out Service ticket that includes your application ID and the URL you want webhooks to be sent to.

When an event occurs (such as a provider updating a batch of payments), you will receive a notification to this URL. This includes the event type and its related data.