- 18 Sep 2024
- 8 Minutes to read
- Print
- DarkLight
Authentication guide
- Updated on 18 Sep 2024
- 8 Minutes to read
- Print
- DarkLight
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.api.pagonxt.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). | String | Required |
assertion | JWT bearer token you created in the previous step | String | Required |
scope | Scope of the access token. | String | Required |
Request example
The following example illustrates the request using raw HTTP code:
POST /oauth/token HTTP/1.1
Host: sandbox.api.pagonxt.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.
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:
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: payments.support@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.api.pagonxt.com
Content-Type: application/json
Authorization: Bearer 79c06aeb-e48e-4025-8cf7-dfasdfafgs44
X-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.api.pagonxt.com
Authorization: Bearer 79c06aeb-e48e-4025-8cf7-dfasdfafgs44
X-Client-Id: YOUR_CLIENT_ID