Inbound APIs (to Thales D1)

OpenAPI specification for APIs your system calls on Thales D1.

Get Access Token

post

/oauth2/token

This request is used by the Merchant Gateway backend to get an access token.

Header parameters

x-correlation-idstringRequired

Random identifier which can be used to correlate the different API calls done as part of a single use-case. This identifier will be the one primarily used for troubleshooting.

Warning: This identifier should not be derived from sensitive personal data, as its value will be logged in clear.

There is no strong guarantee of the uniqueness of this identifier, so please refrain from using it for other purpose than logging and troubleshooting.

Pattern: ^[A-Za-z0-9_-]{1,64}$

Body

grant_typeconst: urn:ietf:params:oauth:grant-type:jwt-bearerRequired

Describes the flow.
In our case we have defined the JWT bearer flow, so you will have to set urn:ietf:params:oauth:grant-type:jwt-bearer

assertionstringRequired

The assertion is the entire JWT value.
Please refer to OAuth2 Access Token for more details on how to generate this JWT.
The JWT must contain the following fields:

iss: Issuer of the JWT. It shall be the merchant gateway identifier and it will be used to lookup the onboarded public key.
exp: The validity must be the expiration time of the assertion within 15 minutes, expressed as the number of seconds from 1970-01-01T0:0:0Z measured in UTC.

Supported alg: ES256.

Example: ey...HRT8LOON8z

Responses

200

Default allowed response

application/json

access_tokenstringOptional

The access_token that will be used to call the APIs.

Example: ey...HRT6LOON7w

expires_innumberOptional

Remaining time in seconds for the access_token to expire.

Example: 900

token_typestringOptional

Type of the access_token that will be used to call the APIs.

Example: Bearer

scopestringOptional

Scope of the access_token.

Example: d1-s2s:api:merchant-gtw

400

Bad Request - Not Retryable

Error Code	Description
INVALID_FIELD	Contains the field in error (first found)
MISSING_FIELD	Contains the missing field (first found)

application/json

post/oauth2/token

POST /authz/v1/oauth2/token HTTP/1.1
Host: api.d1.thalescloud.io
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 102

{
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "assertion": "hhhhhhh.pppppppp.ssssssssss"
}

{
  "access_token": "ey...HRT6LOON7w",
  "expires_in": 900,
  "token_type": "Bearer",
  "scope": "d1-s2s:api:merchant-gtw"
}

Create a Merchant

post

/merchant-gateways/{merchantGatewayId}/merchants

Create a merchant.

Authorizations

AuthorizationstringRequired

A JWT generated by the Get Access Token API.
The server checks the validity of the provided token to control access to this protected resource.

Path parameters

merchantGatewayIdstring · min: 10 · max: 10Required

Merchant Gateway Identifier.

Example: MGW_000001Pattern: ^[A-Za-z0-9_-]{10}$

Header parameters

x-correlation-idstringRequired

Random identifier which can be used to correlate the different API calls done as part of a single use-case. This identifier will be the one primarily used for troubleshooting.

Warning: This identifier should not be derived from sensitive personal data, as its value will be logged in clear.

There is no strong guarantee of the uniqueness of this identifier, so please refrain from using it for other purpose than logging and troubleshooting.

Pattern: ^[A-Za-z0-9_-]{1,64}$

Body

merchantNamestring · min: 1 · max: 64Required

An unique merchant name that is end user friendly.

Example: My MerchantPattern: ^[A-Za-z0-9-_. ]+$

Responses

201

Created

application/json

merchantIdstring · min: 11 · max: 11Required

Merchant Identifier (aka Token Requestor ID) generated by the scheme TSP for that merchant.

Example: 10610027312Pattern: ^[A-Za-z0-9_-]{11}$

creationDateTimestring · date-timeRequired

Creation date time as defined by RFC 3339, section 5.6

400

Bad Request - Not Retryable

Error Code	Description
FIELD_INVALID_FORMAT	JSON not well formatted or one field is not expected format as defined in this documentation (first found)

