Skip to content
Developerhome
Product homepage
Payments Out Service

3. Integrate

  Less than to read

Your Postman environment and collections

To see the Provider API in action you can use Postman. Postman is a multi-platform REST client with an intuitive GUI for:

  • Configuring HTTP requests
  • Designing JSON payloads
  • Viewing HTTP responses

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

If you need help with Postman, they provide help and learning resources in the Postman Learning Center.

Step 1: Get Postman

Visit the Postman website to download and install Postman.

Step 2: Get the Postman collections

Postman supports collections. These are pre-packaged bundles of API requests. We provide a Postman collection for common tasks to help you when developing with the Provider API.

To assist in the development and testing of your integration, we have provided 2 Postman collections.

Or, use the link below to create a fork of the Provider API collection directly to your Postman workspace.

Run in Postman

Step 3: Import the Postman collection

  1. Unzip the JSON format files from the downloaded ZIP archive.
  2. Open Postman.
  3. From the main menu, select File > Import.
  4. Drag and drop the JSON files into Postman.

Step 4: Import the environment JSON received during registration

The environment JSON we provided in registration contains the details of the sandbox test environment. This includes your client ID and secret. The environment JSON must be imported into Postman to enable the collections to function.

  1. Unzip the JSON format file from the downloaded ZIP archive.
  2. Open Postman.
  3. Select the manage environments option at the top right of the Postman UI.
  4. From the manage environments view, select Import.
  5. Select the choose files option and locate the environment JSON file.
  6. 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 Postman collections. Find out how to download the Postman 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?