Batch file structure

This page defines the batch file format that the issuer backend provides for batch updates.

Batch file structure

The batch file has the following structure:

NAME	TYPE	M/O/C	DESCRIPTION
header	Object	M	The header describing the batch update request.
records	Array	M	The array containing the records. Each record corresponds to an operation.
signature	String	M	This field represents a detached JSON Web Signature (JWS). The signature must be created with the issuer private key. During D1 onboarding, the issuer shares the corresponding public key. For details, see JWS.

Header

The header has the following structure:

NAME	TYPE	SIZE	M/O/C	DESCRIPTION
batchId	String	48	M	The identifier of the batch file as specified in the file name.
seqNumber	String	48	M	The sequence number of the batch file as specified in the file name.
issuerId	String	48	M	The identifier of the issuer.
operation	String	48	M	Identifies the operation that will be performed with the input file. Value: VIRTUAL_CARD_REGISTRATION.

Records

A record has the following structure:

NAME	TYPE	SIZE	M/O/C	DESCRIPTION
rowId	int	-	M	The incremental row identifier.
virtualCardRegistrationRequest	Object	-	M	The virtual card registration request payload.

virtualCardRegistrationRequest

NAME	TYPE	SIZE	M/O/C	DESCRIPTION
card	Object of type Card	N/A	M	An object containing the encrypted card data.

Where the card has the following structure:

NAME	TYPE	SIZE	M/O/C	DESCRIPTION
id	String	1...48	M	The unique identifier assigned by the issuer.
encryptedData	String	-	M	PKCS#7 payload encrypted with the Thales public key.
scheme	String	-	M	Values: VISA or MASTERCARD.

The content encryption algorithm is AES256/CBC/PKCS7Padding.

The supported key encryption algorithm for an RSA public key (2048-bit) is RSA/OAEPWithSHA256AndMGF1Padding.

For details, see Data encryption and security.

The structure of the deciphered payload is as follows:

NAME	TYPE	SIZE	M/O/C	DESCRIPTION
fpan	String	Up to 20	M	FPAN of the funding card. Example: {"fpan":"6789451266992345"}.

Signature

The signature object uses the JWS scheme as specified by RFC 7515.

During D1 onboarding, the issuer must share the public key.

Process

1. Remove carriage returns and whitespace from the payload.

2. Encode the payload using UTF-8.

3. Initialize a signing object with the encoded data.

4. Set the protected header:

   1. alg = "PS256"

   2. kid = "key identifier"

5. Use the private key to sign the data and produce a JWS object.

6. Split the JWS string into parts using . as the separator.

7. Create the detached signature by combining the first and third parts with ...

8. Return the detached signature.

Example (Node.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

The following format shows the representation of a JWS object:

Base64URL(UTF-8(JWS header)) || '.' || Base64URL(JWS payload) || '.' || Base64URL(JWS signature)

As the detached signature is used, the JWS Payload is replaced by an empty string:

Base64URL(UTF-8(JWS header)) || '..' || Base64URL(JWS signature)

JWS header

The 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 is PS256.
kid	String	64	Required	Key identifier of the key used to sign the JWS payload.

JWS payload

The payload to sign is a JSON object with the header and records attributes. It uses UTF-8 encoding and contains no carriage returns or whitespace. Example: {header:{...},records:[...]}

Batch file example

{
    "header": {
        "batchId": "0000000000001111111111FF",
        "seqNumber": "005",
        "operation": "VIRTUAL_CARD_REGISTRATION",
        "issuerId": "BANK_ABC"},
    "records": [
            {
            "rowId": 0,
            "virtualCardRegistrationRequest": {
                "card":{
                    "id":"FWSPMC000000000fcb2f4136b2f4136a0532d2f4136a0532",
                    "encryptedData":"KDlTthhZTGufMY…….xPSUrfmqCHXaI9wOGY=",
                    "scheme":"MASTERCARD"}
                }
            },
            {
            "rowId": 1,
            "virtualCardRegistrationRequest": {
                "card":{
                    "id":"FWSPMC000000000fcb2f4136b2f4136a0532d2f4136a0532",
                    "encryptedData":"KDlTthhZTGufMY…….xPSUrfmqCHXaI9wOGY=",
                    "scheme":"MASTERCARD"}
                }
            }
    ],
    "signature": "AxY8DctDa….GlsbGljb3RoZQ="
}