├── .github └── workflows │ └── plantuml.yml ├── .gitignore ├── 422-codes-ted-tef.txt ├── 422-descricoes-ted-tef.txt ├── 422-titulos-ted-tef.txt ├── README.md ├── ciclo-de-vida-consentimento.png ├── ciclo-vida-pagamento-agendado.png ├── estrutura-payload-create-consent.png ├── imgs └── fluxo-revogacao-usuario-iniciadora.svg ├── jornada-pagamentoagendado.png ├── lista-de-finalidades.txt ├── payload_consents.md ├── payload_payment.md ├── pix-agendamento-proposta-final.md ├── renderizacao-enum.png ├── ted-tef-proposta.md ├── ted-tef-reject-reason.txt └── tef-proxy-proposta.md /.github/workflows/plantuml.yml: -------------------------------------------------------------------------------- 1 | name: generate plantuml 2 | on: push 3 | jobs: 4 | generate_plantuml: 5 | runs-on: ubuntu-latest 6 | name: plantuml 7 | steps: 8 | - name: checkout 9 | uses: actions/checkout@v1 10 | with: 11 | fetch-depth: 1 12 | - name: plantuml 13 | id: plantuml 14 | uses: grassedge/generate-plantuml-action@v1.5 15 | with: 16 | path: imgs 17 | message: "Render PlantUML files" 18 | env: 19 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 20 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /.idea/ 2 | -------------------------------------------------------------------------------- /422-codes-ted-tef.txt: -------------------------------------------------------------------------------- 1 | VALOR_ACIMA_LIMITE - Indica que o pagamento foi rejeitado por ter um valor maior ou quantidade pagamentos supere o limite pré-estabelecido pela detentora de conta. 2 | PAGAMENTO_DIVERGENTE_DO_CONSENTIMENTO - Indica que o pagamento foi rejeitado devido aos incompatibilidade com os dados do consentimento associado 3 | CONSENTIMENTO_INVALIDO - Indica que o pagamento foi rejeitado devido ao consentimento vinculado não estar em um estado esperado pelo fluxo de pagamento. 4 | SALDO_INSUFICIENTE - Indica que o pagamento foi rejeitado por insuficiência de fundos na conta do pagador. 5 | JANELA_OPER_INVALIDA - Indica que o pagamento foi rejeitado devido ao fato da janela de horário de pagamentos permitida do arranjo enccerrou. 6 | LIQUIDACAO_ERRO_INESPERADO - Indica que ocorreu um problema inesperado na liquidação do pagamento junto ao arranjo alvo 7 | NAO_INFORMADO - Indica que o pagamento foi rejeitado por uma situação não informada pela detentora -------------------------------------------------------------------------------- /422-descricoes-ted-tef.txt: -------------------------------------------------------------------------------- 1 | Code: VALOR_ACIMA_LIMITE , Descrição: Acima do limite estabelecido 2 | Code: PAGAMENTO_DIVERGENTE_DO_CONSENTIMENTO, Descrição: Dados do pagamento divergentes dos dados do consentimento. 3 | Code: CONSENTIMENTO_INVALIDO, Descrição: Consentimento inválido (status diferente de "AUTHORISED" ou está expirado) 4 | Code: SALDO_INSUFICIENTE, Descrição: A conta selecionada não possui saldo suficiente para realizar o pagamento 5 | Code: JANELA_OPER_INVALIDA, Descrição: Requisição está fora da janela de funcionamento. 6 | Code: LIQUIDACAO_ERRO_INESPERADO, Descrição: Erro na liquidação do pagamento no arranjo alvo. 7 | Code: NAO_INFORMADO, Descrição: Não reportado/identificado pela instituição detentora de conta. -------------------------------------------------------------------------------- /422-titulos-ted-tef.txt: -------------------------------------------------------------------------------- 1 | Code: VALOR_ACIMA_LIMITE , Título: Acima do limite estabelecido 2 | Code: PAGAMENTO_DIVERGENTE_DO_CONSENTIMENTO, Título: Divergência entre pagamento e consentimento 3 | Code: CONSENTIMENTO_INVALIDO, Título: Consentimento inválido 4 | Code: SALDO_INSUFICIENTE, Título: Saldo insuficiente 5 | Code: JANELA_OPER_INVALIDA, Título: Janela de operação inválida 6 | Code: LIQUIDACAO_ERRO_INESPERADO, Título: Erro na liquidação do pagamento no arranjo 7 | Code: NAO_INFORMADO, Título: Não informado -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # ob-docs 2 | Esboços de especificações para o Open Banking. 3 | -------------------------------------------------------------------------------- /ciclo-de-vida-consentimento.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/thbezerra/ob-docs/69b8a51aeba108d1910bd4ff0af7febf18a83ef2/ciclo-de-vida-consentimento.png -------------------------------------------------------------------------------- /ciclo-vida-pagamento-agendado.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/thbezerra/ob-docs/69b8a51aeba108d1910bd4ff0af7febf18a83ef2/ciclo-vida-pagamento-agendado.png -------------------------------------------------------------------------------- /estrutura-payload-create-consent.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/thbezerra/ob-docs/69b8a51aeba108d1910bd4ff0af7febf18a83ef2/estrutura-payload-create-consent.png -------------------------------------------------------------------------------- /imgs/fluxo-revogacao-usuario-iniciadora.svg: -------------------------------------------------------------------------------- 1 | UsuárioUsuárioIniciadoraIniciadoraDetentora OBDetentora OBPIXPIX1. Solicitar revogação do consentimento para pagamento agendado1.1 Criar a solicitação de revogação de consentimento1.1.1 Cancelar agendamento PIX1.1.2 Marcar o pagamento como rejeitado1.1.3 Marcar o consentimento como revogado1.1.4 Cancelar os tokens de acesso vinculados ao consentimento1.1.4 Armazenar a revogação do consentimento como completada -------------------------------------------------------------------------------- /jornada-pagamentoagendado.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/thbezerra/ob-docs/69b8a51aeba108d1910bd4ff0af7febf18a83ef2/jornada-pagamentoagendado.png -------------------------------------------------------------------------------- /lista-de-finalidades.txt: -------------------------------------------------------------------------------- 1 | 1 - Pagamento de Impostos, Tributos e Taxas 2 | 10 - Crédito em Conta 3 | 100 - Depósito Judicial 4 | 101 - Pensão Alimentícia 5 | 103 - Cessão de créditos - Liquid.principal por aquis.créditos ou direitos creditórios ou fluxo de caixa garant.por créditos, por ordem cliente PJ financ. 6 | 104 - Cessão de créditos - Liquidação principal por aquisição de créditos ou direitos creditórios, por ordem de FIDC ou cia securitizadora 7 | 107 - Cessão de créditos - Repasse contratual de fluxo de caixa ou de recebíveis pagos, por ordem de cliente PJ financeira 8 | 108 - Cessão de créditos - Repasse contratual de fluxo de caixa ou de recebíveis pagos antecipadamente, por ordem de cliente PJ financeira 9 | 109 - Cessão de créditos - Ajustes diversos 10 | 11 - Pagamento a Corretoras 11 | 110 - Transferência entre contas de mesma titularidade 12 | 111 - Crédito para investidor em cliente da IF Creditada 13 | 112 - Débito de investidor em cliente da IF Debitada 14 | 113 - Pagamento de Operações de Crédito por Cliente 15 | 114 - Resgate de aplicação financeira de cliente para conta de sua titularidade 16 | 117 - Aplicação financeira em nome do cliente remetente 17 | 12 - Pagamento de Boleto Bancário em Cartório 18 | 121 - Pagamento da TIR - Pix Saque e/ou Pix Troco 19 | 123 - Cessão de créditos - Liquid.princ.por recompra de créditos ou direitos creditórios ou fluxo de caixa garant.por créditos, por ordem cliente PJ financ. 20 | 124 - Cessão de créditos - Liquidação principal por recompra de créditos ou direitos creditórios, por ordem de FIDC ou cia securitizadora 21 | 13 - Pagamento de Tarifas pela Prestação de Serviços de Arrecadação de Convênios 22 | 131 - FGCoop - Recolhimento Fundo Garantidor do Cooperativismo de Crédito 23 | 132 - FGCoop - devolução de recolhimento a maior 24 | 136 - FGTS - Saque Emergencial 25 | 139 - Crédito ao consumidor decorrente de programa de incentivo fiscal 26 | 14 - Repasse de Valores Referentes a Títulos Liquidados em Cartórios de Protesto 27 | 149 - Auxílio Emergencial Lei 13.982 28 | 15 - Liquidação Financeira de Operadora de Cartão 29 | 150 - Benefício Emergencial de Preservação do Emprego e da Renda - BEm 30 | 157 - Tributos Municipais ISS - LCP 157 31 | 175 - Tributos Municipais ISS TERCEIROS - LCP 157 32 | 18 - Operações Seguro Habitacional - SFH 33 | 19 - Operações do FDS - Caixa 34 | 2 - Pagamento à Concessionárias de Serviço Público 35 | 200 - Transferência Internacional em Reais 36 | 201 - Ajuste Posição Mercado Futuro 37 | 202 - Repasse de Valores do BNDES 38 | 203 - Liquidação de Compromissos Junto ao BNDES 39 | 204 - Operações de Compra e Venda de Ações - Bolsas de Valores e Mercado de Balcão 40 | 205 - Contratos Referenciados em Ações ou Índices de Ações - Bolsas de Valores, de Mercadorias e de futuros 41 | 206 - Operação de Câmbio - Não Interbancária 42 | 207 - Operações no Mercado de Renda Fixa e de Renda Variável com Utilização de Intermediário 43 | 208 - Operação de Câmbio - Mercado Interbancário - Instituições sem conta Reservas Bancárias 44 | 209 - Pagamento de Operações com identificação de destinatário final 45 | 23 - Taxa de Administração 46 | 27 - Pagamento de Acordo / Execução Judicial 47 | 28 - Liquidação de Empréstimos Consignados 48 | 29 - Pagamento de bolsa auxílio 49 | 3 - Pagamentos de Dividendos 50 | 30 - Remuneração a cooperado 51 | 300 - Restituição de Imposto de Renda 52 | 301 - Ordem Bancária do Tesouro - OBT 53 | 302 - Pagamento de multas ao BACEN por atrasos de importação 54 | 303 - Restituição de tributos - RFB 55 | 31 - Pagamento de prebenda (Remuneração a padres e sacerdotes) 56 | 33 - Pagamento de juros sobre capital próprio 57 | 34 - Pagamento de rendimentos ou amortização s/ cotas e/ou debêntures 58 | 35 - Taxa de Serviço 59 | 36 - Pagamento de cheque para não correntista 60 | 37 - Pagamento de juros e/ou amortização de títulos depositados em garantia nas Câmaras 61 | 38 - Estorno ou Restituição - Diversos 62 | 39 - Pagamento de Vale Transporte 63 | 4 - Pagamento de Salários 64 | 40 - Simples Nacional 65 | 41 - Repasse de valores para o FUNDEB 66 | 42 - Repasse de Valores de Convênio Centralizado 67 | 43 - Patrocínio com Incentivo Fiscal 68 | 44 - Doação com Incentivo Fiscal 69 | 45 - Transferência de conta corrente de instituição não bancária para sua Conta de Liquidação 70 | 47 - Pagamento de Rescisão de Contrato de Trabalho 71 | 5 - Pagamento de Fornecedores 72 | 50 - Reembolso de despesas com estruturação de operações de renda fixa e variável 73 | 500 - Restituição de Prêmios de Seguros 74 | 501 - Pagamento de Indenização de Sinistro de Seguro 75 | 502 - Pagamento de Prêmio de Co-Seguro 76 | 504 - Pagamento de Indenização de Sinistro de Co-Seguro 77 | 505 - Pagamento de Prêmio de Resseguro 78 | 507 - Pagamento de Indenização de Sinistro de Resseguro 79 | 508 - Restituição de Indenização de Sinistro de Resseguro 80 | 509 - Pagamento de Despesas com Sinistros 81 | 510 - Pagamento de Inspeções/Vistorias Prévias 82 | 511 - Pagamento de Resgate de Título da Capitalização 83 | 512 - Pagamento de Sorteio de Título de Capitalização 84 | 513 - Pagamento de Devolução de Mensalidade de Título de Capitalização 85 | 514 - Restituição de Contribuição de Plano Previdenciário 86 | 515 - Pagamento de Benefício Previdenciário de Pecúlio 87 | 516 - Pagamento de Benefício Previdenciário de Pensão 88 | 517 - Pagamento de Benefício Previdenciário de Aposentadoria 89 | 518 - Pagamento de Resgate Previdenciário 90 | 519 - Pagamento de Comissão de Corretagem 91 | 520 - Pagamento de Transferências/Portabilidade de Reserva de Seguro/Previdência 92 | 6 - Pagamento de Honorários 93 | 7 - Pagamento de Aluguéis e Taxas de Condomínio 94 | 8 - Pagamento de Duplicatas e Títulos 95 | 9 - Pagamento de Mensalidade Escolar 96 | 97 - Compra de Moeda Estrangeira pelo FSB - Fundo Soberano do Brasil 97 | 99999 - Outros -------------------------------------------------------------------------------- /payload_consents.md: -------------------------------------------------------------------------------- 1 | ``` 2 | { 3 | "data":{ 4 | "creditor":{ 5 | "personType":"PESSOA_NATURAL", 6 | "cpfCnpj":"58764789000137", 7 | "name":"Marco Antonio de Brito" 8 | }, 9 | "payment":{ 10 | "type":"PIX", 11 | "date":"2021-01-01", 12 | "currency":"BRL", 13 | "amount":"100000.12", 14 | "ibgeTownCode":"5300108", 15 | "details":{ 16 | "localInstrument":"DICT", 17 | "qrCode":"00020104141234567890123426660014BR.GOV.BCB.PIX014466756C616E6F32303139406578616D706C652E636F6D27300012\nBR.COM.OUTRO011001234567895204000053039865406123.455802BR5915NOMEDORECEBEDOR6008BRASILIA61087007490062\n530515RP12345678-201950300017BR.GOV.BCB.BRCODE01051.0.080450014BR.GOV.BCB.PIX0123PADRAO.URL.PIX/0123AB\nCD81390012BR.COM.OUTRO01190123.ABCD.3456.WXYZ6304EB76\n", 18 | "proxy":"12345678901", 19 | "creditorAccount":{ 20 | "ispb":"12345678", 21 | "issuer":"1774", 22 | "number":"1234567890", 23 | "accountType":"CACC" 24 | } 25 | } 26 | }, 27 | "debtorAccount":{ 28 | "ispb":"12345678", 29 | "issuer":"1774", 30 | "number":"1234567890", 31 | "accountType":"CACC" 32 | } 33 | } 34 | } 35 | ``` -------------------------------------------------------------------------------- /payload_payment.md: -------------------------------------------------------------------------------- 1 | ``` 2 | { 3 | "data": { 4 | "localInstrument": "DICT", 5 | "payment": { 6 | "amount": "100000.12", 7 | "currency": "BRL" 8 | }, 9 | "creditorAccount": { 10 | "ispb": "12345678", 11 | "issuer": "1774", 12 | "number": "1234567890", 13 | "accountType": "CACC" 14 | }, 15 | "remittanceInformation": "Pagamento da nota XPTO035-002.", 16 | "qrCode": "00020104141234567890123426660014BR.GOV.BCB.PIX014466756C616E6F32303139406578616D706C652E636F6D27300012\nBR.COM.OUTRO011001234567895204000053039865406123.455802BR5915NOMEDORECEBEDOR6008BRASILIA61087007490062\n530515RP12345678-201950300017BR.GOV.BCB.BRCODE01051.0.080450014BR.GOV.BCB.PIX0123PADRAO.URL.PIX/0123AB\nCD81390012BR.COM.OUTRO01190123.ABCD.3456.WXYZ6304EB76\n", 17 | "proxy": "12345678901", 18 | "cnpjInitiator": "50685362000135", 19 | "transactionIdentification": "E00038166201907261559y6j6", 20 | "ibgeTownCode": "5300108" 21 | } 22 | } 23 | ``` -------------------------------------------------------------------------------- /pix-agendamento-proposta-final.md: -------------------------------------------------------------------------------- 1 | # Indices 2 | - [Introdução](#introdução) 3 | - [Ciclos de vida](#ciclo-de-vida-de-consentimentos-e-pagamentos-agendados) 4 | - [Consentimento](#consentimento) 5 | - [Pagamento](#pagamento) 6 | - [Controle de Acesso](#controle-de-acesso) 7 | - [Agendamento de pagamentos](#agendamento-de-pagamentos) 8 | - [Jornada](#jornada) 9 | - [Endpoints](#endpoints) 10 | - [Criar consentimento](#criar-consentimento) 11 | - [Consultar consentimento](#consultar-consentimento) 12 | - [Criar pagamento PIX](#criar-pagamento-pix) 13 | - [Consultar pagamento PIX](#consultar-pagamento-pix) 14 | - [Mecanismo de retentativas de liquidação de pagamentos agendados](#mecanismo-de-retentativas-de-liquidao-de-pagamentos-agendados) 15 | - [Revogação do consentimento](#revogao-do-consentimento) 16 | - [Endpoints](#endpoint) 17 | - [Revogar consentimento](#revogar-consentimento) 18 | - [Consultar consentimento](#consultar-consentimento-revogado) 19 | - [Consultar pagamento agendado PIX](#consultar-pagamento-pix) 20 | - [Regras de negócio](#regras-de-negcio) 21 | 22 | 23 | # Introdução 24 | Esta proposta visa adicionar suporte a agendamento de pagamentos para datas futuras tendo como 25 | alvo inicial o suporte a pagamento agendados únicos (Sem recorrência) para o arranjo Pix, contudo pavimentando a possibilidade 26 | de adição de semelhante funcionalidade a outros meios de pagamentos posteriormente, pois as mudanças principais estão no consentimento. 27 | Toda a proposta fora escrita tendo o controle do mecanismo de agendamento junto as detentoras de contas. 28 | 29 | # Ciclo de vida de consentimentos e pagamentos agendados 30 | 31 | Para suportar a funcionalidade de agendamento serão necessárias alterações nas máquinas de estado dos recursos de consentimento e pagamentos. 32 | 33 | ## Consentimento 34 | Para suportar a possibilidade de revogação do consentimento o novo status **REVOKED** será adicionado ao schema: [EnumAuthorisationStatusType](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_EnumAuthorisationStatusType). 35 | O status **CONSUMED** do consentimento não será mais um estado final em consentimentos para pagamentos agendados, 36 | pois poderá ser alterado para o novo status **REVOKED** caso algum dos participantes da transação (Usuário final, Iniciadora ou Detentora) 37 | decida por cancelar o pagamento antes de ser liquidado. 38 | 39 | ![Ciclo de vida do consentimento](ciclo-de-vida-consentimento.png) 40 | 41 | ## Pagamento 42 | Para suportar a noção de agendamento serão adicionados dois novos status ao recurso de pagamentos pix listados abaixo o schema: [EnumPaymentStatusType](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_EnumPaymentStatusType). 43 | 1. **SASP (SCHEDULE_ACCEPTED_SETTLEMENT_IN_PROCESS)** 44 | 2. **SASC (SCHEDULE_ACCEPTED_SETTLEMENT_COMPLETED)** 45 | 46 | Estes dois novos status indicam respectivamente que o processo de agendamento está em processamento e o segundo que o agendamento foi realizado. 47 | O primeiro status faculta a possibilidade das detentoras implementarem um fluxo assíncrono de agendamento. 48 | No dia alvo do agendamento o pagamento será liquidado com os preceitos já estabelecidos da máquina estados do pagamento. 49 | 50 | ![Ciclo de vida do pagamento agendado](ciclo-vida-pagamento-agendado.png) 51 | 52 | # Controle de acesso 53 | A funcionalidade agendamento não introduz novas necessidades de controle de acesso ao que já é praticado na modalidade de pagamentos normais. 54 | Nesta sessão apenas gostaríamos de ratificar que o controle do tempo de vida máximo dos access tokens obtidos pelo processo de hybrid flow estão vinculados ao tempo de expiração do consentimento, deste modo 55 | a iniciadora poderá obter novos Acces-Tokens através do seu Reflesh Token até que o consentimento atinga sua data de expiração. 56 | 57 | # Agendamento de pagamentos 58 | A funcionalidade de agendamento proposta apenas permite agendamentos para pagamentos únicos, ou seja, sem recorrência. 59 | O suporte a recorrência será estudado no futuro caso haja necessidade. 60 | 61 | ## Jornada 62 | A jornada para realizar agendamentos de pagamentos fundamentalmente é semelhante à jornada de um pagamento normal 63 | facilitando o processo de suporte a funcionalidade. 64 | 65 | ![Jornada de pagamentos agendados](jornada-pagamentoagendado.png) 66 | 67 | ## Endpoints 68 | 69 | Para suportar o agendamento todos os endpoints envolvidos no processo de pagamentos normais sofrerão alterações. 70 | 71 | ### Criar consentimento 72 | 73 | **POST /payments/v1/consents** 74 | 75 | Os consentimentos criados por este endpoint terão a adição de novo objeto que írá conter os dados do agendamento conforme descrito adiante. 76 | Este novo objeto está sendo adicionado ao consentimento, portanto, agnóstico aos tipos de pagamentos, ou seja, PIX, TED/TEF e outros arranjos 77 | irão reutilizar o aqui definido. 78 | 79 | **Fragmento do consentimento com a estrutura do objeto de agendamento** 80 | ``` 81 | { 82 | "data":{ 83 | "payment":{ 84 | "type":"PIX", 85 | "schedule":{ 86 | "single":{ 87 | "date":"2035-01-01" 88 | } 89 | } 90 | } 91 | } 92 | } 93 | ``` 94 | Campo **schedule** foi adicionado para permitir que o novo objeto de agendamento seja descrito. 95 | Descrição dos campos: 96 | 97 | |**Campo**|**Tipo**|**Requerido**|**Descrição**|Regras de negócio| 98 | |----------|------|---------|--------------------------------------------------------|---------| 99 | |**data.payment.schedule**|objeto|condicionalmente|Define o agendamento do pagamento. Utilizado somente na funcionalidade de agendamento de pagamentos|N/A| 100 | |**data.payment.schedule.single**|objeto|sim|Define a política de agendamento único|N/A| 101 | |**data.payment.schedule.single.date**|string(date)|sim|Define a data alvo da liquidação do pagamento.O fuso horário de Brasilia deve ser utilizado para criação e racionalização sobre os dados deste campo|[RN101](#regras-de-validação), [RN103](#regras-de-validação)| 102 | 103 | **Regras de negócio** 104 | 1. [RN001](#regras-funcionais) 105 | 106 | ### Consultar consentimento 107 | 108 | **GET /payments/v1/consents/{consentId}** 109 | 110 | Todos os novos dados mencionados no endpoint de criação do consentimento também estarão presentes na resposta positiva deste endpoint. 111 | 112 | ### Criar pagamento pix 113 | 114 | **POST /payments/v1/pix/payments** 115 | 116 | Nenhuma mudança estrutural neste endpoint será feita para realizar o agendamento. Apenas será incluído os novos status conforme descrito em [Ciclo de vida](#ciclo-de-vida-de-consentimentos-e-pagamentos-agendados) 117 | 118 | ### Consultar pagamento PIX 119 | 120 | **GET /payments/v1/pix/payments/{paymentId}** 121 | 122 | Nenhuma mudança estrutural neste endpoint será feita para realizar o agendamento. Apenas será incluído os novos status conforme descrito em [Ciclo de vida](#ciclo-de-vida-de-consentimentos-e-pagamentos-agendados) e motivos de rejeição. 123 | 124 | ## Mecanismo de retentativas de liquidação de pagamentos agendados 125 | 126 | No momento da liquidação de pagamentos agendados é possível ter falhas sistêmicas ou violações de regras de negócio passiveis de recuperação em segundo momento 127 | como, por exemplo, ausência de saldo na conta do pagador para realizar a liquidação. Neste contexto poderia ser interessante as detentoras de conta a adoção de políticas de retentativa de liquidação. 128 | O arranjo PIX não define nada a respeito deste tema, então por consequência o Open Banking deixa livre para cada detentora adotar a política 129 | de retentativa que mais fazer sentido para ela. 130 | 131 | # Revogação do consentimento 132 | 133 | Com a inclusão da funcionalidade agendamento é interessante facultar para as partes envolvidas na transação a possibilidade de cancelamento do pagamento agendado antes da sua liquidação futura. 134 | Esse mecanismo de cancelamento do pagamento agendado será oferecido a partir da revogação de consentimentos para pagamentos agendados. 135 | Considerando a diretriz do controle do agendamento pela detentora de conta e as necessidades dos envolvidos na transação e possível as seguintes possibilidades de jornadas de revogação. 136 | 137 | 1. Revogação **pelo usuário na iniciadora** na área de gestão de pagamentos do open banking (Consulte o guia de UX do Open Banking para maiores detalhes) 138 | 2. Revogação **pelo usuário na detentora** na área de gestão de pagamentos do open banking (Consulte o guia de UX do Open Banking para maiores detalhes) 139 | 3. Revogação **pelo usuário na detentora** na área de gestão de Pix (Consulte o guia de UX do arranjo PIX para maiores detalhes) 140 | 4. Revogação pela iniciadora sem a presença do usuário 141 | 5. Revogação pela detentora sem a presença do usuário 142 | 143 | ## Endpoint 144 | Para incluir a funcionalidade revogação do consentimento será necessário a inclusão de um novo endpoint e a alteração do endpoint de consulta do consentimento descritos a seguir. 145 | Os dados do consentimento terão uma expansão para capturar as circunstâncias da revogação tornando claro ocorrido para todas as partes envolvidas. 146 | 147 | ### Revogar consentimento 148 | 149 | **PATCH /payments/v1/consents/{consentId}** 150 | 151 | **Parâmetros** 152 | 153 | |Nome|Origem|Tipo|Requerido|Descrição| 154 | |-----------------|----------|------------|---------|---------------------------------------------------------------------------------------------------------------------------| 155 | |**consentId**|path|string|sim|O consentId é o identificador único do consentimento a ser revogado e deverá ser um URN - Uniform Resource Name.| 156 | |**Authorization**|header|string|sim|Cabeçalho HTTP padrão. Permite que as credenciais sejam fornecidas dependendo do tipo de recurso solicitado.| 157 | |**x-fapi-auth-date**|header|string|não|Data em que o usuário logou pela última vez com o receptor. Representada de acordo com a RFC7231.Exemplo: Sun, 10 Sep 2017 19:43:31 UTC| 158 | |**x-fapi-customer-ip-address**|header|string|não|O endereço IP do usuário se estiver atualmente logado com o receptor.| 159 | |**x-fapi-interaction-id**|header|string|não|Um UID RFC4122 usado como um ID de correlação. Se fornecido, o transmissor deve "reproduzir" esse valor no cabeçalho de resposta.| 160 | |**x-idempotency-key**|header|string|sim|Cabeçalho HTTP personalizado. Identificador de solicitação exclusivo para suportar a idempotência.| 161 | |**x-customer-user-agent**|header|string|não|Indica o user-agent que o usuário utiliza.| 162 | 163 | **Payload de requisição** 164 | 165 | ``` 166 | { 167 | "data":{ 168 | "status":"REVOKED", 169 | "revocation":{ 170 | "loggedUser":{ 171 | "document":{ 172 | "identification":"11111111111", 173 | "rel":"CPF" 174 | } 175 | }, 176 | "revoked_by":"USER", 177 | "reason":{ 178 | "code":"OTHER", 179 | "additionalInformation":"Não quero mais o serviço" 180 | } 181 | } 182 | } 183 | } 184 | ``` 185 | **Descrição dos campos** 186 | 187 | |**Campo**|**Tipo**|**Requerido**|**Descrição**|Regras de negócio| 188 | |----------|------|---------|---------------------------------------------------------------------------------------------------------------|---------| 189 | |**data.status**|enumerado(string) - [EnumAuthorisationStatusType](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_EnumAccountPaymentsType)|sim|Status para qual o consentimento seguirá. Apenas o valor **REVOKED** será suportado no momento|[RN100](#regras-de-validação)| 190 | |**data.revocation**|objeto|sim|Objeto que contém as informações das circunstância da revogação|N/A| 191 | |**data.revocation.loggedUser**|objeto|condicionalmente|Representa o usuário (pessoa natural) que encontra-se logado na instituição Iniciadora de Pagamento.|[RN104](#regras-de-validação)| 192 | |**data.revocation.loggedUser.document**|objeto|sim|Objeto que contém os dados de identificação do usuário.|N/A| 193 | |**data.revocation.loggedUser.document.identification**|string|sim|Número do documento de identificação oficial do usuário.|N/A| 194 | |**data.revocation.loggedUser.document.rel**|string|sim|Tipo do documento de identificação oficial do usuário.|N/A| 195 | |**data.revocation.revoked_by**|enumerado(string)|sim|Define qual das partes envolvidas na transação está realizando a revogação. Valores possíveis: **USER** (Revogado pelo usuário), **ASPSP** (Provedor de serviços de pagamento para serviços de conta - Detentora de conta), **TPP** (Instituições Provedoras - iniciadora de pagamentos).|N/A| 196 | |**data.revocation.reason**|objeto|sim|Define a razão pela qual o consentimento foi revogado|N/A| 197 | |**data.revocation.reason.code**|enumerado(string)|sim|Define o código da razão pela qual o consentimento foi revogado. Valores possíveis: **FRAUD** (Indica suspeita de fraude), **ACCOUNT_CLOSURE** (Indica que a conta do usuário foi encerrada), **OTHER** (Indica que motivo do cancelamento está fora dos motivos pré-estabelecidos) |[RN108](#regras-de-validação)| 198 | |**data.revocation.reason.additionalInformation**|string(máximo: 255 Caracteres)|condicionalmente|Contém informações adicionais definidas pelo requisitante da revogação|[RN109](#regras-de-validação)| 199 | 200 | **Controle de acesso** 201 | 202 | Este endpoint deve suportar apenas ser chamado usando client credentials. 203 | 204 | **Regras de negócio** 205 | 206 | 1.[RN002](#regras-funcionais) 207 | 208 | ### Consultar consentimento revogado 209 | 210 | **GET /payments/v1/consents/{consentId}** 211 | 212 | Todos os novos dados mencionados no endpoint de revogação do consentimento também estarão presentes na resposta positiva deste endpoint. 213 | 214 | ### Consultar pagamento agendado PIX 215 | 216 | **GET /payments/v1/pix/payments/{paymentId}** 217 | 218 | Nenhuma mudança estrutural neste endpoint será feita para realizar a revogação. 219 | Apenas será incluído um novo motivo de rejeição: **CONSENT_REVOKED** para mostrar que o pagamento foi cancelado devido à revogação do consentimento. 220 | os novos status conforme descrito em [Ciclo de vida](#ciclo-de-vida-de-consentimentos-e-pagamentos-agendados) 221 | 222 | 223 | ## Regras de negócio 224 | 225 | Nesta sessão serão listadas todas as regras de negócio envolvidas nos endpoints citados nas sessões anteriores. 226 | 227 | ### Regras funcionais 228 | 229 | |**Código**|**Descrição**|Endpoint| 230 | |----------|-----------------------------------------------------------------------------------------------------------|------------| 231 | |**RN001**|Ao revogar um consentimento o pagamento associado deverá ir para o status **RJCT** e campo **rejectionReason** deverá ter o valor **CONSENT_REVOKED**. Schema: [EnumRejectionReasonType](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_EnumRejectionReasonType) |[Revogar consentimento](#revogar-consentimento)| 232 | 233 | 234 | ### Regras de validação 235 | 236 | |**Código**|**Descrição**|Endpoint|Resposta HTTP|Código de Erro|Título|Mensagem|Schema| 237 | |----------|------------------------------------------------------------------------------------------------------------------------------------------|-----------------|-------|----------------|--------------------------|-----------------------------|--------------------------| 238 | |**RN101**|O campo **data.payment.schedule.single.date** deverá sempre ser no mínimo D+1 corrido, ou seja, a data imediatamente posterior em relação a data do consentimento considerando o fuso horário de Brasília|[Criar consentimento](#criar-consentimento)|422|**INVALID_SCHEDULE**|Agendamento inválido|Agendamento inválido|[422ResponseErrorCreateConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_422ResponseErrorCreateConsent)| 239 | |**RN102**|O campo **data.status** na revogação do consentimento só deverá aceitar o valor **REVOKED**|[Revogar consentimento](#revogar-consentimento)|400|Livre|Livre|Livre|[ResponseError](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_ResponseError)| 240 | |**RN103**|O campo **data.payment.schedule.single.date** deverá ser no máximo um ano corrido a partir da data do consentimento considerando o fuso horário de Brasília|[Criar consentimento](#criar-consentimento)|422|**INVALID_SCHEDULE**|Agendamento inválido|Agendamento inválido|[422ResponseErrorCreateConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_422ResponseErrorCreateConsent)| 241 | |**RN104**|O campo **data.revocation.loggedUser** deve ser preenchidos quando a revogação for feita pelo usuário final, ou seja, se o campo **data.revocation.revoked_by** estiver com o valor **USER**|[Revogar consentimento](#revogar-consentimento)|422|USER_INFORMATION_REQUIRED|Informação do usuário requerida|Informação do usuário requerida|[422ResponseErrorCreateConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_422ResponseErrorCreateConsent)| 242 | |**RN105**|O consentimento só pode ser revogado nos status **CONSUMED**|[Revogar consentimento](#revogar-consentimento)|422|OPERATION_NOT_ALLOWED_BY_STATUS|Operação não permitida|Operação não permitida devido ao status atual do consentimento|[422ResponseErrorCreateConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_422ResponseErrorCreateConsent)| 243 | |**RN106**|Somente consentimentos para pagamentos agendados podem ser revogados, ou seja, que possuam o campo **data.payment.schedule** preenchido|[Revogar consentimento](#revogar-consentimento)|422|OPERATION_NOT_SUPPORTED_BY_CONSENT_TYPE|Operação não permitida|Operação não suportada pelo tipo de consentimento|[422ResponseErrorCreateConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_422ResponseErrorCreateConsent)| 244 | |**RN107**|O consentimento só pode ser revogado até o dia anterior, ou seja, a meia noite no fuso horário de Brasília do dia imediatamente anterior a data alvo da liquidação do pagamento|[Revogar consentimento](#revogar-consentimento)|422|REVOCATION_TIME_LIMIT_EXCEEDED|Prazo limite para revogação excedido|Prazo limite para revogação excedido|[422ResponseErrorCreateConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_422ResponseErrorCreateConsent)| 245 | |**RN108**|Os motivos de revogação do consentimento: **FRAUD** e **ACCOUNT_CLOSURE** só podem ser usados caso o campo: **data.revocation.revoked_by** tenha o valor **TPP** ou **ASPSP**, ou seja, somente no caso de revogação unilateral pela iniciadora ou detentora|[Revogar consentimento](#revogar-consentimento)|422|REVOCATION_REASON_NOT_ALLOWED|Motivo de revogação não permitido|Motivo de revogação não permitido|[422ResponseErrorCreateConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_422ResponseErrorCreateConsent)| 246 | |**RN109**|O campo **data.revocation.reason.additionalInformation** é obrigatório quando a revogação for feita pela iniciadora ou pela detentora unilateralmente, ou seja, o campo revoked_by igual a **TPP** ou **ASPSP** e o motivo de revogação for **OTHER**|[Revogar consentimento](#revogar-consentimento)|422|REVOCATION_ADDITIONAL_INFORMATION_REQUIRED|Informação adicional requerida|Informação adicional requerida|[422ResponseErrorCreateConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_422ResponseErrorCreateConsent)| 247 | -------------------------------------------------------------------------------- /renderizacao-enum.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/thbezerra/ob-docs/69b8a51aeba108d1910bd4ff0af7febf18a83ef2/renderizacao-enum.png -------------------------------------------------------------------------------- /ted-tef-proposta.md: -------------------------------------------------------------------------------- 1 | # Indices 2 | - [Introdução](#introdução) 3 | - [Consentimento](#consentimento) 4 | - [Criar consentimento](#criar-consentimento) 5 | - [Estruturação do payload de requisição](#estruturação-do-payload-de-requisição) 6 | - [Ciclo de vida](#ciclo-de-vida-do-consentimento) 7 | - [Agendamento](#agendamento) 8 | - [Pagamento](#pagamento) 9 | - [Criar pagamento](#criar-pagamento) 10 | - [Regras de negócio](#regras-de-negcio) 11 | - [Documentação da api e swagger](#documentação-da-api-e-swagger) 12 | 13 | # Introdução 14 | Esta proposta visa adicionar suporte a iniciação de pagamentos através do arranjo de **TED (Transferência Eletrônica Disponível) e TEF (Transferência Eletrônica de Fundos)**. 15 | **TED** é um arranjo de pagamentos que permite a realização de transferências financeiras entre instituições detentoras de contas no Banco Central. 16 | **TEF** é um arranjo de pagamentos que permite a realização de transferências financeiras entre contas dentro de uma mesma instituição financeira. 17 | 18 | 19 | # Consentimento 20 | Para realizar uma iniciação de pagamento através de qualquer arranjo de pagamentos pelo Open Banking é necessário a criação de um consentimento que representa o desejo do usuário 21 | de permitir que sejam utilizados recursos financeiros em uma das suas contas presentes em uma detentora de conta por uma iniciadora de pagamentos. 22 | Este conceito já é utilizado no Open Banking em face de outros arranjos de pagamentos e agora será expandido para suporte aos dois novos arranjos apresentados nesta proposta. 23 | O consentimento é criado via endpoint [REST](https://pt.wikipedia.org/wiki/REST) e o seu funcionamento para adição do suporte a **TED/TEF** será detalhado a seguir. 24 | 25 | ## Criar consentimento 26 | - **Path** : POST - /payments/v1/consents 27 | - **Request Payload** : [CreatePaymentConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_CreatePaymentConsent) 28 | - **HTTP 200 Response Payload**: [ResponsePaymentConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_ResponsePaymentConsent) 29 | - **HTTP 422 Response Payload**: [422ResponseErrorCreateConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_422ResponseErrorCreateConsent) 30 | 31 | O payload de requisição deste endpoint deverá ser expandido para suportar os dados necessários para os novos arranjos propostos. 32 | Antes de ser apresentado as expansões necessárias para cada arranjo será descrita uma reestruturação da composição do objeto requisição deste endpoint com finalidade de tornar mais clara a documentação do mesmo em face das necessidades específicas de cada arranjo suportado atualmente e os vindouros. 33 | 34 | ### Estruturação do payload de requisição 35 | 36 | Para facilitar a compreensão da nova estrutura proposta de payload e as relações entre os elementos que o compõe será utilizado o diagrama de classes abaixo. 37 | 38 | ![Estrutura payload criação de consentimento](estrutura-payload-create-consent.png) 39 | 40 | Toda a mudança proposta apresentada no diagrama se concentra no campo **data.payment** do schema **CreatePaymentConsent**. 41 | O schema desse campo (**PaymentConsent**) se tornaria uma estrutura [polimórfica](https://pt.wikipedia.org/wiki/Polimorfismo_(ci%C3%AAncia_da_computa%C3%A7%C3%A3o)) abstrata com três schemas concretos: **PixPaymentConsent**, **TedPaymentConsent** e **TefPaymentConsent** respectivamente para os arranjos **PIX**, **TED** e **TEF**. 42 | O campo determinante ([discriminator](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/)) de qual schema apropriado será o **type** . 43 | Uma conjectura surge a partir desta proposta que seria a não necessidade de existir um campo **details** para Pix visto que tudo poderia estar simplesmente definido no **PixPaymentConsent** diminuindo a profundidade do payload, contudo, neste momento essa alteração acarretaria em quebra de contrato de API o que é muito complexo de ser absorvido pelo ecossistema agora. 44 | 45 | Abaixo são apresentados fragmentos de payloads de consentimentos contendo a utilização dos três novos schemas com toda a informação disponível em cada um deles. 46 | Também serão descritos os campos novos, ou seja, introduzidos pelos novos arranjos. 47 | 48 | **PIX** 49 | ``` 50 | { 51 | "data":{ 52 | "payment":{ 53 | "type":"PIX", 54 | "date":"2021-01-01", 55 | "schedule":{ 56 | "single":{ 57 | "date":"2021-01-01" 58 | } 59 | }, 60 | "currency":"BRL", 61 | "amount":"100000.12", 62 | "ibgeTownCode":"5300108", 63 | "details":{ 64 | "localInstrument":"DICT", 65 | "qrCode":"00020104141234567890123426660014BR.GOV.BCB.PIX014466756C616E6F32303139406578616D706C652E636F6D27300012\nBR.COM.OUTRO011001234567895204000053039865406123.455802BR5915NOMEDORECEBEDOR6008BRASILIA61087007490062\n530515RP12345678-201950300017BR.GOV.BCB.BRCODE01051.0.080450014BR.GOV.BCB.PIX0123PADRAO.URL.PIX/0123AB\nCD81390012BR.COM.OUTRO01190123.ABCD.3456.WXYZ6304EB76\n", 66 | "proxy":"12345678901", 67 | "creditorAccount":{ 68 | "ispb":"12345678", 69 | "issuer":"1774", 70 | "number":"1234567890", 71 | "accountType":"CACC" 72 | } 73 | } 74 | } 75 | } 76 | } 77 | ``` 78 | 79 | **TED** 80 | 81 | ``` 82 | { 83 | "data":{ 84 | "payment":{ 85 | "type":"TED", 86 | "date":"2021-01-01", 87 | "schedule":{ 88 | "single":{ 89 | "date":"2021-01-01" 90 | } 91 | }, 92 | "currency":"BRL", 93 | "amount":"100000.12", 94 | "creditorAccount":{ 95 | "ispb":"12345678", 96 | "issuer":"1774", 97 | "number":"1234567890", 98 | "accountType":"CACC" 99 | }, 100 | "purpose":1, 101 | "purposeAdditionalInfo":"Informações adicionais" 102 | } 103 | } 104 | } 105 | ``` 106 | **Campos novos do payload para TED** 107 | 108 | |**Campo**|**Tipo**|**Requerido**|**Descrição**|Regras de negócio| 109 | |----------|------|---------|--------------------------------------------------------|---------| 110 | |**data.payment.purpose**|enumerado(string) - EnumPurposeTed|sim|Define a finalidade da transferência. O domínio deste enumerado está no [anexo](lista-de-finalidades.txt)|N/A| 111 | |**data.payment.purposeAdditionalInfo**|string|condicionalmente|Define o complemento da finalidade da transferência de forma textual.|[RN301](#regras-de-validação)| 112 | 113 | 114 | **TEF** 115 | ``` 116 | { 117 | "data":{ 118 | "payment":{ 119 | "type":"TEF", 120 | "date":"2021-01-01", 121 | "schedule":{ 122 | "single":{ 123 | "date":"2021-01-01" 124 | } 125 | }, 126 | "currency":"BRL", 127 | "amount":"100000.12", 128 | "creditorAccount":{ 129 | "ispb":"12345678", 130 | "issuer":"1774", 131 | "number":"1234567890", 132 | "accountType":"CACC" 133 | } 134 | } 135 | } 136 | } 137 | ``` 138 | **Campos novos ou alterados do payload para TEF** 139 | 140 | |**Campo**|**Tipo**|**Requerido**|**Descrição**|Regras de negócio| 141 | |----------|------|---------|--------------------------------------------------------|---------| 142 | |**data.payment.creditorAccount**|Object|sim|Conta do destinatário do TEF.|N/A| 143 | 144 | A iniciação de pagamentos para TED não suporta todos os tipos de contas de crédito disponíveis pelo Open Banking, sendo suportado somente conta corrente, poupança e pagamentos ([RN302](#regras-de-validação)). 145 | 146 | O arranjo de TED possui uma grade de horários definida de funcionamento pelo Bacen. Além disso, muitas instituições limitam ainda mais a grade de funcionamento deste arranjo nos seus canais de oferta de TED, portanto esse aspectos precisam ser validados no momento do consentimento ([RN303](#regras-de-validação)). 147 | 148 | Tanto o arranjo TED quanto TEF podem apresentar restrições de limites para transferências estipuladas nas detentoras de conta, devendo isso ser considerado ao criar o consentimento([RN304](#regras-de-validação)). 149 | 150 | As alterações na requisição de criação do consentimento devem refletir também tanto na resposta do endpoint de criação de pagamento quanto na resposta do endpoint de busca do consentimento. 151 | 152 | 153 | ## Ciclo de vida do consentimento 154 | Nenhuma alteração no ciclo de vida do consentimento será mudado para inclusão dos novos arranjos. 155 | 156 | ## Agendamento 157 | Todas regras e fluxos envolvendo o agendamento de pagamentos também se aplicarão aos dois novos arranjos. 158 | 159 | 160 | # Pagamento 161 | 162 | O pagamento representa a execução do consentimento dado pelo cliente. 163 | Ele pode tanto ter uma liquidação imediata quanto pode ser postergada para um momento no futuro definido pelo cliente. 164 | Para dar suporte aos novos arranjos de TED/TEF será necessário a criação de novos endpoints REST que viabilizarão o fluxo de pagamento a partir das iniciadoras de pagamentos se forma análoga ao que hoje já praticado no PIX. 165 | 166 | ## Criar Pagamento 167 | - **Path** : POST - /payments/v1/ted-tef/payments 168 | - **Parâmetros** : 169 | 170 | |Nome|Origem|Tipo|Requerido|Descrição| 171 | |-----------------|----------|------------|---------|---------------------------------------------------------------------------------------------------------------------------| 172 | |**Authorization**|header|string|sim|Cabeçalho HTTP padrão. Permite que as credenciais sejam fornecidas dependendo do tipo de recurso solicitado.| 173 | |**x-fapi-auth-date**|header|string|não|Data em que o usuário logou pela última vez com o receptor. Representada de acordo com a RFC7231.Exemplo: Sun, 10 Sep 2017 19:43:31 UTC| 174 | |**x-fapi-customer-ip-address**|header|string|não|O endereço IP do usuário se estiver atualmente logado com o receptor.| 175 | |**x-fapi-interaction-id**|header|string|não|Um UID RFC4122 usado como um ID de correlação. Se fornecido, o transmissor deve "reproduzir" esse valor no cabeçalho de resposta.| 176 | |**x-idempotency-key**|header|string|sim|Cabeçalho HTTP personalizado. Identificador de solicitação exclusivo para suportar a idempotência.| 177 | |**x-customer-user-agent**|header|string|não|Indica o user-agent que o usuário utiliza.| 178 | |**body**|body|objeto|sim|Dados para a criação do pagamento de TED ou TEF.| 179 | 180 | - **Payload** : 181 | ``` 182 | { 183 | "data":{ 184 | "payment":{ 185 | "amount":"100000.12", 186 | "currency":"BRL" 187 | }, 188 | "creditorAccount":{ 189 | "ispb":"12345678", 190 | "issuer":"1774", 191 | "number":"1234567890", 192 | "accountType":"CACC" 193 | }, 194 | "purpose":1, 195 | "purposeAdditionalInfo":"Informações adicionais" 196 | } 197 | } 198 | ``` 199 | - **Campos** : 200 | 201 | |**Campo**|**Tipo**|**Requerido**|**Descrição**|**Regras de negócio**| 202 | |----------|------|---------|---------------------------------------------------------------------------------------------------------------|---------| 203 | |**data.payment**|objeto - Payment|sim|Representa os dados financeiros do pagamento.|N/A| 204 | |**data.payment.amount**|string|sim|Valor da transação com 2 casas decimais.|N/A| 205 | |**data.payment.currency**|string|sim|Código da moeda nacional segundo modelo ISO-4217, ou seja, 'BRL'. Todos os valores monetários informados estão representados com a moeda vigente do Brasil.|N/A| 206 | |**data.creditorAccount**|objeto - TedTefCreditorAccount|sim|Representa a conta do recebedor da transferência financeira gerada pelo pagamento|N/A| 207 | |**data.creditorAccount.ispb**|string|sim|Representa o ISPB (Identificador do Sistema de Pagamentos Brasileiros) da instituição onde a conta do recebedor é domiciliada|N/A| 208 | |**data.creditorAccount.issuer**|string|condicionalmente|Código da Agência emissora da conta sem dígito. (Agência é a dependência destinada ao atendimento aos clientes, ao público em geral e aos associados de cooperativas de crédito, no exercício de atividades da instituição, não podendo ser móvel ou transitória). |[RN305](#regras-de-validação)| 209 | |**data.creditorAccount.number**|string|sim|Deve ser preenchido com o número da conta do usuário recebedor, com dígito verificador (se este existir), se houver valor alfanumérico, este deve ser convertido para 0.|N/A| 210 | |**data.creditorAccount.accountType**|enumerado(string)|sim|Descreve o tipo da conta que receberá o recursos provenientes da iniciação de pagamentos. Domínio: CACC - Current - Conta Corrente, SLRY - Salary - Conta-Salário, SVGS - Savings - Conta de Poupança, TRAN - TransactingAccount - Conta de Pagamento pré-paga.|N/A| 211 | |**data.purpose**|enumerado(string) - EnumPurposeTed|condicionalmente|Define a finalidade da transferência. O domínio deste enumerado está no [anexo](lista-de-finalidades.txt)|[RN306](#regras-de-validação)| 212 | |**data.purposeAdditionalInfo**|string - max length : 200|condicionalmente|Define o complemento da finalidade da transferência de forma textual.|[RN301](#regras-de-validação)| 213 | 214 | - **Respostas** : 215 | - **HTTP 200**: Pagamento de TED/TEF criado com sucesso. 216 | - **Payload**: 217 | ``` 218 | { 219 | "data":{ 220 | "paymentId":"TXpRMU9UQTROMWhZV2xSU1FUazJSMDl", 221 | "consentId":"urn:bancoex:C1DD33123", 222 | "creationDateTime":"2020-07-21T08:30:00Z", 223 | "statusUpdateDateTime":"2020-07-21T08:30:00Z", 224 | "status":"RJCT", 225 | "payment":{ 226 | "amount":"100000.12", 227 | "currency":"BRL" 228 | }, 229 | "creditorAccount":{ 230 | "ispb":"12345678", 231 | "issuer":"1774", 232 | "number":"1234567890", 233 | "accountType":"CACC" 234 | }, 235 | "purpose":99999, 236 | "purposeAdditionalInfo":"Informações adicionais", 237 | "rejectionReason":"UNEXPECTED_SETTLEMENT_ERROR" 238 | }, 239 | "links":{ 240 | "self":"https://api.banco.com.br/open-banking/api/v1/resource" 241 | }, 242 | "meta":{ 243 | "totalRecords":1, 244 | "totalPages":1, 245 | "requestDateTime":"2021-05-21T08:30:00Z" 246 | } 247 | } 248 | ``` 249 | **Campos** : 250 | 251 | |**Campo**|**Tipo**|**Requerido**|**Descrição**|**Regras de negócio**| 252 | |----------|------|---------|---------------------------------------------------------------------------------------------------------------|---------| 253 | |**data.paymentId**|string|sim|Código ou identificador único informado pela instituição detentora da conta para representar a iniciação de pagamento individual.|N/A| 254 | |**data.consentId**|string|sim|Identificador único do consentimento criado para a iniciação de pagamento solicitada. Deverá ser um URN - Uniform Resource Name. Um URN, conforme definido na RFC8141 é um Uniform Resource Identifier - URI - que é atribuído sob o URI scheme "urn" e um namespace URN específico, com a intenção de que o URN seja um identificador de recurso persistente e independente da localização. Considerando a string urn:bancoex:C1DD33123 como exemplo para consentId temos: - o namespace(urn), o identificador associado ao namespace da instituição transnmissora (bancoex), o identificador específico dentro do namespace (C1DD33123).Informações mais detalhadas sobre a construção de namespaces devem ser consultadas na RFC8141.|N/A| 255 | |**data.creationDateTime**|string(date-time)|sim|Data e hora em que o recurso foi criado. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format).|N/A| 256 | |**data.statusUpdateDateTime**|string(date-time)|sim|Data e hora da última atualização da iniciação de pagamento. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format).|N/A| 257 | |**data.status**|enumerado(string) - [EnumPaymentStatusType](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_EnumPaymentStatusType)|sim|Estado atual da iniciação de pagamento. O estado evolui na seguinte ordem: 1. **PDNG** (PENDING) - Iniciação de pagamento ou transação de pagamento está pendente. Checagens adicionais em realização. ; 2. **SASP** (SCHEDULE_ACCEPTED_SETTLEMENT_IN_PROCESS) - Indica que o processo de agendamento está em processamento. ; 3. **SASC** (SCHEDULE_ACCEPTED_SETTLEMENT_COMPLETED) - Indica que o processo de agendamento foi realizado. ; 4. **PART** (PARTIALLY ACCEPTED) - Aguardando autorização múltipla alçada. ; 5. **ACSP** (ACCEPTED_SETTLEMENT_IN_PROCESS) - Iniciação de pagamento aceita e processamento do pagamento foi iniciado. ; 6. **ACSC** (ACCEPTED_SETTLEMENT_COMPLETED_DEBITOR_ACCOUNT) - Débito realizado na conta do pagador. ; 7. **ACCC** (ACCEPTED_SETTLEMENT_COMPLETED) - Crédito realizado na instituição de destino. ; Em caso insucesso: **RJCT** (REJECTED) - Instrução de pagamento rejeitada.|N/A| 258 | |**data.payment**|objeto - Payment|sim|Representa os dados financeiros do pagamento.|N/A| 259 | |**data.payment.amount**|string|sim|Valor da transação com 2 casas decimais.|N/A| 260 | |**data.payment.currency**|string|sim|Código da moeda nacional segundo modelo ISO-4217, ou seja, 'BRL'. Todos os valores monetários informados estão representados com a moeda vigente do Brasil.|N/A| 261 | |**data.creditorAccount**|objeto - TedTefCreditorAccount|sim|Representa a conta do recebedor da transferência financeira gerada pelo pagamento|N/A| 262 | |**data.creditorAccount.ispb**|string|sim|Representa o ISPB (Identificador do Sistema de Pagamentos Brasileiros) da instituição onde a conta do recebedor é domiciliada|N/A| 263 | |**data.creditorAccount.issuer**|string|condicionalmente|Código da Agência emissora da conta sem dígito. (Agência é a dependência destinada ao atendimento aos clientes, ao público em geral e aos associados de cooperativas de crédito, no exercício de atividades da instituição, não podendo ser móvel ou transitória). |[RN305](#regras-de-validação)| 264 | |**data.creditorAccount.number**|string|sim|Deve ser preenchido com o número da conta do usuário recebedor, com dígito verificador (se este existir), se houver valor alfanumérico, este deve ser convertido para 0.|N/A| 265 | |**data.creditorAccount.accountType**|enumerado(string)|sim|Descreve o tipo da conta que receberá o recursos provenientes da iniciação de pagamentos. Domínio: CACC - Current - Conta Corrente, SLRY - Salary - Conta-Salário, SVGS - Savings - Conta de Poupança, TRAN - TransactingAccount - Conta de Pagamento pré-paga.|N/A| 266 | |**data.purpose**|enumerado(string) - EnumPurposeTed|condicionalmente|Define a finalidade da transferência. O domínio deste enumerado está no [anexo](lista-de-finalidades.txt)|[RN306](#regras-de-validação)| 267 | |**data.purposeAdditionalInfo**|string (alfanumerico) - max length : 200, pattern: ^[a-zA-Z0-9_\s]*$ |condicionalmente|Define o complemento da finalidade da transferência de forma textual.|[RN301](#regras-de-validação)| 268 | |**data.rejectionReason**|enumerado(string) - EnumTedTefRejectionReasonType|condicionalmente| Define o motivo pelo qual o pagamento foi rejeitado. Valores possíveis: [anexo](ted-tef-reject-reason.txt) |[RN306](#regras-de-validação)| 269 | 270 | - **HTTP 422**: Violação de alguma regra de negócio no pagamento de TED/TEF. 271 | - **Schema**: 422ResponseErrorCreateTedTefPayment 272 | - **Payload**: 273 | ``` 274 | { 275 | "errors":[ 276 | { 277 | "code":"SALDO_INSUFICIENTE", 278 | "title":"Saldo insuficiente", 279 | "detail":"Esta conta não possui saldo suficiente para realizar o pagamento" 280 | } 281 | ], 282 | "meta":{ 283 | "totalRecords":1, 284 | "totalPages":1, 285 | "requestDateTime":"2021-05-21T08:30:00Z" 286 | } 287 | } 288 | ``` 289 | 290 | **Campos** : 291 | 292 | |**Campo**|**Tipo**|**Requerido**|**Descrição**|**Regras de negócio**| 293 | |----------|------|---------|---------------------------------------------------------------------------------------------------------------|---------| 294 | |**errors**|array|sim|Contém as violações de negócio na tentativa de criação do pagamento de TED ou TEF .|N/A| 295 | |**errors[n].code**|enumerado - **EnumErrorsCreateTedTefPayment**|sim|Código de erro que representa uma violação de regra de negócio.Domínio em [anexo](422-codes-ted-tef.txt)|N/A| 296 | |**errors[n].title**|string|sim|Título específico do erro reportado, de acordo com o código enviado. Correlação em [anexo](422-titulos-ted-tef.txt)|N/A| 297 | |**errors[n].detail**|string|sim|Descrição específica do erro de acordo com o código reportado. Correlação em [anexo](422-descricoes-ted-tef.txt)|N/A| 298 | |**meta**|object - [Meta](https://sensedia.github.io/areadesenvolvedor/#tocS_Meta)|não|Meta informações referente à API requisitada.|N/A| 299 | 300 | # Regras de negócio 301 | 302 | Nesta sessão serão listadas todas as regras de negócio envolvidas nos endpoints citados nas sessões anteriores. 303 | 304 | ## Regras funcionais 305 | 306 | |**Código**|**Descrição**|**Endpoint**|**Resposta HTTP**|**Código de Erro**|**Título**|**Mensagem**|**Schema**| 307 | |----------|------------------------------------------------------------------------------------------------------------------------------------------|-----------------|-------|----------------|--------------------------|-----------------------------|--------------------------| 308 | 309 | ## Regras de validação 310 | 311 | |**Código**|**Descrição**|**Endpoint**|**Resposta HTTP**|**Código de Erro**|**Título**|**Mensagem**|**Schema**| 312 | |----------|------------------------------------------------------------------------------------------------------------------------------------------|-----------------|-------|----------------|--------------------------|-----------------------------|--------------------------| 313 | |**RN301**|O campo **data.payment.purposeAdditionalInfo** deverá ser preenchido apenas quando a **data.payment.purpose** tiver o valor 99999 - Outros|[Criar consentimento](#criar-consentimento)|422|**DETALHE_PGTO_INVALIDO**|Consentimento inválido|Complemento de finalidade requerida|[422ResponseErrorCreateConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_422ResponseErrorCreateConsent)| 314 | |**RN302**|O campo **data.payment.creditorAccount.accountType** quando o arranjo alvo for TED só suportará os tipos **CACC** (Conta corrente), **SVGS** (Poupança) e **TRAN** (Conta de Pagamento pré-paga) |[Criar consentimento](#criar-consentimento)|422|**TIPO_CONTA_NAO_SUPORTADO**|Consentimento inválido|Tipo de conta não suportado pelo arranjo alvo|[422ResponseErrorCreateConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_422ResponseErrorCreateConsent)| 315 | |**RN303**|A detentora de conta deve validar se o consentimento para pagamento de TED está dentro de sua grade funcionamento para o arranjo|[Criar consentimento](#criar-consentimento)|422|**JANELA_HORARIO_NAO_PERMITIDA**|Consentimento inválido|Janela de horário do arranjo de pagamento alvo não permitida|[422ResponseErrorCreateConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_422ResponseErrorCreateConsent)| 316 | |**RN304**|A detentora de conta deve validar se o consentimento para pagamento de TED ou TEF está com o valor dentro dos limites de transferência por ela estabelecidos|[Criar consentimento](#criar-consentimento)|422|**VALOR_ACIMA_LIMITE**|Consentimento inválido|O valor (ou quantidade de transações) ultrapassa a faixa de limite parametrizada na detentora para permitir a realização de transações pelo cliente.|[422ResponseErrorCreateConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_422ResponseErrorCreateConsent)| 317 | |**RN305**|O campo **data.creditorAccount.issuer** só é suportado pelos tipos de conta **CACC**, **SVGS** e **SLRY** e portanto obrigatório apenas nestes casos.|[Criar pagamento](#criar-pagamento)|422|**AGENCIA_REQUERIDA**|Pagamento inválido|O tipo de conta alvo requer as informações de agência|**422ResponseErrorCreateTedTefPayment**| 318 | |**RN306**|O campo **data.purpose** é obrigatório quando o tipo de pagamento for do arranjo TED|[Criar pagamento](#criar-pagamento)|422|**FINALIDADE_REQUERIDA**|Pagamento inválido|Finalidade é requerida para o pagamento no arranjo alvo|**422ResponseErrorCreateTedTefPayment**| 319 | 320 | 321 | # Documentação da api e swagger 322 | 323 | Nesta sessão é destinada a apontamentos para melhorias da documentação das apis, links com informações úteis e quaisquer informações que possam auxiliar neste contexto. 324 | 325 | - **Herança e polimorfismo**: As alterações propostas neste documento fazem uso desta técnica documentada no Open API [aqui](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/) . 326 | - **Descrição de enumerados**: As apis do Open Banking fazem uso muitas vezes de dados com domínios discretos expressados em forma de enumerados. Para facilitar a leitura destes tipos de dados onde a uma descrição semântica de cada valor pertencente ao enumerado recomendamos usar a abordagem abaixo. 327 | - Exemplo 328 | ``` 329 | properties: 330 | code: 331 | type: string 332 | maxLength: 21 333 | enum: 334 | - FORMA_PGTO_INVALIDA 335 | - DATA_PGTO_INVALIDA 336 | - DETALHE_PGTO_INVALIDO 337 | - NAO_INFORMADO 338 | - INVALID_SCHEDULE 339 | example: FORMA_PGTO_INVALIDA 340 | description: > 341 | Códigos de erros previstos na criação de consentimento para a iniciação de pagamentos: 342 | 343 | * `FORMA_PGTO_INVALIDA`- Forma de pagamento inválida. 344 | 345 | * `DATA_PGTO_INVALIDA` - Data de pagamento inválida. 346 | 347 | * `DETALHE_PGTO_INVALIDO` - Detalhe do pagamento inválido. 348 | 349 | * `NAO_INFORMADO` - Não informado. 350 | 351 | * `AGENDAMENTO_INVALIDO` - Agendamento inválido. 352 | 353 | ``` 354 | - **Resultado da renderização no swagger editor** : 355 | ![Renderização dos enums](renderizacao-enum.png) 356 | -------------------------------------------------------------------------------- /ted-tef-reject-reason.txt: -------------------------------------------------------------------------------- 1 | PAYMENT_LIMIT_EXCEEDED - Indica que o pagamento foi rejeitado por ter um valor maior ou quantidade pagamentos supere o limite pré-estabelecido pela detentora de conta. 2 | CONSENT_DATA_MISMATCH - Indica que o pagamento foi rejeitado devido aos incompatibilidade com os dados do consentimento associado 3 | CONSENT_STATUS_NOT_ALLOWED - Indica que o pagamento foi rejeitado devido ao consentimento vinculado não estar em estado esperado pelo fluxo de pagamento. 4 | INSUFFICIENT_FUNDS - Indica que o pagamento foi rejeitado por insuficiência de fundos na conta do pagador. 5 | PAYMENT_OUTSIDE_ALLOWED_TIMETABLE - Indica que o pagamento foi rejeitado devido ao fato da janela de horário de pagamentos permitida do arranjo enccerrou. 6 | CONSENT_REVOKED - Indica que o pagamento agendado foi rejeitado devido a revogação do consentimento vinculado 7 | UNEXPECTED_SETTLEMENT_ERROR - Indica que ocorreu um problema inesperado na liquidação do pagamento junto ao arranjo alvo 8 | UNEXPECTED_ERROR - Indica que o pagamento foi rejeitado por uma situação não informada pela detentora 9 | -------------------------------------------------------------------------------- /tef-proxy-proposta.md: -------------------------------------------------------------------------------- 1 | #Indices 2 | 3 | - [Introdução](#introdução) 4 | - [Criar consentimento](#criar-consentimento) 5 | - [Regras de negócio](#regras-de-negcio) 6 | 7 | #Introdução 8 | 9 | A iniciação de pagamento para TEF permite que a iniciadora informe a conta de destino diretamente ou o proxy (identificador da conta na instituição ) no momento da iniciação. 10 | Caso a detentora de conta identifique a conta informada pelo Alias e a jornada de consentimento se concretiza, a detentora deverá retonar no payload de response o objeto creditorAccount com a informação da conta associada ao proxy informado. 11 | Importante atentar que a iniciadora deverá utilizar o creditorAccount retornado para prosseguir com a transação. 12 | 13 | ## Criar consentimento 14 | - **Path** : POST - /payments/v1/consents 15 | - **Request Payload** : [CreatePaymentConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_CreatePaymentConsent) 16 | - **HTTP 200 Response Payload**: [ResponsePaymentConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_ResponsePaymentConsent) 17 | - **HTTP 422 Response Payload**: [422ResponseErrorCreateConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_422ResponseErrorCreateConsent) 18 | 19 | **TEF** 20 | ``` 21 | { 22 | "data":{ 23 | "payment":{ 24 | "type":"TEF", 25 | "date":"2021-01-01", 26 | "schedule":{ 27 | "single":{ 28 | "date":"2021-01-01" 29 | } 30 | }, 31 | "currency":"BRL", 32 | "amount":"100000.12", 33 | "proxy":"xpot@xpot.com.br", 34 | "creditorAccount":{ 35 | "ispb":"12345678", 36 | "issuer":"1774", 37 | "number":"1234567890", 38 | "accountType":"CACC" 39 | } 40 | } 41 | } 42 | } 43 | ``` 44 | **Campos novos ou alterados do payload para TEF** 45 | 46 | |**Campo**|**Tipo**|**Requerido**|**Descrição**|Regras de negócio| 47 | |----------|------|---------|--------------------------------------------------------|---------| 48 | |**data.payment.proxy**|string|condicionalmente|Alias utilizado pela instituição para identificar a conta de destino do transferência. Mutuamente exclusivo com o campo data.payment.creditorAccount|[RN307](#regras-de-validação), [RN308](#regras-de-validação), [RN309](#regras-de-validação)| 49 | |**data.payment.creditorAccount**|Object|condicionalmente|Conta do destinatário do TEF. Mutuamente exclusivo com o campo data.payment.proxy|[RN307](#regras-de-validação)| 50 | 51 | ## Regras de negocio 52 | 53 | |**Código**|**Descrição**|**Endpoint**|**Resposta HTTP**|**Código de Erro**|**Título**|**Mensagem**|**Schema**| 54 | |----------|------------------------------------------------------------------------------------------------------------------------------------------|-----------------|-------|----------------|--------------------------|-----------------------------|--------------------------| 55 | |**RN307**|O campo **data.payment.proxy** e **data.payment.creditorAccount** para o contexto de TEF são mutuamente exclusivos entre si.|[Criar consentimento](#criar-consentimento)|422|**DETALHE_PGTO_INVALIDO**|Consentimento inválido|O campo proxy ou creditorAccount devem ser informados|[422ResponseErrorCreateConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_422ResponseErrorCreateConsent)| 56 | |**RN308**|Caso o campo **data.payment.proxy** para o contexto de TEF não seja suportado pela detentora a mesma deve retornar uma mensagem de erro.|[Criar consentimento](#criar-consentimento)|422|**IDENTIFICADOR_DE_CONTA_NAO_SUPORTADO**|Consentimento inválido|Alias de conta não suportado|[422ResponseErrorCreateConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_422ResponseErrorCreateConsent)| 57 | |**RN309**|Caso uma conta não for encontrada quando o valor do campo **data.payment.proxy** for fornecido a detentora deve comunicar um erro.|[Criar consentimento](#criar-consentimento)|422|**CONTA_NAO_ENCONTRADA**|Consentimento inválido|Conta não encontrada com o alias informado|[422ResponseErrorCreateConsent](https://openbanking-brasil.github.io/areadesenvolvedor/#tocS_422ResponseErrorCreateConsent)| 58 | --------------------------------------------------------------------------------