application/json

401

Unauthorized - Not Retryable

403

Forbidden - Not Retryable

Error Code	Description
AUTHORIZER_FORBIDDEN	User is not authorized to access this resource

500

Server Error - Not Retryable

Error Code	Description
INTERNAL_ERROR	Internal D1 error
TSP_ERROR	An error occurred with TSP

application/json

503

Service Unavailable - Retryable

post/merchant-gateways/{merchantGatewayId}/merchants

POST /ecom-dcs/merchant-gateways/{merchantGatewayId}/merchants HTTP/1.1
Host: api.d1.thalescloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 30

{
  "merchantName": "My Merchant"
}

{
  "merchantId": "10610027312",
  "creationDateTime": "2026-01-01T00:00:00.000Z"
}

Create a Token

post

/merchant-gateways/{merchantGatewayId}/merchants/{merchantId}/tokens

Create a token from specified card details.

Authorizations

AuthorizationstringRequired

A JWT generated by the Get Access Token API.
The server checks the validity of the provided token to control access to this protected resource.

Path parameters

merchantGatewayIdstring · min: 10 · max: 10Required

Merchant Gateway Identifier.

Example: MGW_000001Pattern: ^[A-Za-z0-9_-]{10}$

merchantIdstring · min: 11 · max: 11Required

Merchant Identifier (aka Token Requestor ID) generated by the scheme TSP for that merchant.

Example: 10610027312Pattern: ^[A-Za-z0-9_-]{11}$

Header parameters

x-correlation-idstringRequired

Random identifier which can be used to correlate the different API calls done as part of a single use-case. This identifier will be the one primarily used for troubleshooting.

Warning: This identifier should not be derived from sensitive personal data, as its value will be logged in clear.

There is no strong guarantee of the uniqueness of this identifier, so please refrain from using it for other purpose than logging and troubleshooting.

Pattern: ^[A-Za-z0-9_-]{1,64}$

Body

encryptedDatastringRequired

The user and card information encrypted in a JWE structure (see data encryption section).

Once decrypted, the JWE plaintext contains the following JSON object:

JSON field parameter name	description	MOC	Length
fpan	The funding pan to tokenize.	M	From 10 to 19
exp	The expiry date in format MMYY.	M	4
name	The card holder name in the format FIRSTNAME LASTNAME or as written on the card.	O	Up to 128 char
cvv	The security code. It can help the issuer in the decision of approving the payment.	O	3 or 4

Example: {"fpan":"5123456789012345", "exp":"0822", "name":"JOHN DOE", "cvv":"123"}

Example: ey...4FT8LOON8z

Responses

201

Created

application/json

tokenIdstring · min: 1 · max: 48Required

Token unique identifier

Example: 01fb32ff-5ed0-497f-8835-6af0916f29c0Pattern: ^[A-Za-z0-9_-]{1,48}$

cardLastDigitsstringRequired

The card last digits

If the card is a cobagde card with a primary and an auxiliary PAN, then the primary PAN is used to generate the last digits

Example: 0037Pattern: ^[0-9]{4}$

cardExpiryDatestringRequired

Card expiry date in MMYY format

Example: 0928Pattern: ^(0[1-9]|1[0-2])\d{2}$

tokenStatestring · enumRequired

Token state

Possible values:

encryptedTokenDatastringRequired

The token data encrypted in a JWE structure (see data encryption section).

Once decrypted, the JWE plaintext contains the following JSON object:

JSON field parameter name	description	MOC	Length
dpan	The token pan value.	M	From 10 to 19
exp	The token expiry date in format MMYY.	M	4

Example: {"dpan":"5123456789012345", "exp":"0822"}

Example: ey...8GT8LOON8z

creationDateTimestring · date-timeRequired

Creation date time as defined by RFC 3339, section 5.6

400

Bad Request - Not Retryable

