Skip to content
Developerhome
Product homepage
Payments Acceptance Service

3. Integrate

  Less than to read

A Bruno collection is available to illustrate the Payments Acceptance 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 Acceptance Service flows. For more information about the collections, including use cases and flows, go to the provider flows section.

Payments Acceptance 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

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. You can follow the steps via the Bruno Collection above.

The Bruno 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 Bruno.

  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.

  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 Bruno.

  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 Bruno

  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.

  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 Bruno collections. Download the Bruno 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?