Authentication guide

1. Create a JWT Bearer token

A JWT Bearer token is included in the request body of an access token request. It allows Payments Hub to confirm the identity of the request sender and to check that they are permitted to access the API. Payments Hub does this by decoding the JWT Bearer token using the public key from the public-private key pair details you provided in the previous section. The decoded information, such as the kid and iss claim values, is then used to verify that the request was sent by you and not someone else.

You must create and sign a JWT Bearer token:

• In the live environment, you must create your own JWT Bearer token and sign it with your private key. For more information, see the Appendix: JWT Bearer token requirements section .

2. Obtain an access token

This section describes how to obtain the access token via an HTTP authentication request to the Oauth API. It also illustrates a successful response.

Request

Create and send a request using one of the following operations:

Sandbox:

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

Live:

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

Headers

The request must contain the headers shown in the following table.

Table: Obtain the access token – Required request headers.

Request body

The request must include the x-www-form-urlencoded key-value pairs shown in the following table.

Table: Obtain the access token – Request body keys.

Request example

The following example illustrates the request using raw HTTP code:

POST /oauth/token HTTP/1.1
Host: sandbox.apis.santander.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic YOUR_ENCODED_CLIENT_ID_AND_SECRET
Content-Length: 720
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&scope=makePayments&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ikh1YnRlc3RfcHJvX3NhbmRib3gifQ.eyJzdWIiOiJxTWtaOTBxb0hBTjVJbkE2V2xNYVZBaE41dDhBQWVPeCIsImlzcyI6IlNhbnRhbmRlciIsImlhdCI6MTYyOTg5MDgzMCwibmJmIjoxNjI5ODkwODMwLCJleHAiOjE2NjE0MjY4MzAsImp0aSI6ImY0NzQ1NzAzLTY4YWYtNDA1NC04Y2NlLTQ5ZDU5NWQzMGY3YiJ9.c-DbT1A4IFJEkaD4nr8vVw-zvp9yoYQxZLltiu65XyeHXb049qcux2meYuJ35fbVc3tUscjoFBY7f9PgQNVcI3kG50b0l2hRDCXeWqUjl8Rfq97ZX_o9IORMb7YyqltGv3i9X8N_-rd2AXYWxu4a27K5lDhY1C518K5Xqzx8xO8vNQfEj08Pxxi0inZC1UYAiQ-w0Hpp_tY1RqmZK_AFO3o7X0y59vc2qhTFXwBWcTOjc_SCfWpD-O0FO1Z-dn0OYWb_ZZ535hvu5C-ax6oYVsaiRrx7upuJ2oHCG3H6MESPgPSJrg70xTjE7tAKGmiywfIWYO_bA2XzzPrDYykSrQ

Response

If the request is valid, you receive an HTTP 200 OK response, which means that an access token was successfully issued. For further details of HTTP response codes and instructions on how to handle errors, see HTTP codes and request error handling.

In addition to the response code, the response body returns an access token.

Extract the value of the access_token key, as you’ll need it to call the API.

Example response body:

{
"access_token": "79c06aeb-e48e-4025-8cf7-dfasdfafgs44",
"token_type": "bearer",
"expires_in": "3599",
"scope": "makePayments"
}

Appendix: JWT Bearer token requirements

To use the API, you need 2 JSON Web Token (JWT) Bearer tokens:

• Authentication JWT Bearer token is used in all authentication requests for all API endpoints.

• Strong Customer Authentication (SCA) JWT Bearer token is additionally used in all API requests that submit a payment. The purpose of this token is to guarantee that payments are not repudiated.

To create your JWT Bearer token:

• Use a JWT generation library, such as auth0.

• Sign the token with a private key of your public-private key pair.

  Email your public key, along with the kid and iss claim values you will use in your JWT Bearer tokens, to the following address: paymentshubsupport@pagonxt.com

• The public key must be created with RSA and sent in PEM format, without password encryption, and must have a length of at least 2048 bits. If these criteria are not met, the token will be rejected.

• If you need to validate a signed token, you can use the JWT debugger at https://jwt.io .

The JWT Bearer token must follow the RFC-7519 standard.

The following example shows a JWT token header and payload content:

// Header
{
"kid": "san_jwt_profile",
"typ": "JWT",
"alg": "RS256"
}

// Payload
{
"sub": "exampleGlobalUID",
"nbf": 1584015598,
"iss": "yourCompany",
"exp": 1615551598,
"iat": 1584015598,
"jti": "4876bbe1-8905-4463-96f2-70df00722b9c"
}

The final signed token consists of 3 concatenated Base64url-encoded strings, separated by dots ("."):

JWT

<Header>.<Payload>.<Signature>

Authentication JWT Bearer token content

The authentication JWT Bearer token must contain the following claims. Additional optional claims are accepted too.

Table: Authentication JWT Bearer token claims.

SCA JWT Bearer token content

The SCA JWT Bearer token must contain the following claims.

Table: SCA JWT Bearer token claims.

