Definición del archivo por lotes

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 [e-mail]. 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

{
    "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": "[e-mail]",
                    "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": "[e-mail]",
                    "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.

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:

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:[...]}