> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/tokenization/register-cards-via-batch-file/batch-file-definition.md).
# Batch file definition
This page defines the JSON batch file format used by the issuer to register end users and their cards.
Each batch file can contain up to **200 MB** of uncompressed data.
## Batch file structure
A batch file is a JSON object with the following top-level attributes:
| Name | Type | M/O/C | Description |
| --------- | ------ | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| header | Object | M | Header that describes the batch file and the migration request. |
| records | Array | M | Array of records. Each record corresponds to one consumer-and-card registration operation. |
| signature | String | M | Detached JSON Web Signature (JWS) of the payload, generated with the issuer private key. The corresponding public key is onboarded into D1 during issuer onboarding. |
### Header
The `header` object has the following structure:
| Name | Type | Size | M/O/C | Description |
| --------- | ------ | ---- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| batchId | String | 48 | M | Pattern: `^[A-Za-z0-9_-]{1,48}$`. Identifier of the batch file, as specified in the file name. |
| seqNumber | String | 48 | M | Pattern: `^[0-9]{1,48}$`. Sequence number of the batch file, as specified in the file name. |
| issuerId | String | 10 | M | Identifier of the issuer. |
| operation | String | N/A | M | Identifies the operation performed with this input file. Supported values are: `CONSUMER_CARD_REGISTRATION`, `CONSUMER_CARD_REGISTRATION_WITH_DIGITAL_CARDS`. |
#### **Operation values**
* `CONSUMER_CARD_REGISTRATION`\
Use this operation to register end users and their associated cards. If a card is already registered in D1 v1, you must use this operation. Existing digital cards will be automatically migrated to D1 v2.
* `CONSUMER_CARD_REGISTRATION_WITH_DIGITAL_CARDS`\
Use this operation to register end users and their associated cards and to migrate existing digital cards. The TSP is called to retrieve the already existing digital cards.
### Records
Each item in the `records` array has the following structure:
| Name | Type | Size | M/O/C | Description |
| ---------------------------------- | ------- | ---- | ----- | ------------------------------------------- |
| rowId | Integer | - | M | Incremental row identifier within the file. |
| consumerAndCardRegistrationRequest | Object | - | M | Payload containing consumer and card data. |
**`consumerAndCardRegistrationRequest` object**
| Name | Type | Size | M/O/C | Description |
| ------------------- | -------------- | ------ | ----- | -------------------------------------------------------------------------------------------------------------------- |
| consumerId | String | 1...64 | M | Pattern: `^[A-Za-z0-9_-]{1,64}$`. Unique identifier of the end user. |
| personalInformation | Object | - | O | Personal information of the end user. |
| cards | Array of cards | N/A | M | Array of card data for the account. The `cards` array **must not contain more than 20 cards** for a single consumer. |
**`personalInformation` object**
| Name | Type | Size | M/O/C | Description | | | |
| ----------------- | ------ | ------ | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ----------- | ---------------------------------------------------------------------- |
| gender | String | N/A | O | Enum: `MALE`, `FEMALE`, `OTHER`. | | | |
| language | String | 3 | C | Pattern: ^\[a-z]{3}$. Language code as defined by the ISO 639-2 standard (for example, eng).
Note: This field is mandatory for Click to Pay.
Accepted language codes: abk, aar, afr, alb, amh, ara, arm, aze, bel, ben, bis, bos, bul, bur, cat, nya, chi, hrv, cze, dan, div, dut, dzo, eng, est, fij, fin, fre, geo, ger, gre, grn, hat, hau, heb, hin, hun, ice, ind, gle, ita, jpn, kaz, khm, kin, kor, kur, kir, lao, lat, lav, lit, ltz, mac, mlg, may, mlt, mao, mah, mon, nau, nep, nor, orm, oss, pus, per, pol, por, rum, roh, rus, smo, sag, srp, sin, slo, slv, som, spa, swa, swe, tgk, tam, tha, ton, tur, tuk, ukr, urd, uzb, vie.
| | | |
| firstName | String | 1...40 | M | Pattern: ^\[\p{L}\p{N}\p{M} ,.'\_#;:/-]{1,40}$. First name of the end user.
Note: This field is mandatory for Click to Pay.
| | | |
| middleName | String | 1...40 | O | Pattern: `^[\p{L}\p{N}\p{M} ,.'_#;:\/-]{1,40}$`. Middle name of the end user. | | | |
| lastName | String | 1...40 | M | Pattern: ^\[\p{L}\p{N}\p{M} ,.'\_#;:/-]{1,40}$. Last name of the end user.
Note: This field is mandatory for Click to Pay.
| | | |
| secondLastName | String | 1...40 | O | Pattern: `^[\p{L}\p{N}\p{M} ,.'_#;:\/-]{1,40}$`. Second last name of the end user. | | | |
| dateOfBirth | String | 10 | O | Pattern: ^\d{4}-(0\[1-9] | 1\[012])-(0\[1-9] | \[12]\[0-9] | 3\[0-1])$
Date of Birth YYYY-MM-DD Example: "1990-01-01"
|
| title | String | N/A | O | Pattern: `^[\p{L}\p{N}\p{M} ,.'_#;:\/-]{1,40}$`. Enum: `Mr.`, `Mrs.`, `Miss`. Title of the end user. | | | |
| nationality | String | 2 | O | Pattern: `^[A-Z]{2}$`. Main nationality of the end user as an ISO 3166-1 alpha-2 code. | | | |
| email | String | 5..256 | C | Pattern: ^\[a-zA-Z0-9\_+&*-]+(?:.\[a-zA-Z0-9\_+&*-]+)\*@(?:\[a-zA-Z0-9-]+.)+\[a-zA-Z]{2,15}$. Email address of the end user, for example
Note: This field is mandatory for Click to Pay with Mastercard.
| | | |
| mobilePhoneNumber | Object | N/A | C | Mobile phone number object.
Note: This field is mandatory for Click to Pay.
| | | |
| residencyAddress | Object | N/A | C | End user's residency address.
Note: This field is mandatory for Click to Pay with Visa. When set for Click to Pay with Mastercard, all fields inside residencyAddress must be provided, in accordance with the Mastercard specification.
| | | |
**`mobilePhoneNumber` object**
| Name | Type | Size | M/O/C | Description |
| ----------- | ------ | ----- | ----- | ------------------------------------------------------------------------------------------------ |
| countryCode | String | 1..10 | M | Pattern: `^\+[0-9]{1,10}$`. International country code for the phone number, for example `+420`. |
| phoneNumber | String | 1..14 | M | Pattern: `^[0-9]{1,14}$`. Phone number without the country code, for example `777222333`. |
**`residencyAddress` object**
| Name | Type | Size | M/O/C | Description |
| ------------- | ------ | ----- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| recipientName | String | 1..64 | O | Pattern: `^[\p{L}\p{N}\p{M} ,.'_#;:\/-]{1,64}$`. Free-text field for the recipient name, if it differs from the first and last name. |
| line1 | String | 1..64 | M | Pattern: `^[\p{L}\p{N}\p{M} ,.'_#;:\/-]{1,64}$`. First line of the address. |
| line2 | String | 1..64 | O | Pattern: `^[\p{L}\p{N}\p{M} ,.'_#;:\/-]{1,64}$`. Second line of the address. |
| line3 | String | 1..64 | O | Pattern: `^[\p{L}\p{N}\p{M} ,.'_#;:\/-]{1,64}$`. Third line of the address. |
| line4 | String | 1..64 | O | Pattern: `^[\p{L}\p{N}\p{M} ,.'_#;:\/-]{1,64}$`. Fourth line of the address. |
| city | String | 1..32 | M | Pattern: `^[\p{L}\p{N}\p{M} ,.'_#;:\/-]{1,32}$`. City. |
| state | String | 1..30 | M | Pattern: ^\[\p{L}\p{N}\p{M} ,.'\_#;:/-]{1,30}$. State or region.
Note: If the consumer has cards enrolled in Click to Pay, this field must use the ISO 3166-2 format with a maximum of 3 characters.
|
| zipCode | String | 1..10 | M | Pattern: `^[0-9a-zA-Z -]{1,10}$`. Postal or ZIP code. |
| countryCode | String | 2 | M | Pattern: ^\[A-Z]{2}$. Country code in ISO 3166-1 alpha-2 format, for example CZ.
Note: This field is mandatory for Click to Pay.
|
**`card` object**
Each entry in the `cards` array has the following structure:
| Name | Type | Size | M/O/C | Description |
| ------------- | ------ | ------ | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | String | 1...48 | M | Pattern: `^[A-Za-z0-9_-]{1,48}$`. Issuer-assigned unique card identifier. |
| cardProductId | String | 1...48 | M | Pattern: `^[A-Za-z0-9_-]{1,48}$`. Unique identifier of the card profile. This value must match the onboarded card profile ID. |
| state | String | N/A | O | Enum: `ACTIVE`, `SUSPENDED`. State of the card. If not provided, the card is considered `ACTIVE`. |
| name | String | 0...26 | M | Pattern: `^[a-zA-Z. -]{0,26}$`. Name of the cardholder as it will appear on the physical or virtual card. For virtual cards, this value is used only for display. Empty string is supported. |
| secondName | String | 0...26 | O | Pattern: `^[a-zA-Z. -]{0,26}$`. Optional second cardholder name as it will appear on the physical card, printed under the first cardholder name. Not used for virtual cards. |
| encryptedData | String | - | M | Payload encrypted with the Thales public key. The unencrypted JSON payload format is: `{ "pan":"6789451266992345", "exp":"1125" }`. |
#### **Unencrypted card payload**
The unencrypted card payload inside `encryptedData` has the following structure:
| Name | Type | Size | M/O/C | Description |
| ---- | ------ | -------- | ----- | ------------------------------------------------------ |
| pan | String | Up to 19 | M | Funding PAN of the card. |
| exp | String | 4 | M | Card expiry date in `MMYY` format, for example `1125`. |
#### Encrypted data
The `encryptedData` field uses the same JWE format as the rest of the D1 solution.
For more details on how to build and encrypt this payload, refer to the "Encrypt sensitive data" section under "Integrate D1 API" paragraph.
## Batch file example
```json
{
"header": {
"batchId": "52bxaby7dw",
"seqNumber": "001",
"operation": "CONSUMER_CARD_REGISTRATION",
"issuerId": "d1power001"
},
"records": [
{
"rowId": 0,
"consumerAndCardRegistrationRequest": {
"consumerId": "pie000010200000000000035",
"personalInformation": {
"gender": "MALE",
"language": "fre",
"firstName": "firstName",
"middleName": "middleName",
"lastName": "lastName",
"secondLastName": "secondLastName",
"title": "Mr.",
"nationality": "FR",
"email": "myemail@dummymail.com",
"mobilePhoneNumber": {
"countryCode": "+1",
"phoneNumber": "123456789"
},
"residencyAddress": {
"recipientName": "recipientName",
"line1": "line1",
"line2": "line2",
"line3": "line3",
"line4": "line4",
"city": "Toulouse",
"state": "FR",
"zipCode": "00000",
"countryCode": "FR"
}
}
}
},
{
"rowId": 1,
"consumerAndCardRegistrationRequest": {
"consumerId": "pie000010200000000000036",
"personalInformation": {
"gender": "MALE",
"language": "fre",
"firstName": "firstName",
"middleName": "middleName",
"lastName": "lastName",
"secondLastName": "secondLastName",
"title": "Mr.",
"nationality": "FR",
"email": "myemail@dummymail.com",
"mobilePhoneNumber": {
"countryCode": "+1",
"phoneNumber": "123456789"
},
"residencyAddress": {
"recipientName": "recipientName",
"line1": "line1",
"line2": "line2",
"line3": "line3",
"line4": "line4",
"city": "Toulouse",
"state": "FR",
"zipCode": "31000",
"countryCode": "FR"
}
},
"cards": [
{
"id": "ZzLTT3m7St7VPYFrrVKvzL",
"cardProductId": "power_mastercard_lite_mode",
"name": "name",
"state": "ACTIVE",
"encryptedData": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiRUNESC1FUyIsImtpZCI6ImQxcG93ZXIwMDEtandlLTIwMjMxMDEzIiwiZXBrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiN3Q4VDZiWEMtdnhIaUdyZmMxa2cyMVdNWVlvT19PSFl0ZDBtNW93NmNFZyIsInkiOiJ0UVNoMVVrNU1Nc215YUs2T2xmYVBWLUI1LTVDSUgtMjMya3AxUkVoNFNRIn19..Rx-9Th7llx6vtoiP.NwbmXrsX9uZQrw5XMcrEL-EBJfh4aMgmq5jp5Nf1zF0P4NetCzYU.IU3OOM9NeBrgslHHjQN8Vw"
}
]
}
}
],
"signature": "AxY8DctDa….GlsbGljb3RoZQ="
}
```
## Signature
The `signature` field is a detached JWS, as defined in [RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515).
During issuer onboarding, the issuer must share the public key that corresponds to the private key used to sign the batch payload.
### Signature generation process
1. Remove all carriage returns, tabs, and white spaces from the JSON payload.
2. Encode the resulting string using UTF-8.
3. Initialize a JWS signer with the encoded data.
4. Set the protected header:
* `alg = "PS256"`
* `kid = "key identifier"`
5. Use the issuer private key to sign the data and produce a compact JWS string.
6. Split the JWS string into three parts using `.` as the separator.
7. Build the detached signature by concatenating the first and third parts with `..` (that is, `part0 + ".." + part2`).
8. Use this detached signature as the value of the `signature` field in the batch file.
Here is a code example that illustrates the process:
```js
const jose = require("jose");
const { pem2jwk } = require("pem-jwk");
async function generateJWS() {
const issuerSignPrivateKey = `-----BEGIN RSA PRIVATE KEY-----
................................................................
................................................................
................................................................
-----END RSA PRIVATE KEY-----`;
// Convert the PEM private key to JWK format
const privateKeyJWK = pem2jwk(issuerSignPrivateKey);
// Import the JWK into a key object
const privateKey = await jose.importJWK(privateKeyJWK);
// Create the payload to sign (as an object)
const input = {"header": {...},"records": [...]};
// Stringify and remove whitespace
const payload = JSON.stringify(input).replace(/\s+|\r?\n|\r|\n|\t/g, "");
const encode = new TextEncoder().encode(payload);
// Sign the payload with the private key
const jws = await new jose.CompactSign(encode)
.setProtectedHeader({ alg: "PS256", kid: "KID_VALUE" })
.sign(privateKey);
// Split the JWS to create the signature
const signParts = jws.split(".");
const signature = signParts[0] + ".." + signParts[2];
console.log("Signature:", signature);
}
// Call the function
generateJWS();
```
### JWS composition
A JWS object in compact serialization has the following structure:
`Base64URL (UTF-8 (JWS Header)) || '.' || Base64URL (JWS Payload) || '.' || Base64URL (JWS Signature)`
When using a **detached** payload, the JWS payload is replaced by an empty string:
`Base64URL (UTF-8 (JWS Header)) || '.' || '' || '.' || Base64URL (JWS Signature)`
or, more compactly:
`Base64URL (UTF-8 (JWS Header)) || '..' || Base64URL (JWS Signature)`
### JWS header
The protected header contains the following metadata:
| Name | Type | Size | Required/Optional/Conditional | Description |
| ---- | ------ | ---- | ----------------------------- | ------------------------------------------------------- |
| alg | Enum | N/A | Required | Algorithm used to sign the JWS payload. Value: `PS256`. |
| kid | String | 64 | Required | Key identifier of the key used to sign the JWS payload. |
### JWS payload
The payload to be signed is a JSON object that contains the `header` and `records` attributes, encoded in UTF-8 with **no** carriage returns, tabs, or white spaces. The canonical form is:
`{header:{...},records:[...]}`
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.payments.thalescloud.io/tokenization/register-cards-via-batch-file/batch-file-definition.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.