Citi Authorization API

openapi: 3.2.0
info:
  title: Dual Auth Authorization API
  description: 'The **Dual Auth Authorization API** enables real-time authorization of card

    transactions by forwarding ISO 8583-based authorization requests to the

    appropriate downstream systems.'
  version: 2.0.0
servers:
- url: https://prod.api.placeholder.com/dual-auth
  description: Production environment — placeholder URL. Actual base URL to be confirmed with the API provider.
- url: https://sandbox.api.placeholder.com/dual-auth
  description: Sandbox environment — placeholder URL. Actual base URL to be confirmed with the API provider.
security:
- mutualTLS: []
tags:
- name: Authorization
  description: Dual Auth Authorization Request and Response
paths:
  /api/authorization:
    post:
      tags:
      - Authorization
      summary: Submit a card authorization request
      description: 'Submits a real-time card authorization request. The request payload follows ISO 8583 field conventions and supports both Visa and Mastercard transaction types.

        **Note:** Visa-specific fields (prefixed `VisaF`) and Mastercard-specific fields (prefixed `MCF`) are mutually exclusive. Include only the fields relevant to the card network of the transaction.

        **HTTP Response:** This API returns HTTP `200` for all processed requests. The outcome of the authorization is indicated by the `respCode` field in the response body (e.g., `00` for Approved, `05` for Declined). No other HTTP response codes are defined by the provider.'
      parameters:
      - name: EASDualAuth-endpoint
        in: header
        description: The actual client endpoint URL to which the authorization request will be routed. This header is used for internal routing purposes only and is **not** forwarded to the external endpoint.
        required: true
        schema:
          type: string
          example: https://client-endpoint.example.com/auth
      requestBody:
        description: Authorization Request Body
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/authorizationRequest'
            examples:
              mastercard_standard_purchase:
                summary: Standard Mastercard Purchase (Production Sample)
                description: A standard card-present Mastercard purchase transaction originating from Singapore.
                value:
                  MessageTypeID: '0100'
                  PrimaryAccountNumber: '5529244000020003000'
                  ProcessingCode: '000000'
                  TransactionAmount: '15.06'
                  BillingAmount: '23.53'
                  TransmissionDateAndTime: '1107083315'
                  SystemTraceAuditNumber: 005619
                  LocalTransactionTime: '223315'
                  LocalTransactionDate: '1106'
                  CardExpiryDate: '2912'
                  MCCMerchantType: '5999'
                  AcquirerCountryCode: '702'
                  POSEntryMode: '812'
                  POSConditionCode: ''
                  AcquirerInstitutionID: '000004'
                  RetrievalReferenceNumber: '331108005619'
                  CardAcceptorTerminalID: '03461004'
                  CardAcceptorIDCode: '543457031007388'
                  CardAcceptorNameLocation: 'CITIONLINE SINGAPORE SG                 '
                  CurrencyCodeTransaction: '702'
                  CurrencyCodeBilling: '702'
                  MCF61POSTermAtt: '0'
                  MCF61POSCHPresence: '0'
                  MCF61POSCdPresence: '0'
                  MCF61POSTranStatus: '0'
                  MCF61POSTranSec: '0'
                  MCF61POSChActTermLvl: '6'
                  MCF61POSCountryCode: '702'
      responses:
        '200':
          description: 'The only HTTP response code returned by this API. All authorization requests that are successfully processed — whether approved or declined — will return HTTP 200. The `respCode` field in the response body indicates the actual authorization outcome.

            > ℹ️ **Note:** A declined transaction (e.g., `respCode: "05"`) is > still returned as HTTP 200. HTTP status codes do **not** reflect > the card authorization decision.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authorizationResponse'
              examples:
                approved:
                  summary: Approved Transaction
                  description: The authorization was approved by the issuer.
                  value:
                    respCode: '00'
                declined:
                  summary: Declined Transaction
                  description: The authorization was declined by the issuer (e.g., do not honor). Note this is still returned as HTTP 200.
                  value:
                    respCode: '05'
      x-codegen-request-body-name: request-body
      operationId: postApiAuthorization
      x-operation-id-source: derived
