Security and Access

Access model

API access requires the applicable institution endpoint, mutual TLS using an accepted certificate, the required regulated role and any operation-specific consent or signing requirements.

See Before You Start for the certificate-based access model and institution endpoint selection.

Where customer authentication or authorisation is required, the API returns information for redirecting the PSU to the SMBC-hosted Strong Customer Authentication journey.

Transport and signing certificates

The transport certificate is presented when establishing the mutual TLS connection.

A signing certificate is used to create an application-layer signature where the operation requires one. A signing certificate does not replace the transport certificate.

The same certificate model applies to sandbox and production. Use certificates belonging to the connecting TPP:

• for London, use applicable real certificates accepted under the UK Open Banking framework; and
• for Frankfurt, Paris, Düsseldorf and Brussels, use applicable real eIDAS certificates.

SMBC does not issue or publish sandbox test certificates. A certificate accepted for transport does not remove the separate requirement for an accepted signing certificate where application-layer signing is required.

Mutual TLS and regulated roles

Mutual TLS is required for sandbox and production API connections.

The TPP certificate must support validation of the regulated role required for the operation:

• AISP access for account-information operations;
• PISP access for payment, signing-basket and funds-confirmations operations; and
• the applicable role for any other operation identified in the API Catalogue.

Establishing mutual TLS does not itself authorise the API request. The request remains subject to role, consent, resource and request-validation rules.

A mutual TLS connection can fail before an HTTP API response is available.

Application-layer signing

Some Payments API operations require an application-layer digital signature in addition to mutual TLS.

The SMBC signing profile is based on the Berlin Group NextGenPSD2 framework and uses the HTTP-signature approach described in the IETF Internet-Draft Signing HTTP Messages (draft-cavage-http-signatures-12), commonly referred to as the Cavage HTTP-signature format.

The Cavage format defines how selected HTTP headers are assembled into a signing string and digitally signed. The SMBC signing profile covers the following four HTTP request headers:

• Digest;
• X-Request-ID;
• TPP-Redirect-URI; and
• PSU-ID.

For an operation that requires a digital signature, each of these headers must be included in the signature if it is present in the HTTP request. This applies whether the header is mandatory or conditional for that operation. If one of these headers is absent from the HTTP request, it must not be included in the signature.

Application-layer signing is separate from mutual TLS:

• the QWAC establishes the mutually authenticated TLS connection; and
• the accepted QSEAL or equivalent signing certificate is used to create the application-layer signature.

Each signed request must include:

• Digest;
• Signature; and
• TPP-Signature-Certificate.

The Payments API Reference remains authoritative for the complete request, certificate and signature requirements.

Signed operations and signing headers

The following operations require application-layer signing. The table shows the headers required by the documented request for each operation. Each listed header must be included in both the headers="..." value of the Signature header and the signing string.

If another header from the SMBC signing profile is also present in the HTTP request, it must also be included in the signature. If a signing-profile header is absent from the HTTP request, it must not be included in the signature.

Request

POST /payments/{payment-product}

Headers required in the signature

• digest
• x-request-id
• psu-id

If TPP-Redirect-URI is also present in the HTTP request, tpp-redirect-uri must also be included in the signature.

---

Request

POST /payments/{payment-product}/{paymentId}/authorisations

Headers required in the signature

• digest
• x-request-id
• tpp-redirect-uri
• psu-id

---

Request

POST /signing-baskets

Headers required in the signature

• digest
• x-request-id
• tpp-redirect-uri
• psu-id

---

Request

DELETE /payments/{payment-product}/{paymentId}

Headers required in the signature

• digest
• x-request-id

If TPP-Redirect-URI or PSU-ID is also present in the HTTP request, the corresponding tpp-redirect-uri or psu-id header must also be included in the signature.

The SMBC signing profile covers Digest, X-Request-ID, TPP-Redirect-URI and PSU-ID. If any of these headers is present in the HTTP request, it must be included in both the headers="..." value of the Signature header and the signing string. If one of these headers is absent from the HTTP request, it must not be included in the signature.

The headers may be listed in any order. However, the order declared in the headers="..." value must match the order of the corresponding lines in the signing string.

This presence-based rule applies only to the four signing-profile headers. SMBC does not require (request-target). Do not include (request-target) or another HTTP request header merely because it is present or mandatory in the request.

Digest calculation

Calculate the SHA-256 hash of the exact request-body bytes and Base64-encode the resulting binary hash. Prefix the Base64 value with SHA-256= to form the complete Digest header value:

Digest: SHA-256=<Base64-encoded SHA-256 hash>

For example:

Digest: SHA-256=agWoTC4nAJGulQsuJv3+X2zgGUcMxRkQWtvJNghyVDk=

The calculation follows this sequence:

Request-body bytes
-> SHA-256 binary hash
-> Base64 encoding
-> prefix with "SHA-256="

The SHA-256= prefix is added after the hash has been calculated and Base64-encoded. The prefix is not part of the content being hashed.

The complete value, including the SHA-256= prefix, must be used as the value of the digest: entry in the signing string.

Calculate the digest only after the request body has reached its final transmitted form. The body sent to SMBC must be identical to the body used to calculate the digest. Changes to content, whitespace, line endings, character encoding or serialisation after calculation will produce a different digest and cause validation to fail.

Empty request bodies

The following signed operations have no request body:

• POST /payments/{payment-product}/{paymentId}/authorisations; and
• DELETE /payments/{payment-product}/{paymentId}.

