3. Integrate

A Bruno collection is available to illustrate the Payments Out Service Provider API methods and workflow.

Setting up Bruno

Step 1: Get Bruno

Visit the Bruno website to Download and install Bruno.

Step 2: Get the Bruno Collection

Bruno supports collections which are a pre-packaged bundle of API requests. To assist in the development and testing of your integration, we have provided a Bruno collection to cover the Payments Out Service flows. For more information about the collections, including use cases and flows, go to the provider flows section.

Payments Out Provider API collection

Step 3: Import the Bruno Collection and Environment

1. Unzip the JSON format files from the downloaded ZIP archive.
2. Open Bruno
3. From the main menu, select File > Import
4. Drag and drop the JSON files into Bruno
5. Ensure the new environment is selected once imported

---

Provider flows

For a successful integration with Payments Out Service, it is important to understand the data flows.

There are 5 flows for providers connecting to Payments Out Service:

• Authorisation
• Creating subscription
• Debtor accounts
• Creditors
• Making payments

Authorisation

To make any calls to the Payments Out Provider API Service you need a Sage ID Token:

1. The Provider calls the POST /authService url.
2. A Sage ID token is returned, this token is used in the authorisation header on future requests.

Use the token until it expires, do not create a new token for each new request.

Creating subscription

When Payments Out Service calls the /subscription endpoint, the provider should create a subscription and provide the Payments Out Service with a link to UI to enable the consumer to onboard:

1. Product initiates a subscription request, calling into Payments Out Service.
2. Payments Out Service calls the POST /subscription endpoint on the Provider API, expecting a 201 response.
3. The provider calls the GET /subscriptions endpoint on the Provider API to retrieve the subscription request details.
4. The provider calls the PATCH /subscriptions endpoint on the Provider API with an authorisation link.
5. Payments Out sends the authorisation link to the consumer.
6. The provider generates UI for authentication and authicates the user.
7. The provider calls PATCH /subscriptions on the ProviderAPI, passing the subscription status.
8. Payments Out updates the consumer with the updated subscription status.

sequenceDiagram
participant Consumer as Consumer
participant C-API as Consumer API
participant P-API as Provider API
participant Provider as Provider
box Payments Out Service
participant C-API
participant P-API
end

Consumer ->> C-API: POST Subscription
C-API ->> Consumer: 201
C-API ->> Provider: POST Subscription
Provider ->> P-API: 201
P-API ->> Consumer: 201
Note right of Provider: Payment provider needs to implement <br/> the Webhook notifications API
Provider ->> P-API: GET Subscription
P-API ->> Provider: 200
Provider ->> P-API: PATCH Subscription status <br/> AwaitingAuthorisation + AuthLink
P-API ->> Provider: 204
P-API ->> Consumer: Webhook Subscription status <br/> AwaitingAuthorisation + AuthLink
Note left of Consumer: Consuming application needs to implement <br/> the Webhook notifications API
Consumer ->> C-API: GET Subscription
C-API ->> Consumer: 200
Consumer ->> Provider: Follow auth link
Provider ->> Provider: Authentication
Provider ->> P-API: PATCH Subscription status <br/> Authorised
P-API ->> Provider: 204
P-API ->> Consumer: Webhook Subscription status <br/> Authorised
Consumer ->> C-API: GET Subscription
C-API ->> Consumer: 200

Debtor accounts (bank accounts)

When Payments Out Service calls the /notifications endpoint, the provider should create a debtor account and provide the Payments Out Service with a link to UI to enable the consumer to authorise the debtor account:

1. Product initiates a debtor account request, calling into Payments Out Service.
2. Payments Out Service calls the POST /notifications endpoint on the Provider, expecting a 201 response.
3. The provider calls the PATCH /debtoraccountputs on the ProviderAPI endpoint with an authorisation link.
4. Payments Out sends the authorisation link to the consumer.
5. The provider generates UI for authentication and authicates the debtor account.
6. The provider calls PATCH /debtoraccountputs on the ProviderAPI, passing the debtor account status.
7. Payments Out updates the consumer with the updated debtor account status.

sequenceDiagram
participant Consumer as Consumer
participant C-API as Consumer API
participant P-API as Provider API
participant Provider as Provider
box Payments Out Service
participant C-API
participant P-API
end

