Authentication Response

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/citi/main/json-schema/citi-authentication-response-schema.json",
  "title": "Authentication Response",
  "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-Response",
  "type": "object",
  "required": [
    "method",
    "transaction",
    "order",
    "authentication"
  ],
  "properties": {
    "transaction": {
      "type": "object",
      "title": "Authentication transaction response",
      "required": [
        "amount",
        "id",
        "currency_code",
        "country_code",
        "type",
        "status",
        "description"
      ],
      "properties": {
        "id": {
          "description": "Unique Transaction identification provided by the merchant during transaction creation",
          "maxLength": 128,
          "minLength": 1,
          "type": "string",
          "title": "id"
        },
        "amount": {
          "description": "Transaction amount",
          "maximum": 1000000000000000000,
          "minimum": 0.01,
          "type": "number",
          "title": "amount"
        },
        "country_code": {
          "description": "Country code",
          "enum": [
            "US"
          ],
          "type": "string",
          "title": "country_code"
        },
        "currency_code": {
          "description": "ISO 4217 Currency Code for instance  USD/GBP/EUR",
          "enum": [
            "USD"
          ],
          "type": "string",
          "title": "currency_code"
        },
        "gateway_recommendation": {
          "description": "Provides a recommendation for your next action based on the outcome of the transaction.",
          "enum": [
            "DO_NOT_PROCEED",
            "DO_NOT_PROCEED_ABANDON_ORDER",
            "PROCEED",
            "RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS"
          ],
          "type": "string",
          "title": "gateway_recommendation"
        },
        "status": {
          "type": "string",
          "maxLength": 20,
          "minLength": 1,
          "description": "Transaction Status, following status you will receive in response \n- PENDING - Transaction pending action from customer  \n- FAILED - Transaction failed for invalid payload \n- UNKNOWN - The result of the operation is unknown \n- SUCCESS - The operation was successfully processed",
          "title": "status"
        },
        "description": {
          "type": "string",
          "maxLength": 256,
          "minLength": 1,
          "description": "Transaction Status, following status you will receive in response \n- PENDING - Transaction pending action from customer  \n- FAILED - Transaction failed for invalid payload \n- UNKNOWN - The result of the operation is unknown \n- SUCCESS - The operation was successfully processed",
          "title": "description"
        },
        "creation_date_time": {
          "type": "string",
          "format": "date-time",
          "description": "GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ) \n- Instant Payment (Debit) - Date time, generated by CitiConnect API, when CitiConnect API accepted a payment initiation after validation",
          "title": "creation_date_time"
        },
        "update_time": {
          "type": "string",
          "format": "date-time",
          "description": "Indicates the date and time the gateway considers the order to have last been updated GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ)",
          "title": "update_time"
        },
        "type": {
          "description": "Indicates the type of action performed on the order.",
          "enum": [
            "AUTHENTICATION",
            "AUTHORIZATION",
            "AUTHORIZATION_UPDATE",
            "CAPTURE",
            "CHARGEBACK",
            "DISBURSEMENT",
            "FUNDING",
            "PAYMENT",
            "REFUND",
            "REFUND_REQUEST",
            "VERIFICATION",
            "VOID_AUTHORIZATION",
            "VOID_CAPTURE",
            "VOID_PAYMENT",
            "VOID_REFUND"
          ],
          "type": "string",
          "title": "type"
        },
        "reference": {
          "description": "An optional identifier for this transaction",
          "maxLength": 250,
          "minLength": 1,
          "type": "string",
          "title": "reference"
        },
        "authentication_status": {
          "description": "Indicates the result of payer authentication.",
          "enum": [
            "AUTHENTICATION_ATTEMPTED",
            "AUTHENTICATION_AVAILABLE",
            "AUTHENTICATION_EXEMPT",
            "AUTHENTICATION_FAILED",
            "AUTHENTICATION_NOT_IN_EFFECT",
            "AUTHENTICATION_NOT_SUPPORTED",
            "AUTHENTICATION_PENDING",
            "AUTHENTICATION_REJECTED",
            "AUTHENTICATION_REQUIRED",
            "AUTHENTICATION_SUCCESSFUL",
            "AUTHENTICATION_UNAVAILABLE"
          ],
          "type": "string",
          "title": "authorization_status"
        }
      }
    },
    "method": {
      "type": "object",
      "title": "Authentication Method Response",
      "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-Response"
        },
        "holder_name": {
          "$ref": "#/$defs/Holder-Name"
        },
        "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"
        }
      }
    },
    "order": {
      "type": "object",
      "title": "Authentication Order Response",
      "required": [
        "creation_date_time",
        "currency_code",
        "id",
        "update_time",
        "total_auth_amount",
        "total_captured_amount",
        "total_refunded_amount"
      ],
      "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"
        },
        "creation_date_time": {
          "type": "string",
          "format": "date-time",
          "description": "GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ)",
          "title": "creation_date_time"
        },
        "update_time": {
          "type": "string",
          "format": "date-time",
          "description": "Indicates the date and time the gateway considers the order to have last been updated GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ)",
          "title": "update_time"
        },
        "reference": {
          "description": "An optional identifier for the orderFor example, a shopping cart number, an order number, or an invoice number.",
          "maxLength": 200,
          "minLength": 1,
          "type": "string",
          "title": "reference"
        },
        "currency_code": {
          "description": "ISO 4217 Currency Code for instance  USD/GBP/EUR",
          "enum": [
            "USD"
          ],
          "type": "string",
          "title": "currency_code"
        },
        "status": {
          "type": "string",
          "maxLength": 30,
          "minLength": 1,
          "description": "Order Status, following status you will receive in response \n- AUTHENTICATED - The payer was successfully authenticated. \n- AUTHENTICATION_INITIATED - Payer authentication has been initiated but not completed. \n- AUTHENTICATION_NOT_NEEDED - Payer authentication was not performed as it was not needed. \n- AUTHENTICATION_UNSUCCESSFUL - Payer authentication was not able to be successfully completed. \n- AUTHORIZED - The payment has been authorized successfully but the authorized amount has not yet been captured, in part, full, or excess. \n- CANCELLED - The initial transaction for this order has been voided successfully. \n- CAPTURED - The authorized amount for this order, in full or excess, has been captured successfully. \n- CHARGEBACK_PROCESSED - A Chargeback has been processed against this order. \n- DISPUTED - The payment has been disputed and is under investigation. A request for information has been received or a chargeback is pending. \n- EXCESSIVELY_REFUNDED - The payment has been captured in part, full, or excess, but the captured amount in excess has been refunded successfully. \n- FAILED - The payment has not been successful. \n- FUNDING - The order transfers money to or from the merchant, without the involvement of a payer. For example, recording monthly merchant service fees from the payment service provider. \n- INITIATED - A browser payment that has successfully been initiated for this order. No payment has yet been made. \n- PARTIALLY_CAPTURED - The authorized amount for this order, in part, has been captured successfully. \n- PARTIALLY_REFUNDED - The payment has been captured in part, full, or excess, but the captured amount in part has been refunded successfully. \n- REFUNDED - The payment has been captured in part, full, or excess, but the captured amount in full has been refunded successfully. \n- REFUND_REQUESTED - A refund against captured amounts on this order has been requested but not executed. Requires further action to approve the refund. \n- VERIFIED - The card details for this order have successfully been verified. No payment has yet been initiated or made. \n- DISBURSED - The order amount has successfully been disbursed to the payer.",
          "title": "status"
        },
        "total_auth_amount": {
          "description": "The amount that has been successfully authorized for this order.",
          "maximum": 1000000000000000000,
          "minimum": 0.01,
          "type": "number",
          "title": "total_auth_amount"
        },
        "total_captured_amount": {
          "description": "The amount that has been successfully captured for this order.",
          "maximum": 1000000000000000000,
          "minimum": 0.01,
          "type": "number",
          "title": "total_captured_amount"
        },
        "total_refunded_amount": {
          "description": "The amount that has been successfully captured for this order.",
          "maximum": 1000000000000000000,
          "minimum": 0.01,
          "type": "number",
          "title": "total_refunded_amount"
        },
        "authentication_status": {
          "description": "Indicates the result of payer authentication.",
          "enum": [
            "AUTHENTICATION_ATTEMPTED",
            "AUTHENTICATION_AVAILABLE",
            "AUTHENTICATION_EXEMPT",
            "AUTHENTICATION_FAILED",
            "AUTHENTICATION_NOT_IN_EFFECT",
            "AUTHENTICATION_NOT_SUPPORTED",
            "AUTHENTICATION_PENDING",
            "AUTHENTICATION_REJECTED",
            "AUTHENTICATION_REQUIRED",
            "AUTHENTICATION_SUCCESSFUL",
            "AUTHENTICATION_UNAVAILABLE"
          ],
          "type": "string",
          "title": "authorization_status"
        }
      }
    },
    "authentication": {
      "title": " Authentication Sub Response",
      "required": [
        "channel",
        "method_completed",
        "method_supported",
        "requestor_id",
        "requestor_name",
        "accept_versions",
        "version"
      ],
      "properties": {
        "scheme": {
          "description": "The EMV 3DS authentication scheme used (e.g., MADA, MASTERCARD, VISA) for externally authenticated transactions.",
          "maxLength": 50,
          "minLength": 2,
          "type": "string",
          "title": "scheme"
        },
        "directory_server_id": {
          "description": "Unique identifier for the Directory Server (RID) for in-app authentication.",
          "maxLength": 10,
          "minLength": 10,
          "type": "string",
          "title": "directory_server_id"
        },
        "method_completed": {
          "description": "Indicates if the issuer's ACS completed the method call to obtain browser info.",
          "type": "boolean",
          "title": "method_completed"
        },
        "method_supported": {
          "description": "Indicates if the issuer's ACS supports the method call protocol.",
          "enum": [
            "NOT_SUPPORTED",
            "SUPPORTED"
          ],
          "type": "string",
          "title": "method_supported"
        },
        "protocol_version": {
          "description": "The version of the EMV 3-D Secure protocol used (e.g., 2.1.0).",
          "maxLength": 20,
          "minLength": 1,
          "type": "string",
          "title": "protocol_version"
        },
        "requestor_id": {
          "description": "The unique identifier assigned to the merchant by the card scheme directory server for 3DS2.",
          "maxLength": 20,
          "minLength": 1,
          "type": "string",
          "title": "requestor_id"
        },
        "requestor_name": {
          "description": "The unique name assigned to the merchant by the card scheme directory server for 3DS2.",
          "maxLength": 40,
          "minLength": 1,
          "type": "string",
          "title": "requestor_name"
        },
        "accept_versions": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "A comma separated list of the forms of payer authentication that you will accept.",
            "title": "accept_versions"
          }
        },
        "channel": {
          "description": "Indicates the channel in which the authentication request is initiated.",
          "enum": [
            "MERCHANT_REQUESTED",
            "PAYER_APP",
            "PAYER_BROWSER"
          ],
          "type": "string",
          "title": "channel"
        },
        "method": {
          "description": "The method that the issuer will use to authenticate the payer.",
          "enum": [
            "DYNAMIC",
            "OUT_OF_BAND",
            "STATIC"
          ],
          "type": "string",
          "title": "method"
        },
        "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"
        },
        "method_post_data": {
          "description": "Base64 URL encoded frame contents to be posted to the method URL for risk assessment.",
          "maxLength": 100,
          "minLength": 1,
          "type": "string",
          "title": "method_post_data"
        },
        "method_url": {
          "type": "string",
          "maxLength": 500,
          "minLength": 1,
          "description": "The URL provided by the issuer to which the method post data must be sent.",
          "title": "method_url"
        },
        "redirect_html": {
          "type": "string",
          "maxLength": 40960,
          "minLength": 1,
          "description": "The URL provided by the issuer to which the method post data must be sent.",
          "title": "redirect_html"
        },
        "version": {
          "description": "Indicates the available payer authentication method or NONE if unavailable.",
          "enum": [
            "3DS2",
            "RUPAY",
            "PASSKEY",
            "NONE"
          ],
          "type": "string",
          "title": "version"
        },
        "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"
        }
      }
    }
  },
  "$defs": {
    "Authentication-Card-Response": {
      "title": "Authentication Card Response",
      "description": "Card informations",
      "properties": {
        "number": {
          "description": "The customer’s payment card number, also known as the Primary Account Number (PAN).",
          "maximum": 23,
          "minimum": 9,
          "type": "string",
          "title": "number"
        },
        "issuer": {
          "description": "The issuer of the card, if known.",
          "maximum": 255,
          "minimum": 1,
          "type": "string",
          "title": "issuer"
        },
        "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"
        },
        "encryption": {
          "description": "The encryption framework used for the payment details received by the gateway.",
          "enum": [
            "DEVICE",
            "DIGITAL_WALLET",
            "DUKPT"
          ],
          "type": "string",
          "title": "encryption"
        },
        "funding_method": {
          "description": "The method used by the payer to provide the funds (Charge, Credit, Debit).",
          "enum": [
            "CHARGE",
            "CREDIT",
            "DEBIT",
            "UNKNOWN"
          ],
          "type": "string",
          "title": "funding_method"
        },
        "brand": {
          "description": "The brand name used to describe the card that is recognized and accepted globally. For many major card types this will match the scheme name. In some markets, a card may also be co-branded with a local brand that is recognized and accepted within its country/region of origin (see card.localBrand).You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.",
          "enum": [
            "AMEX",
            "CHINA_UNIONPA",
            "DINERS_CLUB",
            "DISCOVER",
            "JCB",
            "LOCAL_BRAND_ONLY",
            "MAESTRO",
            "MASTERCARD",
            "RUPAY",
            "UATP",
            "UNKNOWN",
            "VISA"
          ],
          "type": "string",
          "title": "brand"
        },
        "scheme": {
          "description": "The organization that owns a card brand and defines operating regulations for its use. The card scheme also controls authorization and settlement of card transactions among issuers and acquirers.",
          "enum": [
            "AMEX",
            "CHINA_UNIONPA",
            "DINERS_CLUB",
            "DISCOVER",
            "JCB",
            "LOCAL_BRAND_ONLY",
            "MAESTRO",
            "MASTERCARD",
            "RUPAY",
            "UATP",
            "UNKNOWN",
            "VISA"
          ],
          "type": "string",
          "title": "scheme"
        },
        "device_payment": {
          "$ref": "#/$defs/Authentication-Device-Payment-Response"
        },
        "device_specific": {
          "$ref": "#/$defs/Device-Specific-Response"
        }
      }
    },
    "Authentication-Device-Payment-Response": {
      "title": "Authentication Device Payment Response",
      "type": "object",
      "description": "Device",
      "properties": {
        "cryptogram_format": {
          "description": "The format of the cryptogram provided for the digital payment.",
          "enum": [
            "3DSECURE",
            "EMV"
          ],
          "type": "string",
          "title": "cryptogram_format"
        }
      }
    },
    "Device-Specific-Response": {
      "title": "Device",
      "description": "Device Specific Response",
      "properties": {
        "number": {
          "description": "The payer's account number associated with a digital payment method.",
          "maximum": 19,
          "minimum": 9,
          "type": "number",
          "title": "number"
        },
        "expiry_month": {
          "description": "Two-digit month in which the device specific expires.",
          "type": "string",
          "pattern": "^(0?[1-9]|1[0-2])$",
          "title": "expiry_month"
        },
        "expiry_year": {
          "description": "Year from the expiry date of the device specific account number.",
          "type": "string",
          "pattern": "^[0-9]{2,2}$",
          "title": "expiry_year"
        }
      }
    },
    "Holder-Name": {
      "title": "Holder-Name",
      "description": "The name of the bank account holder for the payer's bank account.",
      "properties": {
        "first_name": {
          "description": "first_name. \n - For ACH Pay and verify transaction method.holder.first_name parameter is mandatory \n - For India Card transactions, method.holder.first_name parameter is mandatory",
          "maxLength": 50,
          "minLength": 1,
          "type": "string",
          "title": "first_name"
        },
        "last_name": {
          "description": "last_name. \n - For ACH Pay and verify transaction method.holder.last_name parameter is mandatory \n - For India Card transactions, method.holder.last_name parameter is mandatory",
          "maxLength": 50,
          "minLength": 1,
          "type": "string",
          "title": "last_name"
        }
      }
    }
  }
}