The SCA JWT bearer token can also contain the following optional claims.

Table: SCA JWT Bearer token optional claims.

Request example

The following example illustrates the request using raw HTTP code:

POST /payments/pacs008/v10 HTTP/1.1
Host: sandbox.apis.santander.com
Content-Type: application/json
Authorization: Bearer 79c06aeb-e48e-4025-8cf7-dfasdfafgs44
X-Santander-Client-Id: YOUR_CLIENT_ID
sca-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InByb1BheW1lbnRzSHViU2IifQ.eyJoZCI6IjdoYldtZGcyNE5LQlI4c1VDK2EwamVQdmtXOG1hY0RoZnRXWGViYkRQd0k9Iiwibm9uY2UiOiIzNzZmYjMwNDJjN2YyMWNmY2M0ZSIsImFsZyI6IlNIQTI1NiIsImlzcyI6IlNhbnRhbmRlciIsImlhdCI6MTcxMjA1MTQwNiwibmJmIjoxNzEyMDUxNDA2LCJleHAiOjE3NDM1ODc0MDYsImp0aSI6IjY0ZGYyYWRmLWY2MmEtNDgxYi1iNTNkLWVhYzdiNTQ0NGFhZCJ9.KZDlWYSBHiOgRWQk6DrYy-9duMRrRCWydOVV2fssbEeq5Y4nYd9s0K9B-2qZS9qkqIAvWiKSeWf9rfz0BlvmeWQ_VI48XV2yWRmAj3RueOIV6VU57kuBEFIULgdQow5RFoPPPhOqMlx8IHqQf9axNhZYZjzAJ7Ko05bfNM1RLU3aor18zmHr0Yxnv6_4XyWwE1Nd92zDN6YpRDYNYvZol1MZahIYov8FQZetvOnf3Rj_qZZ1QkCkIhcVfTeJH5J7-_5w6RJZDjBsQnksWenlDwU7nGEzp4woO5TcfuDp3JeCQkYW2dHCJjYgBOs3ghB7-w8CE-vqONCWly62Jug0Sg
Content-Length: 3313

{
  "fitoFICstmrCdtTrf": {
    "grpHdr": {
      "msgId": "599302431952709700000000000",
      "creDtTm": "2023-11-17T04:30:31.111Z",
      "nbOfTxs": "1",
      "sttlmInf": {
        "sttlmMtd": "CLRG"
      }
    },
    "cdtTrfTxInf": [
      {
        "pmtId": {
          "endToEndId": "599302431952709700000000000",
          "txId": "599302431952709700000000000",
          "uetr": "14973c74-b91a-42fd-9b39-6435a7d6e1f4"
        },
        "pmtTpInf": {
          "svcLvl": [
            {
              "prtry": "FP"
            }
          ],
          "lclInstrm": {
            "prtry": "10"
          }
        },
        "intrBkSttlmAmt": {
          "value": 5.18,
          "ccy": "GBP"
        },
        "chrgBr": "SLEV",
        "dbtr": {
          "nm": "MISS LARA NOBLES",
          "pstlAdr": {
            "adrLine": [
              "119",
              "FUNNY ROAD",
              "BOURNEMOUTH",
              "BH8 10QT",
              "GBR"
            ]
          }
        },
        "dbtrAcct": {
          "id": {
            "othr": {
              "id": "11110801"
            }
          },
          "nm": "MISS LARA NOBLES"
        },
        "dbtrAgt": {
          "finInstnId": {
            "clrSysMmbId": {
              "mmbId": "090222"
            }
          }
        },
        "cdtrAgt": {
          "finInstnId": {
            "clrSysMmbId": {
              "mmbId": "086121"
            }
          }
        },
        "cdtr": {
          "nm": "Jessica Gale",
          "pstlAdr": {
            "adrLine": [
              "17",
              "Very Bright Street",
              "Golden Sand road",
              "Birmingham",
              "C1 1BN",
              "UK"
            ]
          }
        },
        "cdtrAcct": {
          "id": {
            "othr": {
              "id": "77791111"
            }
          },
          "nm": "Jessica Gale"
        },
        "rmtInf": {
          "ustrd": [
            "debtor-reference1"
          ],
          "strd": [
            {
              "cdtrRefInf": {
                "ref": "creditor-ref1"
              },
              "addtlRmtInf": [
                "P11607098610056"
              ]
            }
          ]
        }
      }
    ]
  }
}

Request example

The following example illustrates the request using raw HTTP code:

GET /payments/pacs002/v12/YOUR_PAYMENTS_HUB_ID HTTP/1.1
Host: sandbox.apis.santander.com
Authorization: Bearer 79c06aeb-e48e-4025-8cf7-dfasdfafgs44
X-Santander-Client-Id: YOUR_CLIENT_ID

ISO20022 API Specification

Check API Documentation

Click below to embark on your journey to new possibilities.

API Docs

Download Swagger File

Take the next step towards enhanced efficiency and performance.

Swagger file