Skip to content
Developerhome

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 Provider API methods and workflow.

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

Step 1: Download Postman

Visit the Postman website to download and install Postman.

Step 2: Get the Postman collection

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.

Download the Provider API Postman collection or select “Run in Postman” to create a fork of the 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

You will have received the environment JSON after registering. This has the details of the sandbox environment, and 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.

If you want to learn more about the Provider API, we’ve put together some use cases as a guide. These detail the core processes exposed by the Provider API. Find out more in the provider flows section.


The provider flows

These use cases represent the flow of an onboarding business and paying an invoice through a payment service. To follow the steps you need to import the Provider API Postman collection in Postman. You can download the Postman collection here.

The Postman collections contain API requests outside of the scope of the Provider API. This is so you can complete the onboarding flow. These will not be available in the production environment.

The additional API requests allow you to create:

  • organisations
  • companies
  • contacts
  • invoices

The collection includes the SageCloudCredentials.postman_globals.json file. You need to edit this in Postman to include your client ID and secret. These were provided during registration.

The collection relies on the environment JSON for the sandbox environment. Before trying to use the collection, make sure you have imported the Sandbox.postman_environment.json file into Postman.

Onboarding and authenticating with a payment service provider

This flow replicates a business onboarding with a payment service provider. Make sure the OnboardingAuthSuccess collection is imported in Postman.

  1. Obtain the access token for the organisation. You can make this request through the Onboarding and authentication API.

  2. Create a company in the organisation. The request passes the organisation ID and access token in the header and creates the company detailed in the body. This request is required when emulating the onboarding of a new business or organisation.

  3. Authenticate with the Payments Acceptance Service. Obtain an access token for the organisation and associated company.

  4. Get the payment service provider list. This request returns a list of payment service providers available to the company authorised in the JWT.

  5. Select the tab named “Test” in the Postman UI. Enter the index number of the service provider you’re emulating onboarding with. By default, this is populated with 0. You should change this to reflect the index of your payment service in the list.

  6. Send the request ID. The connector API will send the request ID. This is in response to the onboarding request sent by the Provider API.

  7. Authenticate the request ID. This request returns an access token granted to the payment servicer.

  8. Simulate the successful onboarding with your chosen payment provider.

  9. Check the account has been created in the Sage Payments Acceptance Service.

Failure onboarding and authenticating with a payment service provider

This flow emulates a business failing to onboard a payment service provider. Make sure the OnboardingAuthFailure collection is imported in Postman.

  1. Repeat steps 1 to 8 from Onboarding and authenticating with a payment service provider.

  2. Check the account has not been created in the Sage Payments Acceptance Service.

Making a payment submission

Make sure the MakingAPaymentSubmission collection is imported in Postman.

  1. Obtain the access token for the organisation. You can make this request through the Onboarding and authentication API.

  2. Create a company in the organisation. The request passes the organisation ID and access token in the header and creates the company detailed in the body. This request is required when emulating the onboarding of a new business or organisation.

  3. Authenticate with the Payments Acceptance Service. Obtain an access token for the organisation and associated company.

  4. Get the payment service provider list. This request returns a list of payment service providers available to the company authorised in the JWT.

  5. Obtain the authorisation URL for the payment service provider.

  6. Send the request ID. The connector API will send the request ID. This is in response to the onboarding request sent by the Provider API.

  7. Create a customer. This creates a customer in the Service’s database, with a customer ID and name.

  8. Create an invoice for the customer. Use the customer ID created in step 7.

  9. Request the Sage ID token from the payment servicer credentials on the id-shadow-sage sandbox environment.

  10. Mock the payment servicer transaction generated after invoice payment via the paymentSubmission endpoint.

  11. Check the status of the invoice now reads as “paid”.


User flow

Processing an invoice payment

This flow diagram details the full, end-to-end process for processing an invoice payment. From the user starting the payment process to receiving the updated invoice status.

The end user selects the “pay now” option before selecting the payment method. After the payment method is chosen, the Provider API sends a request to the payment servicer. This uses their connector API, and informs them of the transaction details.

The payment servicer must implement a connector API to receive and process provider API requests.

When the end user completes the payment, the consumer API receives the payment outcome. It then updates the invoice status in the Payments Acceptance Service. The calling Sage application is then informed of the success or failure and then updates the invoice status in its database.

Processing an invoice payment


Implement a connector API

To process the webhooks sent by the Consumer API you need to implement a connector API. The connector API allows Payments Acceptance Service to communicate with 3rd parties, and support the capabilities offered to customers.

Endpoints

The connector API is exposed through these endpoints:

  • /accounts
  • /payments
  • /refunds

Connector API specification

You can see the full specification – including response codes and payloads – in the Connector API reference section.

Building this API against the provided endpoints allows you to test the flows in the sandbox environment using the Postman collections. You can download the Postman collection here.


Using the Provider API

The Provider API allows a 3rd party’s integration to communicate with Payments Acceptance Service. This means their service can be offered to customers across the globe when they pay an invoice.

You can see the full API specification in the Provider API reference section.


Next steps

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