For these operations, calculate the SHA-256 hash of an empty body, meaning zero bytes. Base64-encode that hash and add the SHA-256= prefix in the same way as for a populated request body.

Do not hash the text null, {}, an empty JSON string, a space, a newline or another placeholder. These values are not an empty body and produce a different digest.

Constructing the signing string

Construct the signing string using:

• every header required in the signature for the relevant operation;
• any other header from the SMBC signing profile that is present in the HTTP request;
• the lower-case header name; and
• the complete and exact value transmitted in the corresponding HTTP header.

The headers may be listed in any order. The order of the lines in the signing string must match the order of the header names declared in the headers="..." value of the Signature header.

Each line consists of:

<header-name>: <complete header value>

Use one colon followed by one space. Separate each line with a newline and do not add a newline after the final line.

Header names are lower-case in the signing string even though the corresponding HTTP request headers may use conventional casing. Header values must match the transmitted HTTP request exactly.

The following examples show the required signature headers for each documented request. If the HTTP request also contains another header from the SMBC signing profile, that header must also be included in both the headers="..." value and the signing string. A signing-profile header that is absent from the HTTP request must be omitted from both.

The order shown in each example is illustrative. A different order may be used provided that the order declared in the headers="..." value matches the order of the corresponding lines in the signing string.

Payment creation

For the request shown, the Signature header declares:

headers="digest x-request-id psu-id"

The signing string has this structure:

digest: SHA-256=<Base64-encoded SHA-256 hash of the payment body>
x-request-id: <X-Request-ID value>
psu-id: <PSU-ID value>

Payment authorisation

For the request shown, the Signature header declares:

headers="digest x-request-id tpp-redirect-uri psu-id"

The signing string has this structure:

digest: SHA-256=<Base64-encoded SHA-256 hash of an empty body>
x-request-id: <X-Request-ID value>
tpp-redirect-uri: <TPP-Redirect-URI value>
psu-id: <PSU-ID value>

Signing-basket creation

For the request shown, the Signature header declares:

headers="digest x-request-id tpp-redirect-uri psu-id"

The signing string has this structure:

digest: SHA-256=<Base64-encoded SHA-256 hash of the signing-basket body>
x-request-id: <X-Request-ID value>
tpp-redirect-uri: <TPP-Redirect-URI value>
psu-id: <PSU-ID value>

Payment cancellation

For the request shown, the Signature header declares:

headers="digest x-request-id"

The signing string has this structure:

digest: SHA-256=<Base64-encoded SHA-256 hash of an empty body>
x-request-id: <X-Request-ID value>

The presence-based signing rule applies only to Digest, X-Request-ID, TPP-Redirect-URI and PSU-ID. Do not include Consent-ID, PSU-IP-Address, PSU-Device-ID, Accept, Content-Type or another HTTP request header in the signature merely because it is present or mandatory in the request.

Creating the signature

For each signed request, the TPP must:

1. construct the complete request in its final transmitted form;
2. calculate and populate the Digest header;
3. construct the signing string using every required signature header and any other header from the SMBC signing profile that is present in the HTTP request, ensuring that the order of the lines matches the order declared in the headers="..." value;
4. sign the signing string using the private key corresponding to the accepted signing certificate;
5. populate the Signature header;
6. supply the corresponding public certificate in TPP-Signature-Certificate; and
7. send the request without changing the request body or any signed header value.

The Signature header contains:

• keyId, identifying the signing key or certificate;
• algorithm, identifying the signature algorithm;
• headers, containing the ordered signed-header list; and
• signature, containing the Base64-encoded digital signature.

For example, where Digest, X-Request-ID and PSU-ID are present in a payment-creation request, the Signature header may have the following structure:

Signature: keyId="<key identifier>",
algorithm="rsa-sha256",
headers="digest x-request-id psu-id",
signature="<Base64-encoded signature>"

The Payments API Reference defines the complete applicable values and requirements.

Signing certificate

Supply the public signing certificate in TPP-Signature-Certificate in the format defined by the Payments API Reference.

The private key used to create the signature must correspond to the public certificate supplied in the request. The signing certificate does not replace the QWAC required for mutual TLS.

Never supply SMBC with a private key, private-key passphrase or other secret.

Signature validation

SMBC reconstructs the signing string from the request received and verifies the signature using the supplied public signing certificate.

A request may be rejected where:

• a header required in the signature is missing or malformed, including where Digest, X-Request-ID, TPP-Redirect-URI or PSU-ID is present in the HTTP request but the corresponding header is omitted from the signature;
• the Digest value does not represent the request body received;
• SHA-256= is missing or incorrectly formatted;
• a populated body is changed after its digest is calculated;
• a request intended to have an empty body contains data, whitespace or another value;
• the headers="..." value does not include all applicable SMBC signing-profile headers present in the HTTP request, or includes a signing-profile header that is absent from the request;
• the order of the header names declared in the headers="..." value does not match the order of the corresponding lines used to construct the signing string;
• (request-target) or a header outside the SMBC signing profile is included in the signature;
• a signed value differs from the corresponding transmitted HTTP header;
• the signature cannot be verified using the supplied certificate; or
• the certificate, key identifier, algorithm or signature does not meet the applicable requirements.

The Payments API Reference remains authoritative for the complete operation-level request headers, digest calculation, signature algorithm, key identifier, certificate format, examples and error responses.