CreatePixPaymentRequestV3

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/clarafintech/main/json-schema/clarafintech-create-pix-payment-request-v3-schema.json",
  "title": "CreatePixPaymentRequestV3",
  "x-generated": "2026-10-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/clarafintech-openapi.json#/components/schemas/CreatePixPaymentRequestV3",
  "type": "object",
  "required": [
    "externalId",
    "paymentMethod"
  ],
  "properties": {
    "externalId": {
      "type": "string",
      "format": "uuid",
      "description": "Customer-generated payment identifier and company-scoped idempotency key. Re-sending the same value answers 202 without creating a second payment."
    },
    "amount": {
      "type": "number",
      "format": "decimal",
      "description": "Amount in BRL, greater than zero, at most 2 decimals. Required for Pix-key and bank-details payments; optional for a QR payment whose QR defines the amount."
    },
    "description": {
      "type": "string",
      "maxLength": 140,
      "description": "Free-text description of the payment."
    },
    "paymentMethod": {
      "$ref": "#/$defs/PixPaymentMethodV3"
    },
    "beneficiary": {
      "$ref": "#/$defs/PixBeneficiaryRequestV3"
    }
  },
  "$defs": {
    "PixBeneficiaryRequestV3": {
      "type": "object",
      "description": "Beneficiary. Optional owner assertion for a Pix-key or QR payment, where only documentNumber is evaluated; required in full for a bank-details payment, where it is the destination.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Beneficiary name. Required for a bank-details payment."
        },
        "documentNumber": {
          "type": "string",
          "description": "Beneficiary CPF or CNPJ, digits only. Optional owner assertion for a Pix-key or QR payment; required for a bank-details payment."
        },
        "bank": {
          "type": "string",
          "description": "Beneficiary institution ISPB or bank code. Required for a bank-details payment."
        },
        "bankName": {
          "type": "string",
          "description": "Beneficiary institution name. Required for a bank-details payment."
        },
        "accountType": {
          "type": "string",
          "description": "ISO 20022 account type: CACC (checking/current), SVGS (savings), TRAN (payment account), SLRY (salary). Required for a bank-details payment.",
          "enum": [
            "CACC",
            "SVGS",
            "TRAN",
            "SLRY"
          ]
        },
        "accountNumber": {
          "type": "string",
          "description": "Beneficiary account number. Required for a bank-details payment."
        },
        "branch": {
          "type": "string",
          "description": "Beneficiary branch number. Required for a bank-details payment."
        }
      }
    },
    "PixPaymentMethodV3": {
      "type": "object",
      "required": [
        "type"
      ],
      "description": "Pix payment method. The destination is inferred from which fields are populated: dictKey for a Pix key, qrCode for a QR, neither for bank details.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "PIX"
          ]
        },
        "dictKey": {
          "type": "string",
          "description": "Beneficiary Pix (DICT) key. Mutually exclusive with qrCode."
        },
        "dictKeyType": {
          "type": "string",
          "enum": [
            "CPF",
            "CNPJ",
            "EMAIL",
            "PHONE",
            "EVP"
          ],
          "description": "Type of the Pix key. Required whenever dictKey is sent: CPF and CNPJ keys are both digit strings and cannot be told apart from the value."
        },
        "qrCode": {
          "type": "string",
          "description": "EMV copy-and-paste string of a static or dynamic Pix QR. Mutually exclusive with dictKey. Its amount, expiry, and schedulability are resolved asynchronously and surface through polling."
        },
        "desiredPaymentDate": {
          "type": "string",
          "format": "date",
          "description": "Scheduled execution date (YYYY-MM-DD, America/Sao_Paulo). Minimum D+1; omit to pay immediately. A dynamic immediate (cob) QR cannot be scheduled."
        }
      }
    }
  }
}