Skip to content

2. Get set up

  Less than to read

The Provider API and your needs

Integrating with Payments Acceptance Service allows Sage businesses to offer payment options for their customers and process their invoice payments.

Payments Acceptance Service is product agnostic. This means users of a range of products will be able to use this service.

For more information about Payments Acceptance Service and the Provider API, go to What is Payments Acceptance Service?.

If you’re looking for integration with a specific product, be aware that some features may be implemented differently across products.

The provider requirements

Review the requirements for a successful integration with the API. You can still integrate if some items are not complete, but you may need further assessment before integrating.

Partner requirements

  • Updates should be sent in near real time and in accordance with our status flows.
  • The Provider API will throttle requests at a rate agreed with the commercial team (default 10 requests per second). 429 responses may be returned if the provider exceeds the throttling rate and the provider should implement an appropriate backoff before retrying.

Authentication requirements

  • Use Sage ID access tokens until they expire. You do not need new tokens for each new request.
  • Your integration should ensure client credentials and API keys are stored securely.
  • You should notify us immediately of any breach of credentials.
  • Providers who support the notification endpoint must validate the API key header and Sage ID token.

Handling authorisation and notifications

With the Provider API you can handle notifications sent from the Payments Acceptance Service. This is an optional requirement.

Notifications (webhooks) are sent to the callback URL. These occur when a user tries to:

  • sign up to your payment service.
  • make an invoice payment with your payment service.

Technical requirements

You are responsible for maintaining the provider connector.

Your integration needs to include:

  • Authorisation endpoint URL (sandbox and production)
  • Preferred method of sending API key and client secret (to be agreed with Live Services Management)

The following are optional:

  • Notification endpoint URL (sandbox and production)
  • Notification header name and value required by the bank (this will be sent to their endpoint with all notifications)

Getting set up

What you need to do

After you’ve registered with us, you’ll need to:

  • Implement a connector API.
  • Onboard businesses to your service.

Implement a connector API

To process webhooks sent by the consumer API you need a connector API. This is needed to check when an invoice payment is made for your payment service.

Take a look at the OpenAPI 3.0 specification of an example connector API.

Onboard businesses to your service

You’ll be informed when a new business tries to onboard through your connector API. On handling the notification, an authorisation link is sent as a response. This allows the onboarding business to complete their application and onboarding request.

What you’ll get from us

After registration, you will receive these resources:

  • Access to our sandbox environment.
  • A provider-specific Postman environment. This contains your client credentials and keys to allow you run the Postman collections. You can find out more about this in Stage 3: Integrate.
  • An assigned contact from the Enablement team for setup queries.
  • Communication channels established for support.

Next steps

Find out what you need to do to successfully integrate with our service.

Was this helpful?