{ "$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 , 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 (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 ` 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 } } }