Payments Hub quick reference

This document provides a quick overview of the Payments Hub ISO20022 API and concepts related to RESTful APIs, with links to further information.

For information on the Payments Hub API specifically, and how to test it in the sandbox environment, see Tutorials and Sandbox details.

API specification

The API is a RESTful API that follows the OpenAPI Specification and is provided as a YAML file, which you can download from the Developer Marketplace. You can view the downloaded YAML file in any environment or UI you are used to working with, for example, the Swagger Editor.

URLs

Each API operation has a URL that you need to use when sending requests. The URL consists of a host URL (same for all the operations), a base path, and an operation-specific part:

POST <Host URL>/<Base path>/<Operation-specific part>

The API uses the following URLs and base path:

Sandbox host URL:

URL https://sandbox.apis.santander.com

Live host URL:

URL https://apis.santander.com

Base path:

URL /payments

Example endpoint URL:

URL https://sandbox.apis.santander.com/payments/pacs008/v08

For information on the operation-specific parts, see Determining which API operation you need.

Authentication

The API endpoints are protected with OAuth 2.0 JSON Web Token (JWT) Bearer grant, meaning that you must obtain a JWT profile access token before sending API requests. The access token is included in every API request and is used by the API to make sure that only authorized and approved applications can access the API operations.

You must use the following parameters and URLs in your authentication request:

Parameters:

• Mandatory scope parameter must be set to makePayments.

• For the assertion parameter, a JSON Web Token (JWT) Bearer token is required. For a predefined sandbox token and requirements for live tokens, see Authentication guide.

Sandbox URL:

https://sandbox.apis.santander.com/oauth/token

Live URL:

https://apis.santander.com/oauth/token

Note

The authentication endpoint can be used to perform a health check for the Payments Hub API, allowing you to confirm that there are no issues with the system. Sending a request to the authentication endpoint does not automatically invalidate any of the earlier access tokens you have received.

For more information on authentication, see Authentication guide.

HTTP operation types

HTTP operation types are used to define what an HTTP request can do. Currently, the API only contains POST and GET operations. The following table explains how the API uses them.

Table: HTTP operation types

Request content

The following sections provide information about the content of a request sent to the API.

Headers

HTTP requests include headers that contain important information that the API needs to, for example, authenticate and identify the request sender.

HTTP requests to the API can have various required and optional header parameters depending on the API operation. The following table shows the mandatory header parameters used by the API.

Table: Headers

Path parameters

HTTP requests can use path parameters to specify a resource that the request relates to. Unlike header parameters, path parameters are included in the request URL. Path parameters mean that the request does not need to include a request body as the API can identify the resource using the path parameter.

The only URL path parameter used by the API is the paymentsHubId parameter, which represents a previously initiated payment operation. It is used in GET operations to let the API know for which payment operation you are retrieving information.

Request bodies

The request body is the part of an HTTP request that contains the information that is used by the API. They are typically used in POST requests and contain the details needed by the API to create a new resource.

The request bodies of the API are formatted as JSON objects and use message formats defined in the ISO20022 standard. For information on the ISO20022 message formats used by the API, see Message field definitions.

Retry policy

Most APIs have a retry policy, which defines what to do in the event that an HTTP request fails. For example, it determines what intervals to use when resending a failed request, and how many times to send it.

For information on the API retry policy and how to handle client- or server-side error response codes from the API, see HTTP codes and request error handling.

Notifications

You can receive notifications from an API, to allow you to track what is going on with your payments.

The API supports notifications for payment updates, such as when the status of a payment has changed, or a refund payment is initiated. For more information on notifications and how to receive them, see Notifications.

API versioning

In Payments Hub, the entire API has a version and, in addition, each operation (endpoint) has a separate version indicated by version identifiers in the URL. For example: https://sandbox.apis.gruposantander.com/v2/payments/pacs008/v08, where 'v2' indicates that the pacs008.v08 operation is version 2.

The Payments Hub API uses semantic versioning for the overall API, where the version is indicated by 3 version values separated by points.

Major version

A major version update of an API indicates a breaking change, which is where the behaviour of an existing documented API has changed in such a way that the API may no longer work for you. To work with the updated API version, you must modify the way you create your API requests.

Examples of breaking changes include:

• Removing, renaming, or moving API entities such as:

  • Operations

  • Operation HTTP methods

  • Operation query, body, or header parameters

  • Schema properties

  • Authorization roles

• Changing the way in which an API works, for example, introducing a new security token to be included in the request or modifying the API functionality.

• Making optional parameters or schema properties mandatory.

A major version update of an API resets the minor and patch version values to '0'. For example, If an API at version 2.1.2 undergoes a major update, the version changes to 3.0.0.

Minor version

A minor version update indicates backward compatible changes to an API. You can use the updated API version without modifying the way you use it. Changes are considered backward compatible if they add optional new features to an API.

Examples of backward compatible changes include:

• Adding optional request parameters

• Adding new API operations with new payment services

• Adding new fields to an existing API response or to objects within it

• Reordering fields within an API response

• Bug fixes

A minor version update of an API resets the patch version value to '0'. For example, If an API at version 2.1.2 undergoes a minor update, the version changes to 2.2.0.

Patch version

A patch version update indicates changes to the API specification documentation that do not impact the implementation of the API. Patch updates are corrections or improvements to descriptions or examples in the API specification.

When API version changes

Payments Hub informs you of upcoming major API releases and provides sufficient time for you to migrate to the new version. Alongside this, Payments Hub continues to support previous versions for a minimum of 6 months, with both the new and old API versions running in parallel during this period. Unfortunately, ensuring backwards compatibility in the longer term is often cost-prohibitive and can present a technically insurmountable challenge.

All minor and patch version updates are backward compatible changes, so you can continue to use the old API version or move to the new one and decide if you want to modify your API requests to take advantage of the new features. If you do not upgrade to a new major API version within the given time, and try to access an obsolete or unsupported API version, Payments Hub returns a 300 series HTTP status code that indicates redirection, used in conjunction with the location HTTP header that redirects to the appropriate version.