Cobrança Recorrente Completa

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/citi/main/json-schema/citi-cob-rcompleta-schema.json",
  "title": "Cobrança Recorrente Completa",
  "description": "Dados completos da cobrança recorrente via API Pix",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/citi-cobr-api-openapi.yml#/components/schemas/CobRCompleta",
  "type": "object",
  "required": [
    "idRec",
    "txid",
    "status",
    "valor",
    "recebedor",
    "calendario"
  ],
  "allOf": [
    {
      "type": "object",
      "properties": {
        "idRec": {
          "$ref": "#/$defs/RecId"
        }
      }
    },
    {
      "type": "object",
      "properties": {
        "txid": {
          "$ref": "#/$defs/TxId"
        }
      }
    },
    {
      "$ref": "#/$defs/CobRBase"
    },
    {
      "type": "object",
      "properties": {
        "calendario": {
          "type": "object",
          "required": [
            "criacao"
          ],
          "properties": {
            "criacao": {
              "type": "string",
              "format": "date",
              "title": "Data de criação da cobrança",
              "description": "Trata-se de uma data, no formato `YYYY-MM-DD`, segundo ISO 8601. É a data de criação da cobrança."
            }
          }
        }
      }
    },
    {
      "$ref": "#/$defs/CobRStatus"
    },
    {
      "$ref": "#/$defs/CobRConfiguracao"
    },
    {
      "$ref": "#/$defs/DadosDevedorRecorrencia"
    },
    {
      "type": "object",
      "properties": {
        "pix": {
          "type": "array",
          "title": "Pix recebidos",
          "items": {
            "allOf": [
              {
                "$ref": "#/$defs/PixAutomatico"
              },
              {
                "type": "object",
                "properties": {
                  "txid": {
                    "allOf": [
                      {
                        "$ref": "#/$defs/TxId"
                      },
                      {
                        "pattern": "[a-zA-Z0-9]{26,35}"
                      }
                    ]
                  }
                }
              }
            ]
          }
        }
      }
    },
    {
      "$ref": "#/$defs/CobRAtualizacao"
    },
    {
      "$ref": "#/$defs/CobRTentativas"
    }
  ],
  "$defs": {
    "CobRAtualizacao": {
      "type": "object",
      "title": "Histórico de Atualização da Cobrança Recorrente",
      "required": [
        "atualizacao"
      ],
      "properties": {
        "atualizacao": {
          "type": "array",
          "title": "Histórico de Status",
          "description": "Histórico das mudanças de status das cobranças recorrentes.",
          "items": {
            "type": "object",
            "required": [
              "status",
              "data"
            ],
            "properties": {
              "status": {
                "type": "string",
                "title": "Status da cobrança",
                "description": "Status da cobrança.",
                "enum": [
                  "CRIADA",
                  "ATIVA",
                  "CONCLUIDA",
                  "EXPIRADA",
                  "REJEITADA",
                  "CANCELADA"
                ]
              },
              "data": {
                "type": "string",
                "format": "date-time",
                "description": "Data e hora do registro de status atualizado. Respeita RFC 3339."
              }
            }
          }
        },
        "encerramento": {
          "type": "object",
          "title": "Detalhamento do encerramento da cobrança.",
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "cancelamento": {
                  "type": "object",
                  "title": "Informações sobre o cancelamento da cobrança",
                  "required": [
                    "solicitante",
                    "codigo",
                    "descricao"
                  ],
                  "description": "Informações sobre o cancelamento da cobrança",
                  "properties": {
                    "solicitante": {
                      "type": "string",
                      "title": "Solicitante do cancelamento",
                      "enum": [
                        "PSP_PAGADOR",
                        "USUARIO_PAGADOR",
                        "PSP_RECEBEDOR",
                        "USUARIO_RECEBEDOR"
                      ]
                    },
                    "codigo": {
                      "type": "string",
                      "title": "Código do cancelamento",
                      "description": "Código do cancelamento. Corresponde ao código de cancelamento presente no catálogo de mensagens.",
                      "maxLength": 4,
                      "enum": [
                        "ACCT",
                        "BLCK",
                        "CCLD",
                        "FAIL",
                        "OTHR",
                        "SLBD",
                        "SLCR"
                      ]
                    },
                    "descricao": {
                      "type": "string",
                      "title": "Descricao do cancelamento",
                      "description": "Descricao da causa do cancelamento",
                      "maxLength": 105
                    }
                  }
                }
              }
            },
            {
              "type": "object",
              "properties": {
                "rejeicao": {
                  "type": "object",
                  "title": "Informações sobre a rejeição da cobrança",
                  "required": [
                    "codigo",
                    "descricao"
                  ],
                  "description": "Informações sobre a rejeição da cobrança",
                  "properties": {
                    "codigo": {
                      "type": "string",
                      "title": "Código da rejeição",
                      "description": "Código da rejeição. Corresponde ao código de rejeição presente no catálogo de mensagens.",
                      "maxLength": 4,
                      "enum": [
                        "AB10",
                        "AC05",
                        "AC06",
                        "AM02",
                        "AM09",
                        "DENC",
                        "DS27",
                        "DTED",
                        "DTNT",
                        "FBRD",
                        "IRNT",
                        "MIDI",
                        "MSUC",
                        "NIEC",
                        "NIPA",
                        "NITX",
                        "QUNT",
                        "RC09",
                        "UDEI"
                      ]
                    },
                    "descricao": {
                      "type": "string",
                      "title": "Descricao da rejeição",
                      "description": "Descricao da causa da rejeição",
                      "maxLength": 105
                    }
                  }
                }
              }
            }
          ]
        }
      }
    },
    "CobRBase": {
      "type": "object",
      "title": "Cobrança Recorrente Base",
      "required": [
        "ajusteDiaUtil"
      ],
      "description": "Atributos de cobrança recorrente",
      "properties": {
        "infoAdicional": {
          "type": "string",
          "title": "Informações adicionais da fatura.",
          "description": "Informações adicionais da fatura.",
          "minLength": 1,
          "maxLength": 140
        },
        "calendario": {
          "type": "object",
          "title": "Informações sobre calendário da cobrança",
          "required": [
            "dataDeVencimento"
          ],
          "description": "",
          "properties": {
            "dataDeVencimento": {
              "type": "string",
              "format": "date",
              "title": "Data de vencimento da cobrança",
              "description": "Trata-se de uma data, no formato `YYYY-MM-DD`, segundo ISO 8601. É a data de vencimento da cobrança."
            }
          }
        },
        "valor": {
          "type": "object",
          "title": "Valor da cobrança recorrente",
          "required": [
            "original"
          ],
          "description": "Valor da cobrança recorrente",
          "properties": {
            "original": {
              "type": "string",
              "title": "Valor",
              "pattern": "\\d{1,10}\\.\\d{2}",
              "description": "Valor original da cobrança."
            }
          }
        },
        "ajusteDiaUtil": {
          "type": "boolean",
          "title": "Ajuste data prevista para liquidação para próximo dia útil",
          "default": false,
          "description": "Campo de ativação do ajuste da data prevista para liquidação para próximo dia útil caso o vencimento corrente seja um dia não útil. O PSP Recebedor deverá considerar os feriados locais com base no código município do usuário pagador."
        },
        "recebedor": {
          "title": "Recebedor",
          "description": "O objeto recebedor organiza as informações sobre o recebedor da cobrança.",
          "allOf": [
            {
              "$ref": "#/$defs/DadosBancariosRecebedor"
            }
          ]
        }
      }
    },
    "CobRConfiguracao": {
      "type": "object",
      "title": "Configuração da Cobrança Recorrente",
      "required": [
        "politicaRetentativa"
      ],
      "properties": {
        "politicaRetentativa": {
          "type": "string",
          "title": "Política de retentativa da cobrança recorrente",
          "enum": [
            "NAO_PERMITE",
            "PERMITE_3R_7D"
          ]
        }
      }
    },
    "CobRStatus": {
      "type": "object",
      "title": "Status da Cobrança Recorrente",
      "properties": {
        "status": {
          "type": "string",
          "title": "Status do registro da cobrança",
          "enum": [
            "CRIADA",
            "ATIVA",
            "CONCLUIDA",
            "EXPIRADA",
            "REJEITADA",
            "CANCELADA"
          ]
        }
      }
    },
    "CobRTentativas": {
      "type": "object",
      "title": "Histórico de Tentativas da Cobrança Recorrente",
      "properties": {
        "tentativas": {
          "type": "array",
          "title": "Histórico de Tentativas de Cobrança",
          "description": "Histórico de Tentativas de Cobrança",
          "items": {
            "type": "object",
            "required": [
              "dataLiquidacao",
              "tipo",
              "endToEndId",
              "status",
              "atualizacao"
            ],
            "properties": {
              "dataLiquidacao": {
                "type": "string",
                "format": "date",
                "description": "Data da liquidação da cobrança. Trata-se de uma data, no formato `YYYY-MM-DD`, segundo ISO 8601."
              },
              "tipo": {
                "type": "string",
                "title": "Tipo da Tentativa",
                "description": "Tipo da tentativa da cobrança.",
                "enum": [
                  "AGND",
                  "NTAG",
                  "RIFL"
                ]
              },
              "status": {
                "type": "string",
                "title": "Status da Tentativa",
                "description": "Status da tentativa da cobrança.",
                "enum": [
                  "SOLICITADA",
                  "AGENDADA",
                  "PAGA",
                  "CANCELADA",
                  "REJEITADA",
                  "EXPIRADA"
                ]
              },
              "endToEndId": {
                "$ref": "#/$defs/EndToEndId"
              },
              "atualizacao": {
                "type": "array",
                "title": "Histórico de Status da Tentativa",
                "description": "Histórico das mudanças de status da tentativa de cobrança.",
                "items": {
                  "type": "object",
                  "required": [
                    "status",
                    "data"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "title": "Status da Tentativa",
                      "description": "Status da tentativa da cobrança.",
                      "enum": [
                        "SOLICITADA",
                        "AGENDADA",
                        "PAGA",
                        "CANCELADA",
                        "REJEITADA",
                        "EXPIRADA"
                      ]
                    },
                    "data": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Data e hora do registro de status atualizado. Respeita RFC 3339."
                    }
                  }
                }
              },
              "rejeicao": {
                "type": "object",
                "title": "Informações sobre a rejeição da tentativa da cobrança",
                "required": [
                  "codigo",
                  "descricao"
                ],
                "description": "Informações sobre a rejeição da tentativa da cobrança",
                "properties": {
                  "codigo": {
                    "type": "string",
                    "title": "Código da rejeição da tentativa",
                    "description": "Código da rejeição da tentativa. Corresponde ao código de rejeição presente no catálogo de mensagens. Os códigos de rejeição da tentativa `AC05`,`AM09`,`DENC`,`DS27`,`DTED`,`MIDI`,`MSUC`,`NITX`,`RC09` e `DTED` causam a rejeição da cobrança recorrente correspondente.",
                    "maxLength": 4,
                    "enum": [
                      "AB10",
                      "AC05",
                      "AC06",
                      "AM02",
                      "AM09",
                      "DENC",
                      "DS27",
                      "DTED",
                      "DTNT",
                      "FBRD",
                      "IRNT",
                      "MIDI",
                      "MSUC",
                      "NIEC",
                      "NIPA",
                      "NITX",
                      "QUNT",
                      "RC09",
                      "UDEI"
                    ]
                  },
                  "descricao": {
                    "type": "string",
                    "title": "Descricao da rejeição",
                    "description": "Descricao da causa da rejeição",
                    "maxLength": 105
                  }
                }
              }
            }
          }
        }
      }
    },
    "DadosBancariosRecebedor": {
      "type": "object",
      "required": [
        "conta",
        "tipoConta"
      ],
      "properties": {
        "conta": {
          "type": "string",
          "title": "Conta",
          "description": "Número da conta do usuário recebedor.",
          "minLength": 1,
          "maxLength": 20
        },
        "tipoConta": {
          "type": "string",
          "title": "Tipo da conta do usuário recebedor",
          "description": "Tipo da conta do usuário recebedor.",
          "enum": [
            "CORRENTE",
            "POUPANCA",
            "PAGAMENTO"
          ]
        },
        "agencia": {
          "type": "string",
          "title": "Agencia",
          "description": "Número da agência do usuário recebedor.",
          "minLength": 1,
          "maxLength": 4
        }
      }
    },
    "DadosComplementaresPessoa": {
      "type": "object",
      "properties": {
        "logradouro": {
          "type": "string",
          "title": "Logradouro",
          "description": "Logradouro do usuário.",
          "minLength": 1,
          "maxLength": 200
        },
        "cidade": {
          "type": "string",
          "title": "Cidade",
          "description": "Cidade do usuário.",
          "minLength": 1,
          "maxLength": 200
        },
        "uf": {
          "type": "string",
          "title": "UF",
          "description": "UF do usuário.",
          "minLength": 2,
          "maxLength": 2
        },
        "cep": {
          "type": "string",
          "title": "CEP",
          "description": "CEP do usuário.",
          "minLength": 8,
          "maxLength": 8
        }
      }
    },
    "DadosDevedorRecorrencia": {
      "type": "object",
      "properties": {
        "devedor": {
          "title": "Devedor",
          "description": "O objeto devedor organiza as informações sobre o devedor da recorrência.",
          "allOf": [
            {
              "type": "object",
              "properties": {
                "email": {
                  "type": "string",
                  "title": "Email",
                  "pattern": "[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,4}$",
                  "description": "Email do usuário."
                }
              }
            },
            {
              "$ref": "#/$defs/DadosComplementaresPessoa"
            }
          ]
        }
      }
    },
    "DevolucaoId": {
      "type": "string",
      "title": "Id da Devolução",
      "description": "Id gerado pelo cliente para representar unicamente uma devolução.",
      "pattern": "[a-zA-Z0-9]{1,35}"
    },
    "DevolucaoNaturezaPixAutomatico": {
      "type": "string",
      "title": "Natureza da Devolução",
      "description": "Indica qual é a natureza da devolução. Uma devolução pode ser relacionada a um Pix comum (com códigos possíveis: `MD06` e `FR01` da pacs.004 e `REFU` da pacs.008). Na ausência deste campo a natureza deve ser interpretada como \nsendo de um Pix comum (`ORIGINAL`).\n\nAs naturezas são assim definidas:\n  - `ORIGINAL`: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix comum (`MD06`);\n  - `MED_FRAUDE`: quando a devolução ocorre no âmbito do MED (Mecanismo Especial de Devolução) por fundada suspeita de fraude e se refere a um Pix comum (`FR01`).\n  - `MED_PIX_AUTOMATICO`: reembolso total ou parcial ao participante do usuário pagador no âmbito do MED (Mecanismo Especial de Devolução) para o Pix Automático pela utilização de recursos próprios para ressarcimento do usuário pagador.(`REFU`);\n\nOs valores de devoluções são sempre limitados aos valores máximos a seguir:\n- Pix comum: o valor da devolução é limitado ao valor do próprio Pix (a natureza nesse caso pode ser: ORIGINAL, MED_PIX_AUTOMATICO ou MED_FRAUDE);\n",
      "enum": [
        "ORIGINAL",
        "MED_PIX_AUTOMATICO",
        "MED_FRAUDE"
      ]
    },
    "DevolucaoPixAutomatico": {
      "type": "object",
      "title": "Devolução",
      "required": [
        "id",
        "rtrId",
        "valor",
        "horario",
        "status"
      ],
      "properties": {
        "id": {
          "$ref": "#/$defs/DevolucaoId"
        },
        "rtrId": {
          "type": "string",
          "title": "RtrId",
          "description": "ReturnIdentification que transita na PACS004.",
          "pattern": "[a-zA-Z0-9]{32}",
          "minLength": 32,
          "maxLength": 32
        },
        "valor": {
          "type": "string",
          "title": "Valor a devolver.",
          "pattern": "\\d{1,10}\\.\\d{2}",
          "description": "Valor a devolver."
        },
        "natureza": {
          "$ref": "#/$defs/DevolucaoNaturezaPixAutomatico"
        },
        "descricao": {
          "type": "string",
          "title": "Mensagem ao pagador relativa à devolução.",
          "maxLength": 140,
          "description": "O campo `descricao`, opcional, determina um texto a ser apresentado ao pagador contendo informações sobre a devolução. Esse texto será preenchido, na pacs.004, pelo PSP do recebedor, no campo RemittanceInformation. O tamanho do campo na pacs.004 está limitado a 140 caracteres."
        },
        "horario": {
          "type": "object",
          "properties": {
            "solicitacao": {
              "type": "string",
              "format": "date-time",
              "title": "Horário de solicitação",
              "description": "Horário no qual a devolução foi solicitada no PSP."
            },
            "liquidacao": {
              "type": "string",
              "format": "date-time",
              "title": "Horário de liquidacao",
              "description": "Horário no qual a devolução foi liquidada no PSP."
            }
          }
        },
        "status": {
          "type": "string",
          "title": "Status",
          "description": "Status da devolução.",
          "enum": [
            "EM_PROCESSAMENTO",
            "DEVOLVIDO",
            "NAO_REALIZADO"
          ]
        },
        "motivo": {
          "type": "string",
          "title": "Descrição do status.",
          "description": "# Status da Devolução\n\nCampo opcional que pode ser utilizado pelo PSP recebedor para detalhar os motivos\nde a devolução ter atingido o status em questão.\nPode ser utilizado, por exemplo, para detalhar o motivo de a devolução não ter sido realizada.\n",
          "maxLength": 140
        }
      }
    },
    "EndToEndId": {
      "type": "string",
      "title": "Id fim a fim da transação",
      "description": "EndToEndIdentification que transita na PACS002, PACS004 e PACS008",
      "pattern": "[a-zA-Z0-9]{32}",
      "minLength": 32,
      "maxLength": 32
    },
    "PixAutomatico": {
      "type": "object",
      "title": "Pix",
      "required": [
        "txid",
        "endToEndId",
        "valor",
        "horario"
      ],
      "properties": {
        "endToEndId": {
          "$ref": "#/$defs/EndToEndId"
        },
        "txid": {
          "allOf": [
            {
              "$ref": "#/$defs/TxId"
            },
            {
              "pattern": "[a-zA-Z0-9]{1,35}"
            }
          ]
        },
        "valor": {
          "type": "string",
          "title": "Valor do Pix.",
          "pattern": "\\d{1,10}\\.\\d{2}",
          "description": "Valor do Pix."
        },
        "horario": {
          "type": "string",
          "format": "date-time",
          "title": "Horário",
          "description": "Horário em que o Pix foi processado no PSP."
        },
        "infoPagador": {
          "type": "string",
          "title": "Informação livre do pagador",
          "maxLength": 140
        },
        "devolucoes": {
          "type": "array",
          "title": "Devoluções",
          "items": {
            "$ref": "#/$defs/DevolucaoPixAutomatico"
          }
        }
      }
    },
    "RecId": {
      "type": "string",
      "title": "ID Recorrência",
      "description": "# Identificador da Recorrência\n\nRegra de formação:\n- RAxxxxxxxxyyyyMMddkkkkkkkkkkk (29 caracteres; \"case sensitive\", isso é, diferencia letras maiúsculas e minúsculas), sendo:\n  - \"R\":  fixo (1 caractere). \"R\" para a recorrência criada dentro do Pix;\n  - \"A\": identificação da possibilidade de novas tentativas, sendo possíveis os valores \"R\" ou \"N\" (1 caractere). \"R\" caso a recorrência permita novas tentativas de pagamento pós vencimento, ou \"N\" caso não permita novas tentativas.\n  - \"xxxxxxxx\":  identificação do agente que presta serviço para o usuário recebedor que gerou o <Id>, podendo ser: o ISPB do participante direto, o ISPB do participante indireto ou os 8 primeiros dígitos do CNPJ do prestador de serviço de iniciação (8 caracteres numéricos [0-9]);\n  - \"yyyyMMdd\":  data (8 caracteres) de criação da recorrência;\n  - \"kkkkkkkkkkk\": sequencial criado pelo agente que gerou o <Id> (11 caracteres alfanuméricos [a-z|A-Z|0-9]). Deve ser único dentro de cada \"yyyyMMdd\".\n\nDessa forma, o ID da recorrência deve ser formado de acordo com um dos tipos a seguir:\n- \"RRxxxxxxxxyyyyMMddkkkkkkkkkkk\"; para recorrência criada dentro do Pix e que permite novas tentativas de pagamento pós vencimento; ou\n- \"RNxxxxxxxxyyyyMMddkkkkkkkkkkk\"; para recorrência criada dentro do Pix e que não permite novas tentativas de pagamento pós vencimento.”\n",
      "pattern": "[a-zA-Z0-9]{29}",
      "minLength": 29,
      "maxLength": 29
    },
    "TxId": {
      "type": "string",
      "title": "Id da Transação",
      "description": "# Identificador da transação\n\nO campo `txid` determina o identificador da transação.\nO objetivo desse campo é ser um elemento que possibilite ao PSP do recebedor apresentar ao usuário recebedor a funcionalidade de conciliação de pagamentos.\n\nNa pacs.008, é referenciado como `TransactionIdentification <txId>` ou `idConciliacaoRecebedor`.\n\nEm termos de fluxo de funcionamento, o txid é lido pelo aplicativo do PSP do pagador e, \ndepois de confirmado o pagamento, é enviado para o SPI via pacs.008. \nUma pacs.008 também é enviada ao PSP do recebedor, contendo, além de todas as informações usuais \ndo pagamento, o txid.\nAo perceber um recebimento dotado de txid, o PSP do recebedor está apto a se comunicar com o usuário recebedor, \ninformando que um pagamento específico foi liquidado.\n\nO txid é criado exclusivamente pelo usuário recebedor e está sob sua responsabilidade.\nO txid, no contexto de representação de uma cobrança, é único por CPF/CNPJ do usuário recebedor. Cabe ao \nPSP recebedor validar essa regra na API Pix.\n",
      "pattern": "[a-zA-Z0-9]{26,35}",
      "minLength": 26,
      "maxLength": 35
    }
  }
}