Error Code	Description
FIELD_INVALID_FORMAT	JSON not well formatted or one field is not expected format as defined in this documentation (first found)
CRYPTO_ERROR	Unable to decrypt payload

application/json

401

Unauthorized - Not Retryable

403

Forbidden - Not Retryable

Error Code	Description
AUTHORIZER_FORBIDDEN	User is not authorized to access this resource
PAN_NOT_ELIGIBLE	The PAN is not eligible for tokenization. For a cobadge card having an auxiliary PAN, this error is returned if the auxiliary PAN has never been registered by the card issuer into D1.
ISSUER_DECLINED	The Issuer declined the tokenization.

application/json

404

Bad Request - Not Retryable

Error Code	Description
UNKNOWN_ISSUER	Not able to identify the card issuer. The PAN used in the request does not match any card registered in D1 by an issuer.
UNKNOWN_MERCHANT	Not able to identify the merchant.

application/json

500

Bad Request - Not Retryable

Error Code	Description
INTERNAL_ERROR	Internal D1 error
TSP_ERROR	An error occurred with TSP
ISSUER_ERROR	An error occurred with Issuer

application/json

503

Service Unavailable - Retryable

post/merchant-gateways/{merchantGatewayId}/merchants/{merchantId}/tokens

POST /ecom-dcs/merchant-gateways/{merchantGatewayId}/merchants/{merchantId}/tokens HTTP/1.1
Host: api.d1.thalescloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 35

{
  "encryptedData": "ey...4FT8LOON8z"
}

{
  "tokenId": "01fb32ff-5ed0-497f-8835-6af0916f29c0",
  "cardLastDigits": "0037",
  "cardExpiryDate": "0928",
  "tokenState": "ACTIVE",
  "encryptedTokenData": "ey...8GT8LOON8z",
  "creationDateTime": "2026-01-01T00:00:00.000Z"
}

Delete a token

delete

/merchant-gateways/{merchantGatewayId}/merchants/{merchantId}/tokens/{tokenId}

Delete a token.

Authorizations

AuthorizationstringRequired

A JWT generated by the Get Access Token API.
The server checks the validity of the provided token to control access to this protected resource.

Path parameters

merchantGatewayIdstring · min: 10 · max: 10Required

Merchant Gateway Identifier.

Example: MGW_000001Pattern: ^[A-Za-z0-9_-]{10}$

merchantIdstring · min: 11 · max: 11Required

Merchant Identifier (aka Token Requestor ID) generated by the scheme TSP for that merchant.

Example: 10610027312Pattern: ^[A-Za-z0-9_-]{11}$

tokenIdstring · min: 1 · max: 48Required

Token unique identifier

Example: 01fb32ff-5ed0-497f-8835-6af0916f29c0Pattern: ^[A-Za-z0-9_-]{1,48}$

Header parameters

x-correlation-idstringRequired

Random identifier which can be used to correlate the different API calls done as part of a single use-case. This identifier will be the one primarily used for troubleshooting.

Warning: This identifier should not be derived from sensitive personal data, as its value will be logged in clear.

There is no strong guarantee of the uniqueness of this identifier, so please refrain from using it for other purpose than logging and troubleshooting.

Pattern: ^[A-Za-z0-9_-]{1,64}$

Responses

204

No Content

No content

400

Bad Request - Not Retryable

Error Code	Description
FIELD_INVALID_FORMAT	JSON not well formatted or one field is not expected format as defined in this documentation (first found)

application/json

401

Unauthorized - Not Retryable

403

Forbidden - Not Retryable

Error Code	Description
AUTHORIZER_FORBIDDEN	User is not authorized to access this resource

404

Bad Request - Not Retryable

Error Code	Description
UNKNOWN_TOKEN	Not able to identify the token.
UNKNOWN_MERCHANT	Not able to identify the merchant.

application/json

500

Bad Request - Not Retryable

Error Code	Description
INTERNAL_ERROR	Internal D1 error
TSP_ERROR	An error occurred with TSP

application/json

503

Service Unavailable - Retryable

