Authentication Methods

Connected Payments APIs support multiple authentication methods to suit different integration patterns and security requirements. This page covers the three advanced methods available in addition to standard username and password authentication: X-Auth tokens, JWT Bearer tokens, and X-Signature.

Code Sample Disclaimer

Code samples within this document are provided for reference purposes only and are not intended for production use.

---

X-Auth Token Authentication

X-Auth is primarily used in frontend technologies and provides a means to create a scoped authentication token with pre-defined mandatory key-value pairs. If any enforced parameters are modified during processing by the consumer or a malicious third party, the request will be rejected as tampered. All fields not defined during initial authentication may be set and changed freely by the consumer.

Supported APIs

• Transaction APIs
• Tokenisation APIs

Implementation

Creating an X-Auth token requires three components:

1. A data scope to be enforced
2. A signature to verify the scope
3. A configId to enforce any additional required fields

Step 1 — Define the data scope

Identify all field keys and values that should be locked and enforced. This data must include a userName. Collect the fields as a JSON object, then convert to a query string:

{
  "merchReference": "c559da0d-a259-435d-81cb-5f91e6037e6e",
  "userName": "sampleUser",
  "configId": "f2417aa2-d14b-41fc-a82e-e6d2736a34c1",
  "txnType": "0",
  "amount": "1.00"
}

Query string form:

merchReference=c559da0d-a259-435d-81cb-5f91e6037e6e&userName=sampleUser&configId=f2417aa2-d14b-41fc-a82e-e6d2736a34c1&txnType=0&amount=1.00

Step 2 — Sign the scope

Use the userName's shared secret to sign the query string using SHA-256 HMAC:

da91b35bebc455d548227667caf2dc810979a97684d261e4bea55c96f6e3ecd5

Step 3 — Define a configId

A configId created via Connected Payments' config service should be used to apply any required fields. This allows you to define which fields are mandatory on submission from the consumer, and tie requirements conditionally to other fields.

For example, you may require expiryDate and cvv to always be present when a PAN is submitted, without making PAN itself required.

Step 4 — Request the X-Auth token

Submit a request to /hmac/v2/hmac/validate with the following payload:

{
  "data": "merchReference=c559da0d-a259-435d-81cb-5f91e6037e6e&userName=sampleUser&configId=f2417aa2-d14b-41fc-a82e-e6d2736a34c1&txnType=0&amount=1.00",
  "verifyMessage": "da91b35bebc455d548227667caf2dc810979a97684d261e4bea55c96f6e3ecd5",
  "configId": "f2417aa2-d14b-41fc-a82e-e6d2736a34c1",
  "userName": "sampleUser"
}

On success, a header x-authentication-token will be returned alongside config details. This token can now be used in subsequent transaction requests.

---

JWT Bearer Token Authentication

Authentication tokens allow you to reduce the exposure risk of sending a userName and password with every request. Tokens are signed JWTs that carry the full scope of the creating user's permissions and can be used in place of credentials until they expire.

Supported APIs

• Transaction APIs
• Tokenisation APIs
• Reporting APIs
• Dynamic Query APIs
• Surcharge APIs
• Aggregate APIs
• User APIs
• Role APIs
• Customer APIs
• Config APIs

Token Scope

When a token is created it inherits the full scope of permissions of the creating user. Tokens are signed to prevent manipulation and include an expiry date controlled by Connected Payments environmental settings.

Checking Token Expiry

It is important to track token expiry and proactively request a new token before the current one expires.

To check expiry, split the JWT into its three parts — header, payload, and signature — and inspect the exp field in the payload. This value is an epoch timestamp in UTC.

Getting a Token

A token is returned on almost all successful authentication responses. Alternatively, you can request one directly at any time by submitting a userName and password to:

POST /merchanthub/api/v1/auth/virtual/signature

Using a Token

Include the token in the Authorization header with the Bearer prefix:

Authorization: Bearer <token>

---

X-Signature Authentication

X-Signature provides a password-free authentication method using JWS ECDSA ES512, resulting in a signed JWT placed in the x-signature request header. Connected Payments also returns an x-signature on responses, which can be verified using Connected Payments's public key (available on request).

Prerequisites

Before implementing X-Signature, the following must be in place:

• Approval from your Connected Payments Account Manager (may require a change request)
• An elliptic P521 certificate (private key retained by you)
• The corresponding public key provided to Connected Payments

Supported APIs

• Transaction APIs

X-Signature Calculation

The following steps must be completed in order:

Step 1 — Create the JWS header

Create the JWT header object and base64 URL encode it:

{
  "typ": "JWT",
  "alg": "ES512"
}

Step 2 — Define the final request payload

Prepare the full API request body (without password). All Field Level Encryption (FLE) should already be applied at this stage:

{
  "userName": "abc123",
  "ecm": "31",
  "amount": 12300,
  "pan": "123",
  "cardExpiryDate": "11/23",
  "cvv": "123",
  "merchReference": "ABC123",
  "txnType": "0",
  "requestorIp": "127.0.0.1"
}

Step 3 — Base64 URL encode the request

