PixPaymentV3

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/clarafintech/main/json-schema/clarafintech-pix-payment-v3-schema.json",
  "title": "PixPaymentV3",
  "x-generated": "2026-10-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/clarafintech-openapi.json#/components/schemas/PixPaymentV3",
  "type": "object",
  "properties": {
    "externalId": {
      "type": "string",
      "format": "uuid",
      "description": "Customer-supplied payment identifier, unique within the company."
    },
    "status": {
      "type": "string",
      "enum": [
        "IN_PROCESS",
        "SCHEDULED",
        "PAID",
        "FAILED",
        "CANCELLED"
      ],
      "description": "PAID, FAILED, and CANCELLED are terminal. A payment reaches a terminal status within 3 hours at worst. A refunded payment remains PAID."
    },
    "amount": {
      "type": [
        "number",
        "null"
      ],
      "format": "decimal",
      "description": "Null while an amount-less QR is being resolved."
    },
    "currencyCode": {
      "type": "string",
      "enum": [
        "BRL"
      ]
    },
    "paymentMethod": {
      "type": "string",
      "enum": [
        "PIX"
      ]
    },
    "description": {
      "type": "string"
    },
    "beneficiary": {
      "$ref": "#/$defs/PixBeneficiaryV3"
    },
    "pixEndToEndId": {
      "type": "string",
      "description": "Pix end-to-end identifier, available once the payment has settled."
    },
    "error": {
      "$ref": "#/$defs/PixPaymentErrorV3"
    },
    "creationDate": {
      "type": "string",
      "format": "date-time"
    },
    "paymentDate": {
      "type": "string",
      "format": "date",
      "description": "Settlement date. Filterable through paidFrom/paidTo but not sortable."
    }
  },
  "$defs": {
    "PixBeneficiaryV3": {
      "type": "object",
      "description": "Beneficiary as resolved by payment execution. Null until the destination is resolved.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Beneficiary name."
        },
        "documentNumber": {
          "type": "string",
          "description": "Beneficiary CPF or CNPJ, digits only."
        },
        "bank": {
          "type": "string",
          "description": "Beneficiary institution ISPB or bank code."
        },
        "bankName": {
          "type": "string",
          "description": "Beneficiary institution name."
        },
        "accountType": {
          "type": "string",
          "description": "ISO 20022 account type: CACC (checking/current), SVGS (savings), TRAN (payment account), SLRY (salary).",
          "enum": [
            "CACC",
            "SVGS",
            "TRAN",
            "SLRY"
          ]
        },
        "accountNumber": {
          "type": "string",
          "description": "Beneficiary account number."
        },
        "branch": {
          "type": "string",
          "description": "Beneficiary branch number."
        }
      }
    },
    "PixPaymentErrorV3": {
      "type": "object",
      "description": "Failure detail of a FAILED payment. Integrate against code; message is informational, may be reworded without a version change, and is English-only at launch.",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "AMOUNT_REQUIRED",
            "AMOUNT_MISMATCH",
            "BENEFICIARY_MISMATCH",
            "QR_INVALID",
            "QR_EXPIRED",
            "QR_NOT_FOUND",
            "PIX_KEY_INVALID",
            "PIX_KEY_NOT_FOUND",
            "BENEFICIARY_ACCOUNT_ERROR",
            "PAYMENT_DATA_INVALID",
            "INSUFFICIENT_FUNDS",
            "LIMIT_EXCEEDED",
            "PAYMENT_NOT_ALLOWED",
            "PAYMENT_REJECTED",
            "SETTLEMENT_FAILED",
            "PROVIDER_UNAVAILABLE",
            "NOT_SCHEDULABLE",
            "SCHEDULE_DATE_INVALID",
            "SCHEDULE_FAILED",
            "PROCESSING_TIMEOUT",
            "PAYMENT_FAILED"
          ]
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}