PaymentRefundNotification

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/citi/main/json-schema/citi-payment-refund-notification-schema.json",
  "title": "PaymentRefundNotification",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/citi-digitalpayments-api-openapi.yml#/components/schemas/PaymentRefundNotification",
  "type": "object",
  "properties": {
    "end_to_end_id": {
      "$ref": "#/$defs/RestrictedFINXMax128Text"
    },
    "refund_id": {
      "type": "string",
      "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$",
      "description": "UUID v4 format unique end-to-end transaction reference"
    },
    "creation_date_time": {
      "type": "string",
      "format": "date-time",
      "description": "GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ)- Instant Payment (Debit) - Date time, generated by the CitiConnect API, when the CitiConnect API accepted a payment initiation after validation \n- Instant payment (credit) - date and time, either provided by the debtor bank or generated by Citi's transaction processing application, when a transaction was created."
    },
    "value_date": {
      "type": "string",
      "format": "date",
      "description": "Date in local time zone (e.g., EST for a United States RTP network transaction) when Citi's transaction processing application starts processing a transaction. \n- Format YYYY-MM-DD"
    },
    "instructed_amount": {
      "type": "number",
      "minimum": 0.01,
      "maximum": 100000000000000,
      "description": "Instructed amount can be either full original transaction amount or a partial amount \n - Thailand PromptPay - Maximum amount is 2000000.00 \n - United States - Maximum amount is 1000000.00"
    },
    "instructed_currency": {
      "description": "ISO 4217 code for the transaction instructed amount currency.",
      "type": "string",
      "enum": [
        "BRL"
      ]
    },
    "additional_info": {
      "type": "string",
      "maxLength": 140,
      "description": "Additional or remittance information  \n- For Brazil, the `refunds.additional_info` parameter is optional."
    },
    "status": {
      "$ref": "#/$defs/RefundStatus"
    },
    "reasons": {
      "$ref": "#/$defs/Reasons"
    },
    "original_payment": {
      "$ref": "#/$defs/Original_Payment_Status"
    }
  },
  "$defs": {
    "Original_Payment_Status": {
      "type": "object",
      "description": "Either populate UETR OR (`end_to_end_id` AND `value_date`) for the refund to be processed.",
      "properties": {
        "end_to_end_id": {
          "$ref": "#/$defs/RestrictedFINXMax128Text"
        },
        "uetr": {
          "type": "string",
          "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$",
          "description": "UUID v4 format unique end-to-end transaction reference."
        },
        "value_date": {
          "type": "string",
          "format": "date",
          "description": "Format YYYY-MM-DD Date in local time zone (e.g., EST for a United States RTP network transaction) when Citi's transaction processing application starts processing a transaction."
        },
        "instructed_amount": {
          "type": "number",
          "minimum": 0.01,
          "maximum": 100000000000000,
          "description": "Instructed amount \n - Thailand PromptPay - Maximum amount is 2000000.00 \n - United States - Maximum amount is 1000000.00"
        },
        "instructed_currency": {
          "description": "ISO 4217 code for the transaction instructed amount currency.",
          "type": "string",
          "enum": [
            "BRL"
          ]
        }
      }
    },
    "Reason": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Reason codes (e.g., AM03, AM02, AC02, CH03, CH04, CH20, CH21, BE23, NARR, etc.)"
        },
        "description": {
          "type": "string",
          "description": "Reason code description (e.g., \n- AM03 -Method instructed currency is invalid (not in ISO 4217 format or value) \n- AM02 -Instructed amount is not ≥ 0.01 & ≤ 2,000,000.00.\n- AC02 -Debtor account is invalid \n- CH03 -Value date is in the future \n- CH04 -Value date is in the past \n- CH20 -Value-added tax (VAT) amount format is invalid \n- CH21 -Bill identification 1 is mandatory for a bill payment,Bill identification 2 and 3 are conditional for a bill payment \n- BE23 -Creditor mobile number (proxy identification) format is invalid \n- NARR -Creditor name maximum length is 50 )"
        }
      }
    },
    "Reasons": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Reason"
      }
    },
    "RefundStatus": {
      "type": "object",
      "required": [
        "date_time",
        "code",
        "description"
      ],
      "properties": {
        "date_time": {
          "type": "string",
          "format": "date-time",
          "description": "GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ) \n- Date time of transaction status"
        },
        "code": {
          "type": "string",
          "description": "ISO 20022 transaction status code.",
          "enum": [
            "ACCC",
            "ACTC",
            "RJCT"
          ]
        },
        "description": {
          "type": "string",
          "description": "Status code description \n- ACTC - Accepted \n- ACCC - Completed \n- RJCT - Rejected"
        },
        "type": {
          "type": "string",
          "description": "Refund Status \\n P - Partial Refund \\n F  - Full Refund",
          "enum": [
            "P",
            "F"
          ]
        }
      }
    },
    "RestrictedFINXMax128Text": {
      "maxLength": 35,
      "minLength": 1,
      "pattern": "^(?!\\s*$).+",
      "type": "string",
      "description": "Specifies a character string with a maximum length of 35 characters limited to character set X, that is, a-z A-Z / - ? : ( ) . , ‘ + . \n - For Brazil `end_to_end_id` parameter is mandatory and allowed max length is 35"
    }
  }
}