delete/merchant-gateways/{merchantGatewayId}/merchants/{merchantId}/tokens/{tokenId}

DELETE /ecom-dcs/merchant-gateways/{merchantGatewayId}/merchants/{merchantId}/tokens/{tokenId} HTTP/1.1
Host: api.d1.thalescloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
x-correlation-id: text
Accept: */*

No content

Get the token metadata

get

/merchant-gateways/{merchantGatewayId}/merchants/{merchantId}/tokens/{tokenId}/metadata

Get token metadata.

Authorizations

AuthorizationstringRequired

A JWT generated by the Get Access Token API.
The server checks the validity of the provided token to control access to this protected resource.

Path parameters

merchantGatewayIdstring · min: 10 · max: 10Required

Merchant Gateway Identifier.

Example: MGW_000001Pattern: ^[A-Za-z0-9_-]{10}$

merchantIdstring · min: 11 · max: 11Required

Merchant Identifier (aka Token Requestor ID) generated by the scheme TSP for that merchant.

Example: 10610027312Pattern: ^[A-Za-z0-9_-]{11}$

tokenIdstring · min: 1 · max: 48Required

Token unique identifier

Example: 01fb32ff-5ed0-497f-8835-6af0916f29c0Pattern: ^[A-Za-z0-9_-]{1,48}$

Header parameters

x-correlation-idstringRequired

Random identifier which can be used to correlate the different API calls done as part of a single use-case. This identifier will be the one primarily used for troubleshooting.

Warning: This identifier should not be derived from sensitive personal data, as its value will be logged in clear.

There is no strong guarantee of the uniqueness of this identifier, so please refrain from using it for other purpose than logging and troubleshooting.

Pattern: ^[A-Za-z0-9_-]{1,64}$

Responses

200

Get Token Metadata response

application/json

Notice that the card last digits and the card expiry are always returned except if the card has been deleted by the issuer.

cardLastDigitsstringOptional

The card last digits

If the card is a cobagde card with a primary and an auxiliary PAN, then the primary PAN is used to generate the last digits

Example: 0037Pattern: ^[0-9]{4}$

cardExpiryDatestringOptional

Card expiry date in MMYY format

Example: 0928Pattern: ^(0[1-9]|1[0-2])\d{2}$

tokenStatestring · enumRequired

Token state

Possible values:

creationDateTimestring · date-timeRequired

Creation date time as defined by RFC 3339, section 5.6

lastUpdateDateTimestring · date-timeOptional

Last update date time as defined by RFC 3339, section 5.6

400

Bad Request - Not Retryable

Error Code	Description
FIELD_INVALID_FORMAT	JSON not well formatted or one field is not expected format as defined in this documentation (first found)

application/json

401

Unauthorized - Not Retryable

403

Forbidden - Not Retryable

Error Code	Description
AUTHORIZER_FORBIDDEN	User is not authorized to access this resource

404

Bad Request - Not Retryable

Error Code	Description
UNKNOWN_TOKEN	Not able to identify the token.
UNKNOWN_MERCHANT	Not able to identify the merchant.

application/json

500

Bad Request - Not Retryable

Error Code	Description
INTERNAL_ERROR	Internal D1 error

application/json

503

Service Unavailable - Retryable

get/merchant-gateways/{merchantGatewayId}/merchants/{merchantId}/tokens/{tokenId}/metadata

GET /ecom-dcs/merchant-gateways/{merchantGatewayId}/merchants/{merchantId}/tokens/{tokenId}/metadata HTTP/1.1
Host: api.d1.thalescloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
x-correlation-id: text
Accept: */*

{
  "cardLastDigits": "0037",
  "cardExpiryDate": "0928",
  "tokenState": "ACTIVE",
  "creationDateTime": "2026-01-01T00:00:00.000Z",
  "lastUpdateDateTime": "2026-01-01T00:00:00.000Z"
}

Create Transaction

post

/merchant-gateways/{merchantGatewayId}/merchants/{merchantId}/tokens/{tokenId}/transactions

