Understand provider messaging and webhooks

Provider messaging API

The Payments Out Service provider messaging API /api-provider-v1/ can:

• send details of updates
• respond to debtor and creditor queries
• delete requests from consumers of Payments Out Service

This is done via a message to the consuming application using the subscription ID specified in the message.

The electronic payments provider uses the provider messaging API after processing a message from the consuming application.

All the endpoints in the provider 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 consuming application. This is sent as a webhook to an endpoint configured in Payments Out Service for the consumer.

Operations available are:

• POST debtoraccountputs – This informs the consuming application that a bank account has been created with the payment provider.
• POST debtoraccountlistqueryresponses – This returns bank account details to the consuming application.
• POST debtoraccountdeletes – This returns the status of a bank account delete request to the consuming application.
• POST creditorputs – This informs the consuming application that a vendor has been created with the payment provider.
• POST creditorlistqueryresponses – This returns vendor details to the consuming application.
• POST creditordeletes – This returns the status of a vendor delete request to the consuming application.

---

Provider webhook notification API

For a Payments Out Service consuming application to send messages, the payments provider must implement the /notifications endpoint as defined in Provider Webhook Notifications API reference.

Notifications are sent to providers when events occur on Payments Out Service (or Provider API) that require the provider’s attention. For example, when the subscription is created, a notification is sent to the provider to initiate onboarding.

Notifications will always contain “type”. This defines what the purpose of the notification is; and a resource with nested information about the resource involved in the event.

The notifications you must support are as follows:

Subscription Created

This is triggered when a customer chooses to create a subscription with you as a payment provider.

{
  type: ResourceCreated,
  resource: {
    id: Payments Out Subscription Guid,
    type: 'subscriptions',
    url: url to use to get the subscription using the payments out provider api
  }
}

As you process the subscription you should send status updates using the PATCH subscription endpoint.

Creditor created or updated

This is triggered when a vendor is created or updated by a customer.

{
  type: MsgPutCreditor,
  message: {
    data: {  ...  }
  }
}

Creditor Query

This is triggered when a customer requests the creditor details held by you as a provider.

{
  type: MsgPostCreditorListQueries,
  message: {
    data: {  ...  }
  }
}

Debtor created or updated

This is triggered when a bank account is created or updated by a customer.

{
  type: MsgPutDebtorAccount,
  message: {
    data: {  ...  }
  }
}

Debtor Query

This is triggered when a customer requests the bank account details held by you as a provider.

{
  type: MsgPostDebtorAccountListQueries,
  message: {
    data: {  ...  }
  }
}

Creation of a batch of payments

This is triggered when a customer posts a batch of payments against a subscription owned by you as the payment provider.

{
  type: ResourceCreated,
  resource: {
    id: Payments Out Batch Guid,
    type: 'batchpayments',
    url: url to use to get the batch of payments using the payments out provider api
  }
}

As you process the payments you should send status updates using the PATCH batch endpoint.

Response

Your solution should respond with a 200.

###Retry Policy

We do a retry on the delivery of notifications using an exponential back-off algorithm, this retries requests increasing the waiting time between retries. The time between retries doubles each time for a total of 17 attempts. This manifests in 10 attempts on the first day but 31 days will elapse before the final attempt is made.

Securing this endpoint

With the /notification endpoint we can add a custom headerName and headerValue to the request specified by you. This helps ensure you can be certain that this request originates from Sage.

Within this request you will also be passed a Sage ID token under the authorisation header which can be verified using the following endpoint:

Sandbox https://id-shadow.sage.com/.well-known/jwks.json Production https://id.sage.com/.well-known/jwks.json

The following is an example of the request headers which would be sent along with this request:

  headers: {
    accept: 'application/json',
    Authorization: 'Bearer **Sage ID Token**',
    'content-type': 'application/json; charset=utf-8',
    YourKeyHeader: 'YourKeyValue'
  }