Stringify the JSON and base64 URL encode it:

eyJ1c2VyTmFtZSI6ImFiYzEyMyIsImVjbSI6IjMxIiwiYW1vdW50IjoxMjMwMCwicGFuIjoiMTIzIiwiY2FyZEV4cGlyeURhdGUiOiIxMS8yMyIsImN2diI6IjEyMyIsIm1lcmNoUmVmZXJlbmNlIjoiQUJDMTIzIiwidHhuVHlwZSI6IjE4IiwicmVxdWVzdG9ySXAiOiIxMjcuMC4wLjEifQ

Step 4 — Sign the payload using Elliptic P521

Sign the base64 encoded payload using your private P521 elliptic certificate. The signature may be returned in R/S format — if so, it must be converted to DER format before proceeding.

Sample R and S:

{
  "r": "e3f8f2bb676e62c597d08af69738ded02c11786157fe461e9f2b944a7f6e5460abb04556315d39da37e1bbd8f2d730672d73cf9a00928597676effc9442e9fcb9f",
  "s": "104158a6beab1d84951b7bf7bef277ffd381df2ff7da98a840e2787084f0db18916e71eebf681226aab445ef729b3980821bc33276f33bb7a3fce11dae670ce48b9",
  "recoveryParam": 0
}

DER format (hex):

308188024200e3f8f2bb676e62c597d08af69738ded02c11786157fe461e9f2b944a7f6e5460abb04556315d39da37e1bbd8f2d730672d73cf9a00928597676effc9442e9fcb9f02420104158a6beab1d84951b7bf7bef277ffd381df2ff7da98a840e2787084f0db18916e71eebf681226aab445ef729b3980821bc33276f33bb7a3fce11dae670ce48

Step 5 — Base64 URL encode the signature

Base64 URL encode the DER-format signature bytes:

MIGIAkIA4/jyu2duYsWX0Ir2lzje0CwReGFX/kYenyuUSn9uVGCrsEVWMV052jfhu9jy1zBnLXPPmgCShZdnbv/JRC6fy58CQgEEFYpr6rHYSVG3v3vvJ3/9OB3y/32pioQOJ4cITw2xiRbnHuv2gSJqq0Re9ymzmAghvDMnbzO7ej/OEdrmcM5I

Step 6 — Assemble the final JWT

Concatenate the three components with . separators in this order:

<base64-header>.<base64-payload>.<base64-signature>

Place the resulting JWT in the x-signature request header.

---

Field Level Encryption (FLE)

When using X-Signature, the following fields must be submitted using Field Level Encryption:

• PAN
• Driver's Licence
• Account Number
• Secure Token
• CVV

Encryption uses a public key provided by your Connected Payments account manager combined with AES256CBC (A256CBC-HS512). Once encrypted, each field should be submitted as a valid JWE value. Encrypted fields support up to 2000 characters, though the decrypted value is still validated against normal field rules.

PLEASE NOTE

The FLE public certificate expires and is regularly rotated. Ensure your implementation checks and updates the certificate in use to avoid service interruption.

FLE Steps

Step 1 — Collect the field value

Collect the plain-text value to be encrypted (e.g. a PAN: 4111111111111111).

Step 2 — Create the JWT header

{
  "alg": "RSA-OAEP",
  "enc": "A256CBC-HS512",
  "cty": "text/plain"
}

Step 3 — Generate Key, HMAC Key, and IV

Generate uniquely for each request (do not reuse):

Component	Specification
Key	256 bits (32 bytes)
HMAC Key	256 bits (32 bytes)
IV	128 bits (16 bytes)

Step 4 — Encrypt the field value (AES256CBC)

Encrypt the plain-text field value using AES256CBC with PKCS7 padding, using the Key and IV from Step 3. The result is the encrypted payload (ciphertext).

Step 5 — Hash using HMAC SHA512

Hash the following fields in order (no delimiters) using the HMAC Key under SHA512 to produce an authentication tag:

Field	Format
JWE Header	Base64 encoded
IV	Hex
Payload (encrypted bytes)	Raw bytes — not encoded
JWE Header Length	Big-endian unsigned integer

Step 6 — Encrypt the Key using RSA-OAEP

Encrypt the HMAC Key and Key (concatenated in hex, HMAC Key first) using RSA-OAEP and the Connected Payments FLE public certificate for your environment.

Step 7 — Encode and concatenate to form the JWE

Base64 URL encode each component and concatenate with . in this order:

1. JWT Header (Step 2)
2. Encrypted key (Step 6)
3. IV (Step 3)
4. Payload (Step 4)
5. Tag (Step 5)

Step 8 — Insert into the API request

Replace the plain-text field in your API request with the full JWE string:

{
  "userName": "abc123",
  "ecm": "31",
  "amount": 12300,
  "pan": "<JWE token here>",
  "cardExpiryDate": "11/23",
  "cvv": "123",
  "merchReference": "ABC123",
  "txnType": "0",
  "requestorIp": "127.0.0.1"
}

PLEASE NOTE

The X-Signature for authentication must be calculated on the final payload, with all FLE fields already populated with their full JWE values.