Provide all required data to the Merchant/PSP to build a transaction authorisation request.

Authorizations

AuthorizationstringRequired

A JWT generated by the Get Access Token API.
The server checks the validity of the provided token to control access to this protected resource.

Path parameters

merchantGatewayIdstring · min: 10 · max: 10Required

Merchant Gateway Identifier.

Example: MGW_000001Pattern: ^[A-Za-z0-9_-]{10}$

merchantIdstring · min: 11 · max: 11Required

Merchant Identifier (aka Token Requestor ID) generated by the scheme TSP for that merchant.

Example: 10610027312Pattern: ^[A-Za-z0-9_-]{11}$

tokenIdstring · min: 1 · max: 48Required

Token unique identifier

Example: 01fb32ff-5ed0-497f-8835-6af0916f29c0Pattern: ^[A-Za-z0-9_-]{1,48}$

Header parameters

x-correlation-idstringRequired

Random identifier which can be used to correlate the different API calls done as part of a single use-case. This identifier will be the one primarily used for troubleshooting.

Warning: This identifier should not be derived from sensitive personal data, as its value will be logged in clear.

There is no strong guarantee of the uniqueness of this identifier, so please refrain from using it for other purpose than logging and troubleshooting.

Pattern: ^[A-Za-z0-9_-]{1,64}$

Body

transactionIdstringRequired

The unique transaction identifier

Example: Rrn123456789Pattern: ^[A-Za-z0-9]{1,12}$

transactionDateTimestringRequired

UTC Transaction date in 'YYYYMMDDhhmmss' format.

Example: 20260225140530Pattern: ^[0-9]{14}$

amountstringRequired

Amount in the smallest unit of currency, right justified with leading zeros

Example: 000000002100Pattern: ^[0-9]{12}$

currencyCodestringRequired

Currency code as per ISO 4217

Example: 978Pattern: ^[0-9]{3}$

Responses

201

Created

application/json

encryptedDatastringRequired

The payment credentials data encrypted in a JWE structure (see security section in the documentation).

Once decrypted, the JWE plaintext contains the following JSON object:

JSON field parameter name	description	MOC	Length
dpan	The token PAN value	M	Up to 19
exp	The token expiry date in the format MMYY	M	4
cryptogram	The payment cryptogram to use with the token for a payment	M	Up to 256

Example: {"dpan:"9580981500100002", "exp":"1222", "cryptogram": "45f8grzty7f4f5gs5s2c"}

400

Bad Request - Not Retryable

Error Code	Description
FIELD_INVALID_FORMAT	JSON not well formatted or one field is not expected format as defined in this documentation (first found)

application/json

401

Unauthorized - Not Retryable

403

Forbidden - Not Retryable

Error Code	Description
AUTHORIZER_FORBIDDEN	User is not authorized to access this resource
OPERATION_NOT_ALLOWED	Invalid token state

404

Bad Request - Not Retryable

Error Code	Description
UNKNOWN_TOKEN	Not able to identify the token.

application/json

500

Bad Request - Not Retryable

Error Code	Description
INTERNAL_ERROR	Internal D1 error
TSP_ERROR	An error occurred with TSP

application/json

503

Service Unavailable - Retryable

post/merchant-gateways/{merchantGatewayId}/merchants/{merchantId}/tokens/{tokenId}/transactions

POST /ecom-dcs/merchant-gateways/{merchantGatewayId}/merchants/{merchantId}/tokens/{tokenId}/transactions HTTP/1.1
Host: api.d1.thalescloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
x-correlation-id: text
Content-Type: application/json
Accept: */*
Content-Length: 116

{
  "transactionId": "Rrn123456789",
  "transactionDateTime": "20260225140530",
  "amount": "000000002100",
  "currencyCode": "978"
}

{
  "encryptedData": "text"
}

PreviousD1 API reference

NextOutbound APIs (from Thales D1)

Last updated 7 months ago

Was this helpful?