Authentication Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/citi/main/json-schema/citi-authentication-request-schema.json",
  "title": "Authentication Request",
  "description": "Authentication Request",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/citi-authentication-api-openapi.yml#/components/schemas/Authentication-Request",
  "type": "object",
  "required": [
    "authentication",
    "order",
    "method",
    "transaction"
  ],
  "properties": {
    "authentication": {
      "$ref": "#/$defs/Initiate-Authentication"
    },
    "method": {
      "$ref": "#/$defs/Authentication-Method"
    },
    "transaction": {
      "$ref": "#/$defs/Authentication-Transaction"
    },
    "order": {
      "$ref": "#/$defs/Authentication-Order"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "Authentication-Card": {
      "title": "card",
      "description": "Card informations",
      "properties": {
        "number": {
          "description": "The customer’s payment card number, also known as the Primary Account Number (PAN).",
          "type": "string",
          "minLength": 9,
          "maxLength": 23,
          "title": "number"
        },
        "expiry_month": {
          "description": "Two-digit month in which the payment card expires.",
          "type": "string",
          "pattern": "^(0?[1-9]|1[0-2])$",
          "title": "expiry_month"
        },
        "expiry_year": {
          "description": "Two-digit year in which the payment card expires.",
          "type": "string",
          "pattern": "^[0-9]{2,2}$",
          "title": "expiry_year"
        },
        "device_payment": {
          "$ref": "#/$defs/Authentication-Device-Payment"
        }
      }
    },
    "Authentication-Device-Payment": {
      "title": "device",
      "type": "object",
      "description": "Device",
      "properties": {
        "eci_indicator": {
          "description": "The Electronic Commerce Indicator generated for device payments.",
          "maxLength": 2,
          "minLength": 1,
          "type": "string",
          "title": "eci_indicator"
        },
        "online_payment_cryptogram": {
          "description": "A cryptogram used to authenticate the transaction (from decrypted token).",
          "maxLength": 200,
          "minLength": 1,
          "type": "string",
          "title": "online payment cryptogram"
        },
        "cryptogram_format": {
          "description": "The format of the cryptogram provided for the digital payment.",
          "enum": [
            "3DSECURE",
            "EMV"
          ],
          "type": "string",
          "title": "cryptogram_format"
        },
        "token": {
          "description": "The payment token received from the device's payment SDK (e.g., Apple Pay).",
          "maxLength": 16384,
          "minLength": 1,
          "type": "string",
          "title": "token"
        }
      }
    },
    "Authentication-Method": {
      "type": "object",
      "title": "Authentication Method",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "description": "Method specified by the customer for the transaction  \n- Provide CARD for CARD transactions",
          "type": "string",
          "enum": [
            "CARD",
            "GOOGLEPAY",
            "APPLEPAY"
          ],
          "title": "type"
        },
        "card": {
          "$ref": "#/$defs/Authentication-Card"
        },
        "token_id": {
          "description": "Token_number.",
          "maxLength": 50,
          "minLength": 1,
          "type": "string",
          "title": "token_number"
        },
        "token_type": {
          "description": "Token type.",
          "enum": [
            "ALT_TOKEN",
            "NETWORK_TOKEN",
            "ISSUER_TOKEN",
            "CITI_TOKEN"
          ],
          "type": "string",
          "title": "token_type"
        },
        "session_id": {
          "description": "Session identification number",
          "type": "string",
          "minLength": 36,
          "maxLength": 37,
          "title": "session_id"
        }
      }
    },
    "Authentication-Order": {
      "title": "Authentication Order",
      "required": [
        "currency_code",
        "id"
      ],
      "properties": {
        "id": {
          "description": "A unique identifier for this order to distinguish it from any other order you create.",
          "maxLength": 40,
          "minLength": 1,
          "type": "string",
          "title": "id"
        },
        "currency_code": {
          "description": "The currency of the order expressed as an ISO 4217 alpha code, e.g. USD.",
          "enum": [
            "USD"
          ],
          "type": "string",
          "title": "currency_code"
        },
        "reference": {
          "description": "An optional identifier for the order For example, a shopping cart number, an order number, or an invoice number.",
          "maxLength": 250,
          "minLength": 1,
          "type": "string",
          "title": "reference"
        },
        "mcc": {
          "description": "The invoice number you issued for this order",
          "maxLength": 4,
          "minLength": 4,
          "type": "string",
          "title": "mcc"
        }
      },
      "type": "object"
    },
    "Authentication-Transaction": {
      "title": " Authentication Transaction",
      "required": [
        "id",
        "currency_code",
        "country_code"
      ],
      "properties": {
        "currency_code": {
          "description": "ISO 4217 Currency Code for instance USD/GBP/EUR \n- transaction.currency_code parameter is mandatory for all transaction type creation",
          "enum": [
            "USD"
          ],
          "type": "string",
          "title": "currency_code"
        },
        "reference": {
          "description": "Value provided by the merchant for internal tracking/referencing.",
          "maxLength": 250,
          "minLength": 1,
          "type": "string",
          "title": "reference"
        },
        "country_code": {
          "description": "The transaction country",
          "enum": [
            "US"
          ],
          "type": "string",
          "title": "country_code"
        },
        "id": {
          "description": "Unique Transaction identification provided by the merchant during  transaction creation",
          "maxLength": 128,
          "minLength": 1,
          "type": "string",
          "title": "id"
        }
      },
      "type": "object"
    },
    "Initiate-Authentication": {
      "title": " Intiate Authentication",
      "required": [
        "channel"
      ],
      "properties": {
        "channel": {
          "description": "Indicates the channel in which the authentication request is initiated.",
          "enum": [
            "MERCHANT_REQUESTED",
            "PAYER_APP",
            "PAYER_BROWSER"
          ],
          "type": "string",
          "title": "channel"
        },
        "purpose": {
          "description": "Indicates the context in which payer authentication is requested.",
          "enum": [
            "ADD_CARD",
            "AGREEMENT_CANCELLATION",
            "MAINTAIN_CARD",
            "PAYMENT_TRANSACTION",
            "REFRESH_AUTHENTICATION"
          ],
          "type": "string",
          "title": "purpose"
        },
        "type": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "A comma separated list of accepted payer authentication forms. \n- Accepted values are 3DS1,3DS2,PASSKEY",
            "title": "type"
          }
        },
        "line_of_business": {
          "description": "Identifier for different lines of business configured in the merchant profile.",
          "maxLength": 100,
          "minLength": 1,
          "type": "string",
          "title": "line_of_business"
        }
      }
    }
  }
}