components:
  schemas:
    authorizationRequest:
      type: object
      required:
      - MessageTypeID
      - PrimaryAccountNumber
      - ProcessingCode
      - TransactionAmount
      - BillingAmount
      - TransmissionDateAndTime
      - SystemTraceAuditNumber
      - LocalTransactionTime
      - LocalTransactionDate
      - CardExpiryDate
      - MCCMerchantType
      - AcquirerCountryCode
      - POSEntryMode
      - POSConditionCode
      - AcquirerInstitutionID
      - RetrievalReferenceNumber
      - CardAcceptorTerminalID
      - CardAcceptorIDCode
      - CardAcceptorNameLocation
      - CurrencyCodeTransaction
      - CurrencyCodeBilling
      properties:
        MessageTypeID:
          type: string
          minLength: 4
          maxLength: 4
          description: 'ISO 8583 Message Type Identifier. Defines the purpose of the message in the transaction lifecycle.

            | Value | Meaning | |-------|---------| | `0100` | Authorization Request | | `0120` | Authorization Advice | | `0400` | Reversal Request | | `0420` | Reversal Advice |'
          enum:
          - '0100'
          - '0120'
          - '0400'
          - '0420'
          example: '0100'
        PrimaryAccountNumber:
          type: string
          minLength: 19
          maxLength: 19
          description: The cardholder's Primary Account Number (PAN) — the real card number. This is a sensitive field and must be handled in accordance with PCI-DSS requirements.
          example: '5529244000020003000'
        ProcessingCode:
          type: string
          minLength: 6
          maxLength: 6
          description: A 6-digit code that describes the type of transaction being performed and the accounts affected. `000000` represents a standard purchase transaction.
          example: '000000'
        TransactionAmount:
          type: string
          minLength: 1
          maxLength: 13
          description: The transaction amount in the currency of the acquirer (`CurrencyCodeTransaction`). Expressed as a decimal string (e.g., `"15.06"` for $15.06).
          example: '15.06'
        BillingAmount:
          type: string
          minLength: 1
          maxLength: 13
          description: The amount billed to the cardholder in the cardholder's billing currency (`CurrencyCodeBilling`). May differ from `TransactionAmount` when a currency conversion is applied.
          example: '23.53'
        TransmissionDateAndTime:
          type: string
          minLength: 10
          maxLength: 10
          description: The date and time the message was transmitted, in `MMDDHHmmSS` format (Month, Day, Hour, Minute, Second).
          example: '1107083315'
        SystemTraceAuditNumber:
          type: string
          minLength: 6
          maxLength: 6
          description: A unique 6-digit number assigned by the message initiator to identify a specific cardholder transaction. Used to correlate all message types (auth, advice, reversal) that belong to the same transaction.
          example: 005619
        LocalTransactionTime:
          type: string
          minLength: 6
          maxLength: 6
          description: The local time at the point of transaction, in `HHmmSS` format (Hour, Minute, Second).
          example: '223315'
        LocalTransactionDate:
          type: string
          minLength: 4
          maxLength: 4
          description: The local date at the point of transaction, in `MMDD` format (Month, Day).
          example: '1106'
        CardExpiryDate:
          type: string
          minLength: 4
          maxLength: 4
          description: The card's expiration date in `YYMM` format (Year, Month).
          example: '2912'
        MCCMerchantType:
          type: string
          minLength: 4
          maxLength: 4
          description: The Merchant Category Code (MCC) — a 4-digit code classifying the type of business the merchant operates. Defined by Visa/Mastercard specifications.
          example: '5999'
        AcquirerCountryCode:
          type: string
          minLength: 3
          maxLength: 3
          description: The ISO 3166-1 numeric country code of the country where the acquiring institution is located (e.g., `702` for Singapore, `840` for USA).
          example: '702'
        POSEntryMode:
          type: string
          minLength: 3
          maxLength: 4
          description: Indicates the method used to capture the PAN and the PIN entry capability of the terminal. Composed of a PAN entry mode code and a PIN capability code.
          example: '812'
        POSConditionCode:
          type: string
          minLength: 0
          maxLength: 2
          description: '**(Visa only)** A code identifying the transaction conditions at the point-of-sale. For Mastercard transactions, refer to the `MCF61` fields instead. May be empty for non-Visa transactions.'
          example: ''
        AcquirerInstitutionID:
          type: string
          minLength: 6
          maxLength: 11
          description: Identifies the acquiring institution (e.g., the merchant's bank) or its agent. Also known as the Bank Identification Number (BIN) of the acquirer.
          example: '000004'
        RetrievalReferenceNumber:
          type: string
          minLength: 12
          maxLength: 12
          description: A 12-character reference number supplied by the acquiring system. Used to locate the original source document of the transaction and to correlate related messages (e.g., reversals).
          example: '331108005619'
        CardAcceptorTerminalID:
          type: string
          minLength: 8
          maxLength: 8
          description: An 8-character identifier for the specific terminal at the card acceptor's location (e.g., a POS terminal ID).
          example: '03461004'
        CardAcceptorIDCode:
          type: string
          minLength: 15
          maxLength: 15
          description: The Merchant ID (MID) — a 15-character code that uniquely identifies the merchant in the transaction.
          example: '543457031007388'
        CardAcceptorNameLocation:
          type: string
          minLength: 40
          maxLength: 40
          description: The name and location of the card acceptor (merchant), padded to 40 characters. Typically formatted as `<MERCHANT NAME> <CITY> <COUNTRY CODE>`.
          example: 'CITIONLINE SINGAPORE SG                 '
        CurrencyCodeTransaction:
          type: string
          minLength: 3
          maxLength: 3
          description: The ISO 4217 numeric currency code for the transaction currency — the local currency at the point of sale (e.g., `702` for SGD, `840` for USD).
          example: '702'
        CurrencyCodeBilling:
          type: string
          minLength: 3
          maxLength: 3
          description: The ISO 4217 numeric currency code used to bill the cardholder's account. May differ from `CurrencyCodeTransaction` when a currency conversion is applied.
          example: '702'
        VisaF60TermEntCapab:
          type: string
          minLength: 1
          maxLength: 1
          description: '**(Visa only)** Terminal Entry Capability — identifies the terminal''s ability to electronically read account numbers and expiration dates from cards.'
          example: '1'
        VisaF60ChipCondCode:
          type: string
          minLength: 1
          maxLength: 1
          description: '**(Visa only)** Chip Condition Code — provides information about fallback transactions initiated from the magnetic stripe of a VSDC card at a VSDC terminal.'
          example: '0'
        VisaF60SpclCondIndic:
          type: string
          minLength: 1
          maxLength: 1
          description: '**(Visa only)** Special Condition Indicator — describes selected special conditions at the point-of-sale.'
          example: '2'
        VisaF60ChipTxnIndic:
          type: string
          minLength: 1
          maxLength: 1
          description: '**(Visa only)** Chip Transaction Indicator — set by full VSDC data acquirers when the terminal indicates a chip-based transaction.'
          example: '1'
        VisaF60MoToECIndic:
          type: string
          minLength: 2
          maxLength: 2
          description: '**(Visa only)** Mail Order / Telephone Order / E-Commerce Indicator. For MOTO transactions (field 25 = `08`), identifies the order type. For e-commerce transactions (field 25 = `59`), identifies the security level used.'
          example: '05'
        VisaF123VirtualCardNbr:
          type: string
          minLength: 19
          maxLength: 19
          description: '**(Visa only)** The Visa Virtual Card Number (token). Present when the transaction is initiated using a tokenized card (e.g., via a digital wallet).'
          example: '5566801000000113'
        VisaF123WalletSPId:
          type: string
          minLength: 11
          maxLength: 11
          description: '**(Visa only)** Token Requestor ID / Wallet Service Provider ID. Identifies the digital wallet or token requestor that initiated the transaction.'
          example: '43158104465'
        VisaF126RecurTxnIndic:
          type: string
          minLength: 1
          maxLength: 1
          description: '**(Visa only)** Recurring Transaction Indicator. A value of `R` identifies this as a recurring transaction (e.g., a subscription).'
          enum:
          - R
          example: R
        MCF48VirtualCardNbr:
          type: string
          minLength: 19
          maxLength: 19
          description: '**(Mastercard only)** The Mastercard Virtual Card Number (token). Present when the transaction is initiated using a tokenized card (e.g., via a digital wallet).'
          example: '5566801000000113'
        MCF48WalletSPId:
          type: string
          minLength: 11
          maxLength: 11
          description: '**(Mastercard only)** Token / Wallet Service Provider ID. Identifies the digital wallet or token requestor that initiated the transaction.'
          example: '43158104465'
        MCF61POSTermAtt:
          type: string
          minLength: 1
          maxLength: 1
          description: '**(Mastercard only)** POS Terminal Attendance — indicates whether the card acceptor is attending the terminal at the time of the transaction.'
          example: '0'
        MCF61POSCHPresence:
          type: string
          minLength: 1
          maxLength: 1
          description: '**(Mastercard only)** POS Cardholder Presence — indicates whether the cardholder is physically present at the point of service. A value of `4` indicates a recurring transaction.'
          example: '0'
        MCF61POSCdPresence:
          type: string
          minLength: 1
          maxLength: 1
          description: '**(Mastercard only)** POS Card Presence — indicates whether the physical card is present at the point of service.'
          example: '0'
        MCF61POSTranStatus:
          type: string
          minLength: 1
          maxLength: 1
          description: '**(Mastercard only)** POS Transaction Status — indicates the purpose or current status of the authorization request.'
          example: '0'
        MCF61POSTranSec:
          type: string
          minLength: 1
          maxLength: 1
          description: '**(Mastercard only)** POS Transaction Security — indicates the card acceptor''s confidence level in the security of the transaction.'
          example: '0'
        MCF61POSChActTermLvl:
          type: string
          minLength: 1
          maxLength: 1
          description: '**(Mastercard only)** Cardholder-Activated Terminal Level — indicates the type of cardholder-activated terminal used to initiate the transaction (e.g., ATM, kiosk).'
          example: '6'
        MCF61POSCountryCode:
          type: string
          minLength: 3
          maxLength: 3
          description: '**(Mastercard only)** POS Country Code — the ISO 3166-1 numeric country code of the POS location (not the acquirer location).'
          example: '702'
    authorizationResponse:
      type: object
      required:
      - respCode
      properties:
        respCode:
          type: string
          minLength: 2
          maxLength: 2
          description: 'ISO 8583 Response Code indicating the outcome of the authorization request. This API always returns HTTP 200 — the `respCode` field is the authoritative indicator of whether the transaction was approved or declined. Refer to Visa/Mastercard specifications for the full list of values.

            | Code | Meaning | |------|---------| | `00` | Approved | | `05` | Do Not Honor (Declined) |'
          example: '00'
  securitySchemes:
    mutualTLS:
      type: http
      scheme: mutual-tls
      description: Mutual TLS (mTLS) authentication. Both root and intermediary certificates must be exchanged with the API provider as part of the formal onboarding process before any API calls can be made.