PaymentRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/citi/main/json-schema/citi-payment-request-schema.json",
  "title": "PaymentRequest",
  "description": "Payment Request",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/citi-digitalpayments-api-openapi.yml#/components/schemas/PaymentRequest",
  "type": "object",
  "required": [
    "customer",
    "merchant",
    "method",
    "transaction"
  ],
  "properties": {
    "customer": {
      "$ref": "#/$defs/Customer"
    },
    "merchant": {
      "$ref": "#/$defs/Merchant"
    },
    "method": {
      "$ref": "#/$defs/Method"
    },
    "transaction": {
      "$ref": "#/$defs/Transaction"
    },
    "shipping": {
      "$ref": "#/$defs/Shipping"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "AdditionalInfo": {
      "properties": {
        "name": {
          "maxLength": 50,
          "minLength": 1,
          "type": "string",
          "description": "Specifies a character string with a maximum length of 50 characters. \n- For Brazil QR transaction.additionalinfo.name is optional, if the `transaction.additionalinfo.name` parameter is provided by the merchant, then the `transaction.additionalinfo.value` parameter is mandatory."
        },
        "value": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string",
          "description": "Specifies a character string with a maximum length of 200 characters. \n- For Brazil QR transaction.the `additionalinfo.value` parameter is optional, if the `transaction.additionalinfo.value` parameter is provided by merchant, then the `transaction.additionalinfo.name` parameter is mandatory."
        }
      }
    },
    "Address": {
      "description": "\n- For Brazil QR transaction `shipping.address` details is not applicable",
      "required": [
        "country_code"
      ],
      "properties": {
        "line1": {
          "maxLength": 40,
          "minLength": 1,
          "type": "string",
          "description": "Customer line1 address"
        },
        "line2": {
          "maxLength": 40,
          "minLength": 1,
          "type": "string",
          "description": "Customer line2 address."
        },
        "city": {
          "maxLength": 30,
          "minLength": 1,
          "type": "string",
          "description": "Customer city"
        },
        "postal_code": {
          "maxLength": 16,
          "minLength": 1,
          "type": "string",
          "description": "Customer postal code."
        },
        "state": {
          "maxLength": 30,
          "minLength": 1,
          "type": "string",
          "description": "Customer state."
        },
        "country_code": {
          "type": "string",
          "enum": [
            "BR"
          ],
          "description": "Customer country."
        }
      }
    },
    "Customer": {
      "properties": {
        "id": {
          "maxLength": 40,
          "minLength": 1,
          "type": "string",
          "description": "Merchant internal customer ID."
        },
        "type": {
          "type": "string",
          "enum": [
            "INDIVIDUAL",
            "BUSINESS"
          ],
          "description": "Merchant customer type \n - For Brazil QR creation `customer.type` parameter is mandatory"
        },
        "payer_id": {
          "maxLength": 128,
          "minLength": 1,
          "type": "string",
          "description": "Customer's payer identification (e.g., email address) \n - For Brazil QR creation, the `customer.payer_id` parameter is mandatory and only a numeric value is allowed, individual person tax identification (CPF) allowed length = 11  or business entity tax identification (CNPJ) allowed length = 14"
        },
        "payer_type": {
          "type": "string",
          "enum": [
            "BIID",
            "EMAL",
            "EWAL",
            "MBNO",
            "NIDN"
          ],
          "description": "Customer's payer type (BIID for bill identification, EMAL for email address, EWAL for electronic wallet identification, MBNO for mobile number and NIDN for national identification or tax identification \n - For Brazil QR creation `customer.payer_type` parameter is mandatory, applicable value NIDN"
        },
        "name": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string",
          "description": " Payer name \n - For Brazil QR creation customer.name parameter is mandatory and allowed datatype alphanumeric, individual person or business entity name."
        },
        "address": {
          "$ref": "#/$defs/Address"
        }
      }
    },
    "Merchant": {
      "type": "object",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "maxLength": 40,
          "minLength": 1,
          "type": "string",
          "description": "Merchant ID assigned by Citi."
        },
        "payee_id": {
          "maxLength": 128,
          "minLength": 1,
          "type": "string",
          "description": "Merchant's payee identification (e.g., email address) \n - For Brazil QR creation, `merchant.payee_id` parameter is mandatory, allowed maxlength is 77."
        },
        "payee_type": {
          "type": "string",
          "enum": [
            "BIID",
            "EMAL",
            "EWAL",
            "MBNO",
            "NIDN"
          ],
          "description": "Merchant's payee type (BIID for bill identification, EMAL for email address, EWAL for electronic wallet identification, MBNO for mobile number and NIDN for national identification or tax identification \n - For Brazil QR creation `merchant.payee_type` parameter is mandatory"
        }
      },
      "additionalProperties": false
    },
    "Method": {
      "type": "object",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "description": "Method specified by the customer for the transaction \n- Provide PIX for Brazil QR creation",
          "type": "string",
          "enum": [
            "PIX"
          ]
        }
      }
    },
    "Shipping": {
      "type": "object",
      "properties": {
        "name": {
          "maxLength": 100,
          "minLength": 1,
          "type": "string",
          "description": "Recipient name \n- For Brazil QR, the `shipping.name` is not applicable."
        },
        "phone": {
          "maxLength": 10,
          "minLength": 1,
          "type": "number",
          "description": "Recepient phone \n- For Brazil QR, the `shipping.phone` is not applicable."
        },
        "carrier": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string",
          "description": "Service that shipped a physical product \n- For Brazil QR, the `shipping.carrier` is not applicable."
        },
        "tracking_number": {
          "maxLength": 40,
          "minLength": 8,
          "type": "string",
          "description": "Tracking number. \n- For Brazil QR, the `shipping.tracking_number` is not applicable."
        },
        "address": {
          "$ref": "#/$defs/Address"
        }
      }
    },
    "Transaction": {
      "type": "object",
      "required": [
        "reference",
        "amount",
        "currency_code"
      ],
      "properties": {
        "reference": {
          "maxLength": 128,
          "minLength": 1,
          "type": "string",
          "description": "Unique transaction identification provided by the merchant during transaction creation \n- transaction.reference parameter is mandatory for all transaction type creation   \n- For Brazil QR creation `transaction.reference` parameter should be of length between 26 to 35 and allowed datatype is alphanumeric and should not be filled with spaces or zeroes"
        },
        "order_id": {
          "maxLength": 128,
          "minLength": 1,
          "type": "string",
          "description": "Unique order identification provided by the merchant during transaction creation."
        },
        "expiry_time": {
          "type": "integer",
          "format": "int32",
          "minimum": 10,
          "description": "Expiration time for QR collection, specified in seconds \n- QR Creation request will be rejected, if the expiration time value is less than 10."
        },
        "amount": {
          "type": "number",
          "minimum": 0.01,
          "maximum": 100000000000000,
          "description": "Transaction amount \n - For Brazil QR creation decimal values are mandatory for transaction.amount and it must have 2 digits \n - For Brazil QR creation maximum amount limit is 9999999999.99"
        },
        "currency_code": {
          "type": "string",
          "enum": [
            "BRL"
          ],
          "description": "ISO 4217 Currency Code for instance  USD/GBP/EUR \n- transaction.currency_code parameter is mandatory for all transaction type creation"
        },
        "update_flag": {
          "type": "string",
          "enum": [
            "Y",
            "N"
          ],
          "description": "For QR Creation (e.g., Brazil), during transaction processing if the merchant wants to allow their clients to change QR amount then the value should be Y otherwise, the default value is 'N'."
        },
        "qr_image": {
          "type": "string",
          "enum": [
            "Y",
            "N"
          ],
          "description": "Merchant to confirm QR Image is required or not, If required, the value should be 'Y'."
        },
        "additional_info": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AdditionalInfo"
          }
        }
      }
    }
  }
}