Consumer ->> C-API: POST DebtorAccount
C-API ->> Consumer: 201
C-API ->> Provider: POST DebtorAccount
Provider ->> P-API: 201
P-API ->> Consumer: 201
Note right of Provider: Payment provider needs to implement <br/> the Webhook notifications API
Provider ->> P-API: GET DebtorAccount
P-API ->> Provider: 200
Provider ->> P-API: PATCH DebtorAccount status <br/> AwaitingAuthorisation + AuthLink
P-API ->> Provider: 204
P-API ->> Consumer: Webhook DebtorAccount status <br/> AwaitingAuthorisation + AuthLink
Note left of Consumer: Consuming application needs to implement <br/> the Webhook notifications API
Consumer ->> C-API: GET DebtorAccount
C-API ->> Consumer: 200
Consumer ->> Provider: Follow auth link
Provider ->> Provider: Authentication
Provider ->> P-API: PATCH DebtorAccount status <br/> Authorised
P-API ->> Provider: 204
P-API ->> Consumer: Webhook DebtorAccount status <br/> Authorised
Consumer ->> C-API: GET DebtorAccount
C-API ->> Consumer: 200

Create creditors (entities being paid)

An optional step of adding and authenticating creditors is available. When Payments Out Service calls the /notifications endpoint, the provider can create a creditor account and can provide the Payments Out Service with a link to UI to enable the consumer to authorise the creditor account:

1. Product initiates a creditor account request, calling into Payments Out Service.
2. Payments Out Service calls the POST /notifications endpoint on the Provider, expecting a 201 response.

Optional authorisation:

1. The provider calls the PATCH /creditorputs on the ProviderAPI endpoint with an authorisation link.
2. Payments Out sends the authorisation link to the consumer.
3. The provider generates UI for authentication and authicates the creditor account.
4. The provider calls PATCH /creditorputs on the ProviderAPI, passing the debtor account status.
5. Payments Out updates the consumer with the updated creditor account status.

sequenceDiagram
participant Consumer as Consumer
participant C-API as Consumer API
participant P-API as Provider API
participant Provider as Provider
box Payments Out Service
participant C-API
participant P-API
end

opt
Consumer ->> C-API: POST Creditor
C-API ->> Consumer: 201
C-API ->> Provider: POST Creditor
Provider ->> P-API: 201
P-API ->> Consumer: 201
Note right of Provider: Payment provider needs to implement <br/> the Webhook notifications API
Provider ->> P-API: GET Creditor
P-API ->> Provider: 200
opt
Provider ->> P-API: PATCH Creditor status <br/> AwaitingAuthorisation + AuthLink
P-API ->> Provider: 204
P-API ->> Consumer: Webhook Creditor status <br/> AwaitingAuthorisation + AuthLink
Note left of Consumer: Consuming application needs to implement <br/> the Webhook notifications API
Consumer ->> C-API: GET Creditor
C-API ->> Consumer: 200
Consumer ->> Provider: Follow auth link
Provider ->> Provider: Authentication
Provider ->> P-API: PATCH Creditor status <br/> Authorised
P-API ->> Provider: 204
P-API ->> Consumer: Webhook Creditor status <br/> Authorised
Consumer ->> C-API: GET Creditor
C-API ->> Consumer: 200
end
end

Batch payments

When a customer makes a payment in the product:

1. Product initiates a batch payment request, calling into Payments Out Service.
2. Payments Out Service calls the POST /batchpayments endpoint on the provider, expecting a 201 response.
3. The provider calls the GET /batchpayments endpoint on the Provider API, to retrieve the Organisation ID for the batch which is required to PATCH batch status updates.
4. When the provider starts to process the payments, the provider calls the PATCH /batchpayments endpoint on the Provider API, updating the status of the batch payment to Processing.
5. The provider loops through each payment.
6. Once all payments have been made, the provider calls the PATCH /batchpayments endpoint on the Provider API, updating the status of the batch payment to ProcessingComplete.
7. Payments Out Service updates the consumer with the updated status on the batch payment.

sequenceDiagram
participant Consumer as Consumer
participant C-API as Consumer API
participant P-API as Provider API
participant Provider as Provider
box Payments Out Service
participant C-API
participant P-API
end

