Authentication guide
  • 03 Apr 2024
  • 6 Minutes to read
  • Dark
    Light

Authentication guide

  • Dark
    Light

Article summary

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:

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.

Header name

Description

Required/Optional

Values

Authorization

Authorization basic security header.

To create the value, use the client ID (user) and client secret (password) you received when registering your app.

Required

Basic Base64Encode(<Client_ID>:<Client_Secret>)

Content-Type

Format of the request body

Required

application/x-www-form-urlencoded

Accept

Format of the response body

Required

application/json

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.

Key

Description

Data type

Required/Optional

grant_type

Grant type (JWT Bearer token).
Value: urn:ietf:params:oauth:grant-type:jwt-bearer

String

Required

assertion

JWT bearer token you created in the previous step

String

Required

scope

Scope of the access token.
Value: makePayments

String

Required

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&amp;scope=makePayments&amp;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.

Element

Description

Data type

access_token

Access token

String

token_type

Token type.

Value: bearer

String

expires_in

Seconds until the access token expires.

If the access token expires, you must send a new request to get a new token.

Integer

scope

Scope of the access token.

Value: makePayments

String

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:

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.

Type

Claim

Description

Header

kid

Unique key ID of the public-private key pair you use to sign the JWT token.

Note:

You must use the same value for the kid claim in both authentication and SCA JWT Bearer tokens. The value must match the value you have provided to Payments Hub along with your public key.

Header

typ

Media type of the token.

Value: JWT

Header

alg

Public-private key pair algorithm used to sign the JWT token.

Value: RS256

Payload

sub

Client ID you received when subscribing to the API

Payload

nbf

Time before which the JWT is not accepted for processing.

The value must be a NumericDate (seconds since the epoch) defining the current time or a time in the future.

Payload

iss

Name of the JWT issuer.

This value is usually your name or Internet domain.

Note:

You must use the same value for the iss claim in both authentication and SCA JWT Bearer tokens. The value must match the value you have provided to Payments Hub along with your public key.

Example value: yourCompany

Payload

exp

Expiration time on or after which the JWT is not accepted for processing.

The value must be a NumericDate (seconds since the epoch) defining a time in the future.

Payload

iat

Time at which the JWT token was issued.

The value must be a NumericDate (seconds since the epoch).

This value is automatically generated by most JWT generation libraries.

Payload

jti

Unique ID for the JWT token.

This value is automatically generated by most JWT generation libraries.

SCA JWT Bearer token content

The SCA JWT Bearer token must contain the following claims.

Table: SCA JWT Bearer token claims.

Type

Claim

Description

Header

kid

Unique key ID of the public-private key pair you use to sign the JWT token.

Note:

You must use the same value for the kid claim in both authentication and SCA JWT Bearer tokens. The value must match the value you have provided to Payments Hub along with your public key.

Header

typ

Media type of the token.

Value: JWT

Header

alg

Public-private key pair algorithm used to sign the JWT token.

Value: RS256

Payload

iss

Name of the JWT issuer.

This value is usually your name or internet domain.

Note:

You must use the same value for the iss claim in both authentication and SCA JWT Bearer tokens. The value must match the value you have provided to Payments Hub along with your public key.

Example value: yourCompany

Payload

exp

Expiration time on or after which the JWT is not accepted for processing.

The value must be a NumericDate (seconds since the epoch) defining a time in the future.

Payload

iat

Time at which the JWT token was issued.

The value must be a NumericDate (seconds since the epoch).

This value is automatically generated by most JWT generation libraries.

Payload

jti

Unique ID for the JWT token.

This value is automatically generated by most JWT generation libraries.

Payload

alg

Public-private key pair algorithm used to sign the JWT token.

Value: SHA256

Payload

hd

Base64-encoded SHA256 hash of the ISO message included in the API request's message body.

If the content in the claim does not match the message body, the API request fails.

Payload

nonce

Unique ID for the message.

The value can be freely defined.

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

Table: SCA JWT Bearer token optional claims.

Type

Claim

Description

Payload

nbf

Time before which the JWT is not accepted for processing.

The value must be a NumericDate (seconds since the epoch) defining the current time or a time in the future.

Payload

payment_id

Unique payment ID.

The value can be freely defined.

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.

Download Swagger File

Take the next step towards enhanced efficiency and performance.


Was this article helpful?