Skip to content
Developerhome
Product homepage
Payments Acceptance 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 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’ll have received the environment JSON after registering. This has the details of the sandbox environment, and includes your Sage ID and secret. The environment JSON must be imported into Postman so the collections can 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, import the Provider API Postman collection into 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
  • customers
  • invoices

Onboarding and authenticating with a payment service provider

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

  1. Get the access token for the organisation.

  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. Get an access token for the company to make requests to the Payments Acceptance Service.

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

To select the service provider, select the Test tab 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.

  1. Request the onboarding URL to the selected payment service provider. In this request, the Payments Acceptance Service will send the request ID to the Connector API.

  2. Request the Sage ID token on the id-shadow-sage sandbox environment to emulate Provider API request in the next step.

  3. Emulate the payment service provider calls the Provider API /authSuccess endpoint to notify successful onboarding. Use the request ID sent by the Payments Acceptance Service in step 5.

  4. Get the available account list. Check the payment provider’s account has been created in the Payments Acceptance Service.

Onboarding and authenticating with a payment service provider

Failure onboarding and authenticating with a payment service provider

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

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

  2. Emulate the payment service provider calls the Provider API /authFailure endpoint to notify failed onboarding. Use the request ID sent by the Payments Acceptance Service in step 5.

  3. Get the available account list. Check the payment provider’s account has not been created in the Payments Acceptance Service.

Making a payment submission

Make sure the Making a payment submission collection is imported in Postman.

  1. Get the access token for the organisation.

  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. Get an access token for the company to make requests to the Payments Acceptance Service.

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

To select the service provider, select the Test tab 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.

  1. Request the authorisation URL to the selected payment service provider. Onboard to chosen payment service using the URL in this response.

  2. Get the available account list. Check the payment provider’s account has been created in the Payments Acceptance Service.

  3. Create a customer. This creates a customer in the Payments Acceptance Service database, with a customer ID and name.

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

  5. Request the Sage ID token on the id-shadow-sage sandbox environment to emulate Provider API request in the next step.

  6. Emulate the payment service provider calls the Provider API /paymentsubmission endpoint to notify successful payment generation. Use the payment ID created in step 8.

  7. Get the payment information. Check the status of the invoice now reads as “PAID”.

Making a payment submission

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 pay now before selecting the payment method. After the payment method is chosen, the Provider API sends a request to the payment provider. This uses their connector API, and informs them of the transaction details.

The payment provider 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

Two-step payment

Payments Acceptance Service default payment flow is one-step payment as described above. Alternatively, we support the provider performing a two-step process to submit payment. In this process, Payments Acceptance Service expects to obtain payment information once users authorise the payment. Then it sends a request to payment endpoint to submit a payment.

Processing two step 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
  • /prepare
  • /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. Download the Postman collection.

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 review the full API specification in the Provider API reference section.

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?