Consumer ->> C-API: POST Batch of payments
C-API ->> Consumer: 201
C-API ->> Provider: POST Batch of payments
Provider ->> P-API: 201
P-API ->> Consumer: 201
Note right of Provider: Payment provider needs to implement <br/> the Webhook notifications API
Provider ->> P-API: GET Batch of payments
P-API ->> Provider: 200
loop Process payments in batch
Provider ->> P-API: PATCH Payment/batch status <br/> Processing
P-API ->> Provider: 204
P-API ->> Consumer: Webhook Payment/batch status <br/> Processing
Note left of Consumer: Consuming application needs to implement <br/> the Webhook notifications API
Consumer ->> C-API: GET Batch of payments
C-API ->> Consumer: 200
Provider ->> Provider: Make payment
Provider ->> P-API: PATCH Payment/batch status <br/> ProcessingComplete
P-API ->> Provider: 204
P-API ->> Consumer: Webhook Payment/batch status <br/> ProcessingComplete
Consumer ->> C-API: GET Batch of payments
C-API ->> Consumer: 200
end

---

Implement a connector API

To process the required webhooks provider flows, you need to implement a connector API.

Endpoints

This API is exposed through these endpoints:

• /api-provider-v1/subscriptions/ – for getting and patching a subscription
• /api-provider-msg-v1/creditorputs – for updating the status of a creditor
• /api-provider-msg-v1/debtoraccountputs – for updating the status of a debtor
• /api-provider-v1/batchpayments/ – for getting and patching a batch payment

Connector API specification

The full specification, including response codes and payloads, is in the Swagger file. Go to the provider messaging API to find out more.

Building this API against the provided endpoints allows you to test the flows in the sandbox environment using the Bruno collections.

Notifications

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 consumer creates a debtor or creditor account.

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 message data.

Debtor account put

This is triggered when a customer starts the Debtor Accounts flow to link a bank account in Payments Out Service.

This notification prepares the provider for a UI redirect to authorize the debtor account.

• data.debtorAccountId: The identifier of the debtor.

{
    "type": "MsgPostDebtorAccountPuts",
    "message": {
        "data": {
          "debtorAccountId": "DebtorID",
          "subscriptionId": "36aed119-675f-4507-9da3-06a5914d95ee",
          "messageId": "",
          "debtorAgent": {
            "schemeName": "",
            "identification": ""
          },
          "debtorAccount": {
            "schemeName": "",
            "identification": "",
            "name": "",
            "secondaryIdentification": ""
          },
          "additionalData": {}
        }
    }
}

Creditor put

This is triggered in the Creditors (Entities being paid) flow to link a creditor in the Payments Out Service.

This optional flow notification prepares the provider to link the creditor as well as preparing the provider to for UI redirect to authorize the creditor account.

• data.creditorId: The identifier of the creditor.

{
    "type": "MsgPostCreditorPuts",
      "message": {
        "data": {
          "creditorId": "CreditorID",
          "subscriptionId": "36aed119-675f-4507-9da3-06a5914d95ee",
          "messageId": "",
          "creditor": {
            "name": "",
            "postalAddress": {
              "addressLine1": "",
              "addressLine2": "",
              "addressLine3": "",
              "addressLine4": "",
              "postalCode": "",
              "countrySubdivision": "",
              "countryCode": "",
              "country": ""
            },
            "debtorLocalInstrument": "",
            "contactEmail": "",
            "phoneNumber": ""
          },
          "creditorAgent": {
            "schemeName": "",
            "identification": ""
          },
          "creditorAccount": {
            "schemeName": "",
            "identification": "",
            "name": "",
            "secondaryIdentification": ""
          },
          "additionalData": {}
        }
    }
}

---

Using Provider API

Provider API is API used for retrieving data and updating the status of subscriptions, debtors, creditors and payments to the Payments Out Service.

Provider API specification

The full specification, including response codes and payloads, is in the Swagger file. Go to the API Reference section for Provider API.

---

Engineering support

Your team will be able to communicate with our engineers for support. The channels for contacting our engineers was agreed in Stage 2: Get set up.

It is important that you get in touch with us if you have any issues during development such as:

• Issues accessing sandbox
• Documentation issues
• Updates to endpoints or provider names
• Delays to agreed go-live dates
• Knowledge support for provider flows and API specifications

---

Next steps

Find out what you need to do for your integration to go live after you’ve completed your internal testing.

---

Was this helpful?

Yes

No

Submit feedback