{
  "schemaVersion": "1.0.0",
  "contractVersion": "2026-08-25.9",
  "dictionaries": {
    "additionalFields": {
      "id": "additional-fields",
      "title": "Additional field keys",
      "description": "Candidate keys and formats. Requiredness is merchant-, flow-, route-, and downstream-provider-specific; confirm the exact schema with the PayStar manager.",
      "itemContract": {
        "key": "string",
        "value": "flow-specific"
      },
      "requiredness": "varies by flow, route and downstream provider",
      "privacyRule": "Send only fields required by the confirmed flow; do not follow the broad 'send all' recommendation blindly.",
      "items": [
        {
          "key": "productCode",
          "category": "payment_method_and_card",
          "description": "Internal product or service code.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "Merch-12345"
        },
        {
          "key": "cardNumber",
          "category": "payment_method_and_card",
          "description": "Full card PAN. Only send through a PCI-authorized H2H flow.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "<PAN>",
          "sensitivity": "PCI"
        },
        {
          "key": "cardExpireMonth",
          "category": "payment_method_and_card",
          "description": "Card expiry month in MM format.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "05",
          "sensitivity": "PCI"
        },
        {
          "key": "cardExpireYear",
          "category": "payment_method_and_card",
          "description": "Card expiry year in YY format.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "26",
          "sensitivity": "PCI"
        },
        {
          "key": "cardCvv",
          "category": "payment_method_and_card",
          "description": "CVV/CVC, 3–4 digits. Must never be stored.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "<CVV>",
          "sensitivity": "PCI_HIGH"
        },
        {
          "key": "cardHolder",
          "category": "payment_method_and_card",
          "description": "Name printed on the card.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "JOHN DOE",
          "sensitivity": "personal_data"
        },
        {
          "key": "cardToken",
          "category": "payment_method_and_card",
          "description": "Tokenized card identifier issued by a bank/provider.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "<BANK_CARD_TOKEN>",
          "sensitivity": "secret_like"
        },
        {
          "key": "cardStorageToken",
          "category": "tokenization",
          "description": "Token used for subsequent payments in the merchant tokenized flow; availability and storage responsibility depend on the assigned profile.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/deposits#token",
          "example": "<PAYSTAR_CARD_STORAGE_TOKEN>"
        },
        {
          "key": "type",
          "category": "payment_method",
          "description": "Payment type selector used in examples, e.g. card; not listed in the field catalog.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "card"
        },
        {
          "key": "firstName",
          "category": "customer_identity_kyc",
          "description": "Customer first name.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "John",
          "sensitivity": "personal_data"
        },
        {
          "key": "middleName",
          "category": "customer_identity_kyc",
          "description": "Customer middle name.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "Michael",
          "sensitivity": "personal_data"
        },
        {
          "key": "lastName",
          "category": "customer_identity_kyc",
          "description": "Customer last name.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "Smith",
          "sensitivity": "personal_data"
        },
        {
          "key": "customerDocumentId",
          "category": "customer_identity_kyc",
          "description": "Government-issued document identifier; include document type where required.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "Passport <ID>",
          "sensitivity": "KYC_HIGH"
        },
        {
          "key": "customerBirthdayDate",
          "category": "customer_identity_kyc",
          "description": "Date of birth in YYYY-MM-DD format.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "1990-04-05",
          "sensitivity": "personal_data"
        },
        {
          "key": "customerNationality",
          "category": "customer_identity_kyc",
          "description": "Nationality, ISO 3166-1 alpha-3.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "NLD",
          "sensitivity": "personal_data"
        },
        {
          "key": "email",
          "category": "customer_contact_and_address",
          "description": "Customer email address.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "customer@example.com",
          "sensitivity": "personal_data"
        },
        {
          "key": "phoneNumber",
          "category": "customer_contact_and_address",
          "description": "Customer phone number.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "31612345678",
          "sensitivity": "personal_data"
        },
        {
          "key": "telecomOperator",
          "category": "customer_contact_and_address",
          "description": "Mobile network enum/name used for telecom payments and routing.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "vodafone-uk"
        },
        {
          "key": "dialingCode",
          "category": "customer_contact_and_address",
          "description": "International dialing code.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "31"
        },
        {
          "key": "customerAddress",
          "category": "customer_contact_and_address",
          "description": "Customer street address.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "123 Main Street",
          "sensitivity": "personal_data"
        },
        {
          "key": "customerCity",
          "category": "customer_contact_and_address",
          "description": "Customer city/locality.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "Amsterdam",
          "sensitivity": "personal_data"
        },
        {
          "key": "customerState",
          "category": "customer_contact_and_address",
          "description": "State or region where applicable.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "Noord-Holland",
          "sensitivity": "personal_data"
        },
        {
          "key": "customerZipCode",
          "category": "customer_contact_and_address",
          "description": "Postal or ZIP code.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "1012 AB",
          "sensitivity": "personal_data"
        },
        {
          "key": "customerCountryCode",
          "category": "customer_contact_and_address",
          "description": "ISO 3166-1 alpha-3 country code.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "NLD",
          "sensitivity": "personal_data"
        },
        {
          "key": "customerCountry",
          "category": "customer_contact_and_address",
          "description": "Full country name if required by the downstream PSP.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "Netherlands",
          "sensitivity": "personal_data"
        },
        {
          "key": "beneficiaryName",
          "category": "bank_and_payment_details",
          "description": "Legal name of the beneficiary/account holder.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "John Smith",
          "sensitivity": "financial_personal_data"
        },
        {
          "key": "bankName",
          "category": "bank_and_payment_details",
          "description": "Bank enum/name used for routing.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "all"
        },
        {
          "key": "bankAccount",
          "category": "bank_and_payment_details",
          "description": "Beneficiary bank account number.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "<ACCOUNT_NUMBER>",
          "sensitivity": "financial_high"
        },
        {
          "key": "iban",
          "category": "bank_and_payment_details",
          "description": "International Bank Account Number.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "<IBAN>",
          "sensitivity": "financial_high"
        },
        {
          "key": "bankCode",
          "category": "bank_and_payment_details",
          "description": "Country-specific national bank identifier.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "<BANK_CODE>"
        },
        {
          "key": "bankBranch",
          "category": "bank_and_payment_details",
          "description": "Local branch identifier/name.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "<BRANCH>"
        },
        {
          "key": "ifcsCode",
          "category": "bank_and_payment_details",
          "description": "Documented key for Indian IFSC code.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "HDFC0001234"
        },
        {
          "key": "cryptoWalletAdress",
          "category": "crypto",
          "description": "Documented key for a crypto wallet address; chain may also be needed.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "<WALLET_ADDRESS>",
          "sensitivity": "financial_high"
        },
        {
          "key": "browserUserAgent",
          "category": "browser_and_3ds",
          "description": "Full browser User-Agent string.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "<USER_AGENT>",
          "sensitivity": "device_data"
        },
        {
          "key": "browserAcceptHeader",
          "category": "browser_and_3ds",
          "description": "Browser HTTP Accept header.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "text/html,application/xhtml+xml",
          "sensitivity": "device_data"
        },
        {
          "key": "browserLanguage",
          "category": "browser_and_3ds",
          "description": "Browser language.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "en-GB",
          "sensitivity": "device_data"
        },
        {
          "key": "browserJavaEnabled",
          "category": "browser_and_3ds",
          "description": "Whether Java is enabled.",
          "requiredness": "flow_specific",
          "value_type": "boolean",
          "source_url": "/api/reference#additional-fields",
          "example": true
        },
        {
          "key": "browserJavascriptEnabled",
          "category": "browser_and_3ds",
          "description": "Whether JavaScript is enabled.",
          "requiredness": "flow_specific",
          "value_type": "boolean",
          "source_url": "/api/reference#additional-fields",
          "example": true
        },
        {
          "key": "browserColorDepth",
          "category": "browser_and_3ds",
          "description": "Screen color depth in bits.",
          "requiredness": "flow_specific",
          "value_type": "integer",
          "source_url": "/api/reference#additional-fields",
          "example": 24
        },
        {
          "key": "browserScreenWidth",
          "category": "browser_and_3ds",
          "description": "Screen width in pixels.",
          "requiredness": "flow_specific",
          "value_type": "integer",
          "source_url": "/api/reference#additional-fields",
          "example": 1920
        },
        {
          "key": "browserScreenHeight",
          "category": "browser_and_3ds",
          "description": "Screen height in pixels.",
          "requiredness": "flow_specific",
          "value_type": "integer",
          "source_url": "/api/reference#additional-fields",
          "example": 1080
        },
        {
          "key": "browserTZ",
          "category": "browser_and_3ds",
          "description": "Timezone offset from UTC in minutes.",
          "requiredness": "flow_specific",
          "value_type": "integer",
          "source_url": "/api/reference#additional-fields",
          "example": -120
        },
        {
          "key": "browserChallengeWindowSize",
          "category": "browser_and_3ds",
          "description": "3DS challenge window code: 01=250x400, 02=390x400, 03=500x600.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "03",
          "enum": [
            "01",
            "02",
            "03"
          ]
        },
        {
          "key": "storeUrl",
          "category": "merchant_and_store",
          "description": "Merchant website or checkout URL.",
          "requiredness": "flow_specific",
          "value_type": "uri",
          "source_url": "/api/reference#additional-fields",
          "example": "https://merchant.example.com/"
        },
        {
          "key": "ip",
          "category": "miscellaneous",
          "description": "End-user IP address.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "203.0.113.10",
          "sensitivity": "personal_data"
        },
        {
          "key": "payeerIdentifier",
          "category": "miscellaneous",
          "description": "Payer/customer identifier on the merchant side.",
          "requiredness": "flow_specific",
          "value_type": "string_unless_flow_contract_says_otherwise",
          "source_url": "/api/reference#additional-fields",
          "example": "Merch-Customer-12345",
          "sensitivity": "personal_data"
        },
        {
          "key": "ExpectedResult",
          "category": "sandbox",
          "description": "Legacy-documented sandbox control; casing, supported outcomes and profile applicability require confirmation. Not verified by this test set.",
          "requiredness": "optional_test_only",
          "value_type": "string",
          "source_url": "/api/integration#sandbox",
          "example": "status=failed",
          "enum": [
            "status=failed",
            "status=success"
          ]
        }
      ]
    }
  },
  "reviewRevision": "2026-09-15.5"
}