バッチファイル構造

このページは、イシュアのバックエンドが一括更新用に提供するバッチファイル形式を定義します。

バッチファイルの構造

バッチファイルは次の構造を持ちます：

NAME	TYPE	M/O/C	説明
header	Object	M	バッチ更新リクエストを記述するヘッダー。
records	Array	M	レコードを含む配列。各レコードは1つの操作に対応します。
署名	String	M	このフィールドは分離されたJSON Web Signature（JWS）を表します。署名はイシュアの秘密鍵で作成する必要があります。D1オンボーディング時に、イシュアは対応する公開鍵を共有します。詳細は参照してください JWS.

Header

ヘッダーは次の構造を持ちます：

NAME	TYPE	SIZE	M/O/C	説明
batchId	String	48	M	ファイル名で指定されたバッチファイルの識別子。
seqNumber	String	48	M	ファイル名で指定されたバッチファイルのシーケンス番号。
issuerId	String	48	M	イシュアの識別子。
operation	String	48	M	入力ファイルで実行される操作を識別します。値： VIRTUAL_CARD_REGISTRATION.

Records

レコードは次の構造を持ちます：

NAME	TYPE	SIZE	M/O/C	説明
rowId	int	-	M	増分行識別子。
virtualCardRegistrationRequest	Object	-	M	バーチャルカード登録リクエストのペイロード。

virtualCardRegistrationRequest

NAME	TYPE	SIZE	M/O/C	説明
card	Card型のオブジェクト	N/A	M	暗号化されたカードデータを含むオブジェクト。

Where the card has the following structure:

NAME	TYPE	SIZE	M/O/C	説明
id	String	1...48	M	イシュアによって割り当てられた一意の識別子。
encryptedData	String	-	M	Thalesの公開鍵で暗号化されたPKCS#7ペイロード。
scheme	String	-	M	値： VISA または MASTERCARD.

コンテンツ暗号化アルゴリズムは AES256/CBC/PKCS7Padding.

RSA公開鍵（2048ビット）に対してサポートされる鍵暗号化アルゴリズムは RSA/OAEPWithSHA256AndMGF1Padding.

詳細については、参照してください データ暗号化とセキュリティ.

復号されたペイロードの構造は次のとおりです：

NAME	TYPE	SIZE	M/O/C	説明
fpan	String	最大20	M	資金提供カードのFPAN。例： {"fpan":"6789451266992345"}.

署名

署名オブジェクトは、によって指定されたJWS方式を使用します RFC 7515.

D1オンボーディング中に、イシュアは公開鍵を共有する必要があります。

手順

1. ペイロードから改行文字と空白を削除します。
2. ペイロードを使用してエンコードします UTF-8.
3. エンコードされたデータで署名オブジェクトを初期化します。
4. 保護ヘッダーを設定します：

   1. alg = "PS256"
   2. kid = "キー識別子"
5. 秘密鍵を使用してデータに署名し、JWSオブジェクトを生成します。
6. 区切り文字としてを使用してJWS文字列を部分に分割します。 . を区切り文字として。
7. 最初と3番目の部分を組み合わせて分離署名を作成します ...
8. 分離署名を返します。

例（Node.js）：

const jose = require("jose");
const { pem2jwk } = require("pem-jwk");

async function generateJWS() {
        const issuerSignPrivateKey = `-----BEGIN RSA PRIVATE KEY-----
................................................................
................................................................
................................................................
-----END RSA PRIVATE KEY-----`;

    // PEM形式の秘密鍵をJWK形式に変換する
    const privateKeyJWK = pem2jwk(issuerSignPrivateKey);

    // JWKをキーオブジェクトにインポートする
    const privateKey = await jose.importJWK(privateKeyJWK);

    // 署名するペイロードを作成する（オブジェクトとして）
    const input = {"header": {...},"records": [...]};
    // 文字列化して空白を削除する
    const payload = JSON.stringify(input).replace(/\s+|\r?\n|\r|\n|\t/g, "");
    const encode = new TextEncoder().encode(payload);

    // 秘密鍵でペイロードに署名する
    const jws = await new jose.CompactSign(encode)
        .setProtectedHeader({ alg: "PS256", kid: "KID_VALUE" })
        .sign(privateKey);

    // 署名を作成するためにJWSを分割する
    const signParts = jws.split(".");
    const signature = signParts[0] + ".." + signParts[2];

    console.log("Signature:", signature);
}

// 関数を呼び出す
generateJWS();

JWS の構成

次の形式は JWS オブジェクトの表現を示します：

Base64URL(UTF-8(JWS ヘッダー)) || '.' || Base64URL(JWS ペイロード) || '.' || Base64URL(JWS 署名)

分離署名が使用されるため、JWS ペイロードは空の文字列に置き換えられます：

Base64URL(UTF-8(JWS ヘッダー)) || '..' || Base64URL(JWS 署名)

JWS ヘッダー

ヘッダーには次のメタデータが含まれます：

NAME	TYPE	SIZE	必須/任意/条件付き	説明
alg	列挙型	該当なし	必須	JWS ペイロードの署名に使用されるアルゴリズム。値は PS256.
kid	String	64	必須	JWS ペイロードの署名に使用された鍵のキー識別子。

JWS ペイロード

署名対象のペイロードは、次の属性を持つ JSON オブジェクトです： header および records 属性。これは UTF-8 エンコーディングを使用し、改行や空白を含みません。例： {header:{...},records:[...]}

バッチファイルの例

{
    "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="
}