openapi: 3.0.0 info: title: API Payment Initiation - Open Banking Brasil description: | API de Iniciação de Pagamentos, responsável por viabilizar as operações de iniciação de pagamentos para o Open Banking Brasil. Para cada uma das formas de pagamento previstas é necessário obter prévio consentimento do cliente através dos `endpoints` dedicados ao consentimento nesta API. # Orientações No diretório de participantes duas `Roles` estão relacionadas à presente API: - `CONTA`, referente às instituições detentoras de conta participantes do Open Banking Brasil; - `PAGTO`, referente às instituições iniciadoras de transação de pagamento de conta participantes do Open Banking Brasil. Os tokens utilizados para consumo dos `endpoints` desta API devem possuir os `scopes` `openid` e `payments`. Esta API não requer a implementação de `permissions` para sua utilização. Todas as requisições e respostas devem ser assinadas seguindo o protocolo estabelecido na sessão Assinaturas do guia de segurança. ## Assinatura de payloads No contexto da API Payment Initiation, os `payloads` de mensagem que trafegam tanto por parte da instituição iniciadora de transação de pagamento quanto por parte da instituição detentora de conta devem estar assinados. Para o processo de assinatura destes `payloads` as instituições devem seguir as especificações de segurança publicadas no Portal do desenvolvedor: - Certificados exigidos para assinatura de mensagens: [Padrões de certificados digitais Open Banking Brasil](https://github.com/OpenBanking-Brasil/specs-seguranca/blob/main/open-banking-brasil-certificate-standards-1_ID1.md#certificado-de-assinatura-certificadoassinatura) - Como assinar o payload JWS: [https://openbanking-brasil.github.io/areadesenvolvedor/#como-assinar-o-payload](https://openbanking-brasil.github.io/areadesenvolvedor/#como-assinar-o-payload) ## Controle de acesso O endpoint de consulta de pagamento GET /pix/payments/{​​​paymentId}​​​ deve suportar acesso a partir de access_token emitido por meio de um grant_type do tipo `client credentials`, como opção do uso do token vinculado ao consentimento (hybrid flow). Para evitar vazamento de informação, a detentora deve validar que o pagamento consultado pertence ao ClientId que o criou e, caso haja divergências, retorne um erro HTTP 400. version: 1.0.1-rc1.0 license: name: Apache 2.0 url: 'https://www.apache.org/licenses/LICENSE-2.0' contact: name: Governança do Open Banking Brasil – Especificações email: gt-interfaces@openbankingbr.org url: 'https://openbanking-brasil.github.io/areadesenvolvedor/' servers: - url: 'https://api.banco.com.br/open-banking/payments/v1' description: Servidor de Produção - url: 'https://apih.banco.com.br/open-banking/payments/v1' description: Servidor de Homologação tags: - name: Pagamentos paths: /consents: post: tags: - Pagamentos summary: Criar consentimento para a iniciação de pagamento. operationId: paymentsPostConsents description: Método de criação do consentimento para a iniciação de pagamento. parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/xFapiAuthDate' - $ref: '#/components/parameters/xFapiCustomerIpAddress' - $ref: '#/components/parameters/xFapiInteractionId' - $ref: '#/components/parameters/xCustomerUserAgent' - $ref: '#/components/parameters/XIdempotencyKey' requestBody: content: application/jwt: schema: $ref: '#/components/schemas/CreatePaymentConsent' description: Payload para criação do consentimento para iniciação do pagamento. required: true responses: '201': $ref: '#/components/responses/201PaymentsConsentsConsentCreated' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '406': $ref: '#/components/responses/NotAcceptable' '415': $ref: '#/components/responses/UnsupportedMediaType' '422': $ref: '#/components/responses/UnprocessableEntityConsents' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' default: description: Erro inesperado. content: application/json: schema: $ref: '#/components/schemas/ResponseError' security: - OpenId: - openid OAuth2ClientCredentials: - payments '/consents/{consentId}': get: tags: - Pagamentos summary: Consultar consentimento para iniciação de pagamento. operationId: paymentsGetConsentsConsentId description: Método para consulta do consentimento para a iniciação de pagamento. parameters: - $ref: '#/components/parameters/consentId' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/xFapiAuthDate' - $ref: '#/components/parameters/xFapiCustomerIpAddress' - $ref: '#/components/parameters/xFapiInteractionId' - $ref: '#/components/parameters/xCustomerUserAgent' responses: '200': $ref: '#/components/responses/200PaymentsConsentsConsentIdRead' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '406': $ref: '#/components/responses/NotAcceptable' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' default: description: Erro inesperado. content: application/json: schema: $ref: '#/components/schemas/ResponseError' security: - OAuth2ClientCredentials: - payments /pix/payments: post: tags: - Pagamentos summary: Criar iniciação de pagamento. operationId: paymentsPostPixPayments description: Método para criar uma iniciação de pagamento. parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/xFapiAuthDate' - $ref: '#/components/parameters/xFapiCustomerIpAddress' - $ref: '#/components/parameters/xFapiInteractionId' - $ref: '#/components/parameters/xCustomerUserAgent' - $ref: '#/components/parameters/XIdempotencyKey' requestBody: content: application/jwt: schema: $ref: '#/components/schemas/CreatePixPayment' description: Payload para criação da iniciação do pagamento Pix. required: true responses: '201': $ref: '#/components/responses/201PaymentsInitiationPixPaymentCreated' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '406': $ref: '#/components/responses/NotAcceptable' '415': $ref: '#/components/responses/UnsupportedMediaType' '422': $ref: '#/components/responses/UnprocessableEntityPixPayments' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' default: description: Erro inesperado. content: application/json: schema: $ref: '#/components/schemas/ResponseError' security: - OAuth2AuthorizationCode: - 'consent:consentId' - payments '/pix/payments/{paymentId}': get: tags: - Pagamentos summary: Consultar iniciação de pagamento. operationId: paymentsGetPixPaymentsPaymentId description: Método para consultar uma iniciação de pagamento. parameters: - $ref: '#/components/parameters/paymentId' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/xFapiAuthDate' - $ref: '#/components/parameters/xFapiCustomerIpAddress' - $ref: '#/components/parameters/xFapiInteractionId' - $ref: '#/components/parameters/xCustomerUserAgent' responses: '200': $ref: '#/components/responses/200PaymentsInitiationPixPaymentIdRead' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '406': $ref: '#/components/responses/NotAcceptable' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' default: description: Erro inesperado. content: application/json: schema: $ref: '#/components/schemas/ResponseError' security: - OAuth2AuthorizationCode: - payments - OAuth2ClientCredentials: - payments components: schemas: 422ResponseErrorCreateConsent: type: object required: - errors properties: errors: type: array minItems: 1 maxItems: 3 items: type: object required: - code - title - detail properties: code: $ref: '#/components/schemas/EnumErrorsCreateConsent' title: type: string maxLength: 255 pattern: \w*\W* example: Forma de pagamento inválida. description: | Título específico do erro reportado, de acordo com o código enviado: • FORMA_PGTO_INVALIDA: Forma de pagamento inválida. • DATA_PGTO_INVALIDA: Data de pagamento inválida. • DETALHE_PGTO_INVALIDO: Detalhe do pagamento inválido. • NAO_INFORMADO: Não informado. detail: type: string maxLength: 2048 pattern: \w*\W* example: Meio de pagamento inválido. description: | Descrição específica do erro de acordo com o código reportado: • FORMA_PGTO_INVALIDA – Meio de pagamento inválido. • DATA_PGTO_INVALIDA – Data de pagamento inválida no contexto, por exemplo, data no passado. Para pagamentos únicos deve ser informada a data atual, do dia corrente. • DETALHE_PGTO_INVALIDO: O campo [nome_campo] não atende os requisitos de preenchimento. • NAO_INFORMADO – Não reportado/identificado pela instituição detentora de conta. additionalProperties: false meta: $ref: '#/components/schemas/Meta' additionalProperties: false 422ResponseErrorCreatePixPayment: type: object required: - errors properties: errors: type: array minItems: 1 maxItems: 9 items: type: object required: - code - title - detail properties: code: $ref: '#/components/schemas/EnumErrorsCreatePayment' title: type: string maxLength: 255 pattern: \w*\W* example: Saldo insuficiente. description: | Título específico do erro reportado, de acordo com o código enviado: • SALDO_INSUFICIENTE: Saldo insuficiente. • BENEFICIARIO_INCOMPATIVEL: Beneficiário incompatível. • VALOR_INCOMPATIVEL: Valor da transação incompatível. • VALOR_ACIMA_LIMITE: Acima do limite estabelecido. • VALOR_INVALIDO: Valor inválido. • COBRANCA_INVALIDA: Cobrança inválida. • CONSENTIMENTO_INVALIDO: Consentimento inválido. • JANELA_OPER_INVALIDA: Janela de operação inválida. • NAO_INFORMADO: Não informado. detail: type: string maxLength: 2048 pattern: \w*\W* example: A conta selecionada não possui saldo suficiente para realizar o pagamento. description: | Descrição específica do erro de acordo com o código reportado: • SALDO_INSUFICIENTE: A conta selecionada não possui saldo suficiente para realizar o pagamento. • BENEFICIARIO_INCOMPATIVEL: O beneficiário informado no consentimento não é o mesmo do esperado pelo DICT. • VALOR_INCOMPATIVEL: O valor informado no consentimento não é o mesmo valor do informado no payload de pagamento. • VALOR_ACIMA_LIMITE: 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. • VALOR_INVALIDO: O valor enviado não é válido para o QR Code informado. • COBRANCA_INVALIDA: Validação de expiração, validação de vencimento ou Status Válido. • CONSENTIMENTO_INVALIDO: Consentimento inválido (status diferente de "AUTHORISED" ou está expirado). • JANELA_OPER_INVALIDA: Requisição está fora da janela de funcionamento. • NAO_INFORMADO: Não reportado/identificado pela instituição detentora de conta. additionalProperties: false meta: $ref: '#/components/schemas/Meta' additionalProperties: false BusinessEntity: type: object description: 'Usuário (pessoa jurídica) que encontra-se logado na instituição Iniciadora de Pagamento. [Restrição] Preenchimento obrigatório se usuário logado na instituição Iniciadora de Pagamento for um CNPJ (pessoa jurídica).' additionalProperties: false required: - document properties: document: type: object additionalProperties: false required: - identification - rel properties: identification: type: string maxLength: 14 description: Número do documento de identificação oficial do titular pessoa jurídica. example: '11111111111111' pattern: '^\d{14}$' rel: type: string maxLength: 4 description: Tipo do documento de identificação oficial do titular pessoa jurídica. example: CNPJ pattern: '^[A-Z]{4}$' CreatePaymentConsent: type: object required: - data properties: data: type: object description: Objeto contendo as informações de consentimento para a iniciação de pagamento individual. required: - loggedUser - creditor - payment properties: loggedUser: $ref: '#/components/schemas/LoggedUser' businessEntity: $ref: '#/components/schemas/BusinessEntity' creditor: $ref: '#/components/schemas/Identification' payment: $ref: '#/components/schemas/PaymentConsent' debtorAccount: $ref: '#/components/schemas/DebtorAccount' additionalProperties: false additionalProperties: false CreatePixPayment: type: object required: - data properties: data: $ref: '#/components/schemas/CreatePixPaymentData' additionalProperties: false CreatePixPaymentData: type: object description: Objeto contendo dados do pagamento e do recebedor (creditor). required: - localInstrument - payment - creditorAccount - cnpjInitiator properties: localInstrument: $ref: '#/components/schemas/EnumLocalInstrument' payment: $ref: '#/components/schemas/PaymentPix' creditorAccount: $ref: '#/components/schemas/CreditorAccount' remittanceInformation: type: string maxLength: 140 pattern: '[\w\W\s]*' example: Pagamento da nota XPTO035-002. description: | Deve ser preenchido sempre que o usuário pagador inserir alguma informação adicional em um pagamento, a ser enviada ao recebedor. qrCode: type: string maxLength: 512 pattern: '[\w\W\s]*' example: | 00020104141234567890123426660014BR.GOV.BCB.PIX014466756C616E6F32303139406578616D706C652E636F6D27300012 BR.COM.OUTRO011001234567895204000053039865406123.455802BR5915NOMEDORECEBEDOR6008BRASILIA61087007490062 530515RP12345678-201950300017BR.GOV.BCB.BRCODE01051.0.080450014BR.GOV.BCB.PIX0123PADRAO.URL.PIX/0123AB CD81390012BR.COM.OUTRO01190123.ABCD.3456.WXYZ6304EB76 description: | Obs: Campo reservado para uso futuro. Sequência de caracteres que corresponde ao QR Code disponibilizado para o pagador. É a sequência de caracteres que seria lida pelo leitor de QR Code, e deve propiciar o retorno dos dados do pagador após consulta na DICT. Essa funcionalidade é possível tanto para QR Code estático quanto para QR Code dinâmico. No arranjo do Pix esta é a mesma sequência gerada e/ou lida pela funcionalidade Pix Copia e Cola. Este campo deverá ser no formato UTF-8. [Restrição] Preenchimento obrigatório para pagamentos por QR Code, observado o tamanho máximo de 512 bytes. proxy: type: string maxLength: 77 pattern: '[\w\W\s]*' example: '12345678901' description: | Chave cadastrada no DICT pertencente ao recebedor. Os tipos de chaves podem ser: telefone, e-mail, cpf/cnpj ou chave aleatória. No caso de telefone celular deve ser informado no padrão E.1641. Para e-mail deve ter o formato xxxxxxxx@xxxxxxx.xxx(.xx) e no máximo 77 caracteres. No caso de CPF deverá ser informado com 11 números, sem pontos ou traços. Para o caso de CNPJ deverá ser informado com 14 números, sem pontos ou traços. No caso de chave aleatória deve ser informado o UUID gerado pelo DICT, conforme formato especificado na RFC41223. Se informado, a detentora da conta deve validar o proxy no DICT quando localInstrument for igual a DICT, QRDN (uso futuro) ou QRES (uso futuro) e validar o campo creditorAccount. Esta validação é opcional caso o localInstrument for igual a INIC. [Restrição] Se localInstrument for igual a MANU, o campo proxy não deve ser preenchido. Se localInstrument for igual INIC, DICT, QRDN (uso futuro) ou QRES (uso futuro), o campo proxy deve ser sempre preenchido com a chave Pix. cnpjInitiator: type: string pattern: '^\d{14}$' maxLength: 14 example: '50685362000135' description: CNPJ do Iniciador de Pagamento devidamente habilitado para a prestação de Serviço de Iniciação no Pix. transactionIdentification: type: string pattern: '^[a-zA-Z0-9][a-zA-Z0-9]{0,24}$' maxLength: 25 example: E00038166201907261559y6j6 description: | Trata-se de um identificador de transação que deve ser retransmitido intacto pelo PSP do pagador ao gerar a ordem de pagamento. Essa informação permitirá ao recebedor identificar e correlacionar a transferência, quando recebida, com a apresentação das instruções ao pagador. Os caracteres permitidos no contexto do Pix para o campo txid (EMV 62-05) são: - Letras minúsculas, de ‘a’ a ‘z’ - Letras maiúsculas, de ‘A’ a ‘z’ - Dígitos decimais, de ‘0’ a ‘9’ [Restrição] Se localInstrument for igual a INIC, o campo transactionIdentification deve ser preenchido obrigatoriamente. Se localInstrument for igual a MANU ou DICT, o campo transactionIdentification não deve ser preenchido. A detentora de conta deve validar se a condicionalidade do campo foi atendida pela iniciadora de pagamento. additionalProperties: false CreditorAccount: type: object description: | Objeto que contém a identificação da conta de destino do beneficiário/recebedor. required: - ispb - number - accountType properties: ispb: type: string minLength: 8 maxLength: 8 pattern: '^[0-9]{8}$' example: '12345678' description: | Deve ser preenchido com o ISPB (Identificador do Sistema de Pagamentos Brasileiros) do participante do SPI (Sistema de pagamentos instantâneos) somente com números. issuer: type: string maxLength: 4 pattern: '^\d{4}$' example: '1774' description: | 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). [Restrição] Preenchimento obrigatório para os seguintes tipos de conta: CACC (CONTA_DEPOSITO_A_VISTA), SVGS (CONTA_POUPANCA) e SLRY (CONTA_SALARIO). number: type: string minLength: 3 maxLength: 20 pattern: '^\d{3,20}$' example: '1234567890' description: | 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. accountType: $ref: '#/components/schemas/EnumAccountPaymentsType' additionalProperties: false DebtorAccount: type: object description: | Objeto que contém a identificação da conta de origem do pagador. As informações quanto à conta de origem do pagador poderão ser trazidas no consentimento para a detentora, caso a iniciadora tenha coletado essas informações do cliente. Do contrário, será coletada na detentora e trazida para a iniciadora como resposta à criação do pagamento. required: - ispb - number - accountType properties: ispb: type: string minLength: 8 maxLength: 8 pattern: '^[0-9]{8}$' example: '12345678' description: | Deve ser preenchido com o ISPB (Identificador do Sistema de Pagamentos Brasileiros) do participante do SPI (Sistema de pagamentos instantâneos) somente com números. issuer: type: string maxLength: 4 pattern: '^\d{4}$' example: '1774' description: | 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). [Restrição] Preenchimento obrigatório para os seguintes tipos de conta: CACC (CONTA_DEPOSITO_A_VISTA), SVGS (CONTA_POUPANCA) e SLRY (CONTA_SALARIO). number: type: string minLength: 3 maxLength: 20 pattern: '^\d{3,20}$' example: '1234567890' description: | Deve ser preenchido com o número da conta transacional do usuário pagador, com dígito verificador (se este existir), se houver valor alfanumérico, este deve ser convertido para 0. accountType: $ref: '#/components/schemas/EnumAccountPaymentsType' additionalProperties: false Details: type: object description: | Objeto contendo os detalhes do pagamento. required: - localInstrument - creditorAccount properties: localInstrument: $ref: '#/components/schemas/EnumLocalInstrument' qrCode: type: string maxLength: 512 pattern: '[\w\W\s]*' example: | 00020104141234567890123426660014BR.GOV.BCB.PIX014466756C616E6F32303139406578616D706C652E636F6D27300012 BR.COM.OUTRO011001234567895204000053039865406123.455802BR5915NOMEDORECEBEDOR6008BRASILIA61087007490062 530515RP12345678-201950300017BR.GOV.BCB.BRCODE01051.0.080450014BR.GOV.BCB.PIX0123PADRAO.URL.PIX/0123AB CD81390012BR.COM.OUTRO01190123.ABCD.3456.WXYZ6304EB76 description: | Obs: Campo reservado para uso futuro. Sequência de caracteres que corresponde ao QR Code disponibilizado para o pagador. É a sequência de caracteres que seria lida pelo leitor de QR Code, e deve propiciar o retorno dos dados do pagador após consulta na DICT. Essa funcionalidade é possível tanto para QR Code estático quanto para QR Code dinâmico. No arranjo do Pix esta é a mesma sequência gerada e/ou lida pela funcionalidade Pix Copia e Cola. Este campo deverá ser no formato UTF-8. [Restrição] Preenchimento obrigatório para pagamentos por QR Code, observado o tamanho máximo de 512 bytes. proxy: type: string maxLength: 77 pattern: '[\w\W\s]*' example: '12345678901' description: | Chave cadastrada no DICT pertencente ao recebedor. Os tipos de chaves podem ser: telefone, e-mail, cpf/cnpj ou chave aleatória. No caso de telefone celular deve ser informado no padrão E.1641. Para e-mail deve ter o formato xxxxxxxx@xxxxxxx.xxx(.xx) e no máximo 77 caracteres. No caso de CPF deverá ser informado com 11 números, sem pontos ou traços. Para o caso de CNPJ deverá ser informado com 14 números, sem pontos ou traços. No caso de chave aleatória deve ser informado o UUID gerado pelo DICT, conforme formato especificado na RFC41223. Se informado, a detentora da conta deve validar o proxy no DICT quando localInstrument for igual a DICT, QRDN (uso futuro) ou QRES (uso futuro) e validar o campo creditorAccount. Esta validação é opcional caso o localInstrument for igual a INIC. [Restrição] Se localInstrument for igual a MANU, o campo proxy não deve ser preenchido. Se localInstrument for igual INIC, DICT, QRDN (uso futuro) ou QRES (uso futuro), o campo proxy deve ser sempre preenchido com a chave Pix. creditorAccount: $ref: '#/components/schemas/CreditorAccount' additionalProperties: false EndToEndId: type: string minLength: 32 maxLength: 32 pattern: '^([E])([0-9]{8})([0-9]{4})(0[1-9]|1[0-2])(0[1-9]|[1-2][0-9]|3[0-1])(2[0-3]|[01][0-9])([0-5][0-9])([a-zA-Z0-9]{11})$' example: E9040088820210128000800123873170 description: | Deve ser preenchido no formato padrão ExxxxxxxxyyyyMMddHHmmkkkkkkkkkkk (32 caracteres; “case sensitive”, isso é, diferencia letras maiúsculas e minúsculas), sendo: • “E” – fixo (1 caractere); • xxxxxxxx – identificação do agente que gerou o ´EndToEndId´, podendo ser: o ISPB do participante direto ou o ISPB do participante indireto (8 caracteres numéricos [0-9]); • yyyyMMddHHmm – data, hora e minuto (12 caracteres), seguindo o horário UTC, da submissão da ordem de pagamento, caso a liquidação seja prioritária, ou prevista para o envio da ordem ao sistema de liquidação, caso seja realizado um agendamento. Para ordens prioritárias e não prioritárias, aceita-se o preenchimento, pelo agente que gerou o ´EndToEndId´, com uma tolerância máxima de 12 horas, para o futuro e para o passado, em relação ao horário efetivo de processamento da ordem pelo SPI; • kkkkkkkkkkk – sequencial criado pelo agente que gerou o ´EndToEndId´ (11 caracteres alfanuméricos [a-z/A-Z/0-9]). Deve ser único dentro de cada “yyyyMMddHHmm”. Admite-se que o ´EndToEndId´ seja gerado pelo participante direto, pelo participante indireto ou pelo iniciador de pagamento. Ele deve ser único, não podendo ser repetido em qualquer outra operação enviada ao SPI. [Restrição] O ´EndToEndId´ deve ser informado obrigatoriamente caso o status do pagamento seja ACCEPTED_SETTLEMENT_COMPLETED. EnumAccountPaymentsType: type: string maxLength: 4 enum: - CACC - SLRY - SVGS - TRAN example: CACC description: | Tipos de contas usadas para pagamento via Pix. Modalidades tradicionais previstas pela Resolução 4.753, não contemplando contas vinculadas, conta de domiciliados no exterior, contas em moedas estrangeiras e conta correspondente moeda eletrônica. Segue descrição de cada valor do ENUM para o escopo do Pix. CACC - Current - Conta Corrente. SLRY - Salary - Conta-Salário. SVGS - Savings - Conta de Poupança. TRAN - TransactingAccount - Conta de Pagamento pré-paga. EnumAuthorisationStatusType: type: string maxLength: 22 enum: - AWAITING_AUTHORISATION - AUTHORISED - REJECTED - CONSUMED example: AWAITING_AUTHORISATION description: | Retorna o estado do consentimento, o qual no momento de sua criação será AWAITING_AUTHORISATION. Este estado será alterado depois da autorização do consentimento na detentora da conta do pagador (Debtor) para AUTHORISED ou REJECTED. O consentimento fica no estado CONSUMED após ocorrer a iniciação do pagamento referente ao consentimento. Em caso de consentimento expirado a detentora deverá retornar o status REJECTED. Estados possíveis: AWAITING_AUTHORISATION - Aguardando autorização AUTHORISED - Autorizado REJECTED - Rejeitado CONSUMED - Consumido EnumErrorsCreateConsent: type: string maxLength: 21 enum: - FORMA_PGTO_INVALIDA - DATA_PGTO_INVALIDA - DETALHE_PGTO_INVALIDO - NAO_INFORMADO example: FORMA_PGTO_INVALIDA description: | Códigos de erros previstos na criação de consentimento para a iniciação de pagamentos: • FORMA_PGTO_INVALIDA: Forma de pagamento inválida. • DATA_PGTO_INVALIDA: Data de pagamento inválida. • DETALHE_PGTO_INVALIDO: Detalhe do pagamento inválido. • NAO_INFORMADO: Não informado. EnumErrorsCreatePayment: type: string maxLength: 25 enum: - SALDO_INSUFICIENTE - BENEFICIARIO_INCOMPATIVEL - VALOR_INCOMPATIVEL - VALOR_ACIMA_LIMITE - VALOR_INVALIDO - COBRANCA_INVALIDA - CONSENTIMENTO_INVALIDO - JANELA_OPER_INVALIDA - NAO_INFORMADO example: SALDO_INSUFICIENTE description: | Códigos de erros previstos na criação da iniciação de pagamento: • SALDO_INSUFICIENTE – Esta conta não possui saldo suficiente para realizar o pagamento. • BENEFICIARIO_INCOMPATIVEL – O beneficiário informado no consentimento não é o mesmo do esperado pelo DICT. • VALOR_INCOMPATIVEL – O valor informado no consentimento não é o mesmo valor do informado no payload de pagamento. • VALOR_ACIMA_LIMITE – 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. • VALOR_INVALIDO – O valor enviado não é válido para o QR Code informado. • COBRANCA_INVALIDA – Validação de expiração, validação de vencimento, Status Válido. • CONSENTIMENTO_INVALIDO – Consentimento inválido (status não é "authorised" ou está expirado). • JANELA_OPER_INVALIDA – Requisição está fora da janela de funcionamento. • NAO_INFORMADO – Não informada pela detentora de conta. EnumLocalInstrument: type: string maxLength: 4 enum: - MANU - DICT - QRDN - QRES - INIC example: DICT description: | Especifica a forma de iniciação do pagamento: - MANU - Inserção manual de dados da conta transacional - DICT - Inserção manual de chave Pix - QRDN - QR code dinâmico (*Domínio reservado para uso futuro*) - QRES - QR code estático (*Domínio reservado para uso futuro*) - INIC - Indica que o recebedor (creditor) contratou o Iniciador de Pagamentos especificamente para realizar iniciações de pagamento em que o beneficiário é previamente conhecido. EnumPaymentPersonType: type: string maxLength: 15 enum: - PESSOA_NATURAL - PESSOA_JURIDICA description: | Titular, pessoa natural ou juridica a quem se referem os dados de recebedor (creditor). EnumPaymentStatusType: type: string maxLength: 45 enum: - PDNG - PART - ACSP - ACSC - ACCC - RJCT example: PDNG description: | 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. PART (PARTIALLY ACCEPTED) - Aguardando autorização múltipla alçada. 3. ACSP (ACCEPTED_SETTLEMENT_IN_PROCESS) - Iniciação de pagamento aceita e processamento do pagamento foi iniciado. 4. ACSC (ACCEPTED_SETTLEMENT_COMPLETED_DEBITOR_ACCOUNT) - Débito realizado na conta do pagador. 5. ACCC (ACCEPTED_SETTLEMENT_COMPLETED) - Crédito realizado na instituição de destino. Em caso insucesso: RJCT (REJECTED) - Instrução de pagamento rejeitada. EnumPaymentType: type: string maxLength: 3 enum: - PIX example: PIX description: | Este campo define o tipo de pagamento que será iniciado após a autorização do consentimento. EnumRejectionReasonType: type: string maxLength: 50 enum: - ABORTED_SETTLEMENT_TIMEOUT - ERROR_CREDITOR_AGENT - TIMEOUT_DEBTOR_AGENT - INVALID_CREDITOR_ACCOUNT_NUMBER - BLOCKED_ACCOUNT - CLOSED_CREDITOR_ACCOUNT_NUMBER - INVALID_CREDITOR_ACCOUNTTYPE - TRANSACTION_NOT_SUPPORTED - NOT_ALLOWED_BOOK_TRANSFER - FORBIDDEN_RETURN_PAYMENT - INCORRECT_AGENT - ZERO_AMOUNT - NOT_ALLOWED_AMOUNT - INSUFFICIENT_FUNDS - WRONG_AMOUNT - INVALID_AMOUNT - INVALID_NUMBER_OF_TRANSACTIONS - INCONSISTENT_WITH_END_CUSTOMER - INVALID_IDENTIFICATION_CODE - INVALID_CREDITOR_IDENTIFICATION_CODE - CREDITOR_IDENTIFIER_INCORRECT - ELEMENT_CONTENT_FORMALLY_INCORRECT - ORDER_REJECTED - NOT_ALLOWED_PAYMENT - NOT_ALLOWED_ACCOUNT - USER_NOT_YET_ACTIVATED - INVALID_CREATION_DATE - INVALID_CUT_OFF_DATE - SETTLEMENT_FAILED - INVALID_PURPOSE - INVALID_END_TO_END_ID - INVALID_DEBTOR_CLEARING_SYSTEM_MEMBER_IDENTIFIER - INVALID_CREDITOR_CLEARING_SYSTEM_MEMBER_IDENTIFIER - REGULATORY_REASON - SPECIFIC_SERVICE_OFFERED_BY_CREDITOR_AGENT - INVALID_BILL - OPERATION_WINDOW - INCOMPATIBLE_DATE - MISMATCH_AMOUNT - OVER_LIMIT - INVALID_CONSENT - DENIED_MULTIPLE_AUTHORISATIONS - EXPIRED_MULTIPLE_AUTHORISATIONS - EXPIRED_BILL example: USER_NOT_YET_ACTIVATED description: | Motivo da rejeição do pagamento. Informações complementares sobre o motivo do status. ABORTED_SETTLEMENT_TIMEOUT - Liquidação da transação interrompida devido a timeout no SPI (AB03). ERROR_CREDITOR_AGENT - Transação interrompida devido a erro no participante do usuário recebedor (AB09). TIMEOUT_DEBTOR_AGENT - Timeout do participante emissor da ordem de pagamento (AB11). INVALID_CREDITOR_ACCOUNT_NUMBER - Número da conta transacional do usuário recebedor inexistente ou inválido (AC03). BLOCKED_ACCOUNT - Conta transacional do usuário recebedor encontra-se bloqueada (AC06). CLOSED_CREDITOR_ACCOUNT_NUMBER - Número da conta transacional do usuário recebedor encerrada (AC07). INVALID_CREDITOR_ACCOUNTTYPE - Tipo incorreto para a conta transacional do usuário recebedor (AC14). TRANSACTION_NOT_SUPPORTED - Tipo de transação não é suportado/autorizado na conta transacional do usuário recebedor (AG03). Exemplo: transferência para conta salário. NOT_ALLOWED_BOOK_TRANSFER - Não é permitida ordem de pagamento/devolução no SPI cujos recursos sejam transferidos de uma conta transacional para outra em uma mesma instituição participante ou entre participantes que utilizem o serviço de liquidação de um mesmo participante liquidante no SPI (booktransfer) (AG12). FORBIDDEN_RETURN_PAYMENT - Não é permitido devolver a devolução de um pagamento instantâneo (AG13). INCORRECT_AGENT - Participante direto não é liquidante do participante do usuário pagador / participante do usuário recebedor (AGNT). ZERO_AMOUNT - Ordem de pagamento instantâneo com valor zero (AM01). NOT_ALLOWED_AMOUNT - Ordem de pagamento/devolução em valor que faz superar o limite permitido para o tipo de conta transacional creditada (AM02). INSUFFICIENT_FUNDS - Saldo insuficiente na conta PI do participante do usuário pagador (AM04). WRONG_AMOUNT - Devolução de pagamento em valor que faz superar o valor da ordem de pagamento instantâneo correspondente (AM09). INVALID_AMOUNT - Divergência entre a somatória dos valores do bloco ‘valorDoDinheiroOuCompra’ e o campo ‘valor’ (AM12). INVALID_NUMBER_OF_TRANSACTIONS - Quantidade de transações inválida (AM18). INCONSISTENT_WITH_END_CUSTOMER - CPF/CNPJ do usuário recebedor não é consistente com o titular da conta transacional especificada (BE01). INVALID_IDENTIFICATION_CODE - Código de situação de pagamento ou de erro inválido (BE15). INVALID_CREDITOR_IDENTIFICATION_CODE - QR Code rejeitado pelo participante do usuário recebedor (BE17). CREDITOR_IDENTIFIER_INCORRECT - CPF/CNPJ do usuário recebedor incorreto (CH11). ELEMENT_CONTENT_FORMALLY_INCORRECT - Elemento da mensagem incorreto (CH16). ORDER_REJECTED - Ordem rejeitada pelo participante do usuário recebedor (DS04). NOT_ALLOWED_PAYMENT - Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada. No caso em que o participante que assinou a mensagem não é o titular da conta PI debitada nem é o liquidante no SPI do participante do usuário pagador (DS0G). NOT_ALLOWED_ACCOUNT - ISPB do participante que submeteu a resposta à ordem de pagamento/devolução diferente do ISPB do participante creditado pela ordem (DS0H). USER_NOT_YET_ACTIVATED - Participante não se encontra cadastrado ou ainda não iniciou a operação no SPI (DS27). INVALID_CREATION_DATE - Data e Hora do envio da mensagem inválida (DT02). INVALID_CUT_OFF_DATE - Transação extrapola o prazo máximo para devolução de pagamento instantâneo regulamentado pelo Arranjo PIX (DT05). SETTLEMENT_FAILED - Erro no processamento do pagamento instantâneo (ED05). INVALID_PURPOSE - Inconsistência entre a finalidade da transação e o preenchimento do bloco elementos Structured (FF07). INVALID_END_TO_END_ID - Identificador da operação mal formatado (FF08). INVALID_DEBTOR_CLEARING_SYSTEM_MEMBER_IDENTIFIER - ISPB do participante do usuário pagador inválido ou inexistente (RC09). INVALID_CREDITOR_CLEARING_SYSTEM_MEMBER_IDENTIFIER - ISPB do participante do usuário recebedor inválido ou inexistente (RC10). REGULATORY_REASON - Ordem de pagamento em que o usuário pagador é sancionado por resolução do Conselho de Segurança das Nações Unidas (CSNU). Nos casos em que o usuário recebedor for o sancionado, a ordem de pagamento não deve ser rejeitada (RR4). SPECIFIC_SERVICE_OFFERED_BY_CREDITOR_AGENT - A transação original não está relacionada ao serviço de Saque Pix (SL02). INVALID_BILL - Validação de expiração, validação de vencimento, Status Válido (INDT). OPERATION_WINDOW - Requisição está fora da janela de funcionamento (IDEA). INCOMPATIBLE_DATE - Data do pagamento divergente da data consentida ou divergente da data atual do QR Code (TERM). MISMATCH_AMOUNT - O valor informado no consentimento não é o mesmo valor do informado no payload de pagamento (OB01). OVER_LIMIT - 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 (OB02). INVALID_CONSENT - Consentimento inválido (status não é "authorised" ou está expirado) (OB03). DENIED_MULTIPLE_AUTHORISATIONS - Um (ou mais) aprovadores na detentora recusaram a operação (OB04). EXPIRED_MULTIPLE_AUTHORISATIONS - Um (ou mais) aprovadores na detentora não tomaram ação para aprovar a operação (OB05). EXPIRED_BILL - O QR Code não é mais válido (OB06). [Restrição] Esse motivo deverá ser enviado quando o campo /data/status for igual a RJCT (REJECTED). Identification: type: object description: Objeto contendo os dados do recebedor (creditor). required: - personType - cpfCnpj - name properties: personType: $ref: '#/components/schemas/EnumPaymentPersonType' cpfCnpj: type: string minLength: 11 maxLength: 14 pattern: '^\d{11}$|^\d{14}$' example: '58764789000137' description: | Identificação da pessoa envolvida na transação. Preencher com o CPF ou CNPJ, de acordo com o valor escolhido no campo type. O CPF será utilizado com 11 números e deverá ser informado sem pontos ou traços. O CNPJ será utilizado com 14 números e deverá ser informado sem pontos ou traços. name: type: string maxLength: 140 pattern: '[\w\W\s]*' example: Marco Antonio de Brito description: | Em caso de pessoa natural deve ser informado o nome completo do titular da conta do recebedor. Em caso de pessoa jurídica deve ser informada a razão social ou o nome fantasia da conta do recebedor. additionalProperties: false LoggedUser: type: object description: Usuário (pessoa natural) que encontra-se logado na instituição Iniciadora de Pagamento. additionalProperties: false required: - document properties: document: type: object additionalProperties: false required: - identification - rel properties: identification: type: string maxLength: 11 description: Número do documento de identificação oficial do usuário. example: '11111111111' pattern: '^\d{11}$' rel: type: string maxLength: 3 description: Tipo do documento de identificação oficial do usuário. example: CPF pattern: '^[A-Z]{3}$' Meta: type: object description: Meta informações referente a API requisitada. required: - totalRecords - totalPages - requestDateTime properties: totalRecords: type: integer format: int32 description: Número total de registros no resultado example: 1 totalPages: type: integer format: int32 description: Número total de páginas no resultado example: 1 requestDateTime: description: 'Data e hora da consulta, conforme especificação RFC-3339, formato UTC.' type: string maxLength: 20 format: date-time example: '2021-05-21T08:30:00Z' additionalProperties: false PaymentConsent: type: object description: Objeto contendo dados de pagamento para consentimento. required: - type - date - currency - amount - details properties: type: $ref: '#/components/schemas/EnumPaymentType' date: type: string format: date maxLength: 10 pattern: '^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$' example: '2021-01-01' description: 'Data do pagamento, conforme especificação RFC-3339.' currency: type: string maxLength: 3 pattern: '^([A-Z]{3})$' example: BRL description: | 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. amount: type: string minLength: 4 maxLength: 19 pattern: '^((\d{1,16}\.\d{2}))$' example: '100000.12' description: | Valor da transação com 2 casas decimais. details: $ref: '#/components/schemas/Details' additionalProperties: false PaymentPix: type: object description: Objeto contendo dados do pagameto como moeda e valor. required: - amount - currency properties: amount: type: string minLength: 4 maxLength: 19 pattern: '^((\d{1,16}\.\d{2}))$' example: '100000.12' description: | Valor da transação com 2 casas decimais. currency: type: string maxLength: 3 pattern: '^([A-Z]{3})$' example: BRL description: | 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. additionalProperties: false ResponseError: type: object required: - errors properties: errors: type: array minItems: 1 maxItems: 13 items: type: object required: - code - title - detail properties: code: description: Código de erro específico do endpoint type: string pattern: '[\w\W\s]*' maxLength: 255 title: description: Título legível por humanos deste erro específico type: string pattern: '[\w\W\s]*' maxLength: 255 detail: description: Descrição legível por humanos deste erro específico type: string pattern: '[\w\W\s]*' maxLength: 2048 additionalProperties: false meta: $ref: '#/components/schemas/Meta' additionalProperties: false ResponsePaymentConsent: type: object required: - data - links - meta properties: data: type: object description: Objeto contendo as informações de resposta do consentimento para a iniciação de pagamento individual. required: - consentId - statusUpdateDateTime - creationDateTime - expirationDateTime - status - loggedUser - creditor - payment properties: consentId: type: string maxLength: 256 pattern: '^urn:[a-zA-Z0-9][a-zA-Z0-9-]{0,31}:[a-zA-Z0-9()+,\-.:=@;$_!*''%\/?#]+$' example: 'urn:bancoex:C1DD33123' description: | 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](https://tools.ietf.org/html/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](https://tools.ietf.org/html/rfc8141). creationDateTime: description: 'Data e hora em que o consentimento foi criado. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format).' type: string format: date-time example: '2021-05-21T08:30:00Z' pattern: '^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\d|2[0123]):(?:[012345]\d):(?:[012345]\d)Z$' maxLength: 20 expirationDateTime: description: | Data e hora em que o consentimento da iniciação de pagamento expira, devendo ser sempre o creationDateTime mais 5 minutos. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC (UTC time format). O consentimento é criado com o status AWAITING_AUTHORISATION, e deve assumir o status AUTHORIZED ou REJECTED antes do tempo de expiração - 5 minutos. Caso o tempo seja expirado, o status deve assumir REJECTED. Para o cenário em que o status assumiu AUTHORISED, o tempo máximo do expirationDateTime do consentimento deve assumir "now + 60 minutos". Este é o tempo para consumir o consentimento autorizado, mudando seu status para CONSUMED. Não é possível prorrogar este tempo e a criação de um novo consentimento será necessária para os cenários de insucesso. O tempo do expirationDateTime é garantido com os 15 minutos do access token, sendo possível utilizar mais três refresh tokens até totalizar 60 minutos. type: string format: date-time example: '2021-05-21T08:30:00Z' pattern: '^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\d|2[0123]):(?:[012345]\d):(?:[012345]\d)Z$' maxLength: 20 statusUpdateDateTime: type: string format: date-time example: '2021-05-21T08:30:00Z' pattern: '^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\d|2[0123]):(?:[012345]\d):(?:[012345]\d)Z$' maxLength: 20 description: | Data e hora em que o recurso foi atualizado. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format). status: $ref: '#/components/schemas/EnumAuthorisationStatusType' loggedUser: $ref: '#/components/schemas/LoggedUser' businessEntity: $ref: '#/components/schemas/BusinessEntity' creditor: $ref: '#/components/schemas/Identification' payment: $ref: '#/components/schemas/PaymentConsent' debtorAccount: $ref: '#/components/schemas/DebtorAccount' additionalProperties: false links: $ref: '#/components/schemas/ResponsePixPayment/properties/links' meta: $ref: '#/components/schemas/Meta' additionalProperties: false ResponsePixPayment: type: object required: - data - links - meta properties: data: $ref: '#/components/schemas/ResponsePixPaymentData' links: type: object description: Referências para outros recusos da API requisitada. required: - self properties: self: type: string format: uri maxLength: 2000 description: URI completo que gerou a resposta atual. example: 'https://api.banco.com.br/open-banking/api/v1/resource' pattern: '^(https?:\/\/)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&\/\/=]*)$' additionalProperties: false meta: $ref: '#/components/schemas/Meta' additionalProperties: false ResponsePixPaymentData: type: object description: Objeto contendo dados do pagamento e da conta do recebedor (creditor). required: - paymentId - consentId - creationDateTime - statusUpdateDateTime - status - localInstrument - payment - creditorAccount - cnpjInitiator properties: paymentId: type: string minLength: 1 maxLength: 100 pattern: '^[a-zA-Z0-9][a-zA-Z0-9\-]{0,99}$' example: TXpRMU9UQTROMWhZV2xSU1FUazJSMDl description: | Código ou identificador único informado pela instituição detentora da conta para representar a iniciação de pagamento individual. O `paymentId` deve ser diferente do `endToEndId`. Este é o identificador que deverá ser utilizado na consulta ao status da iniciação de pagamento efetuada. endToEndId: $ref: '#/components/schemas/EndToEndId' consentId: type: string maxLength: 256 pattern: '^urn:[a-zA-Z0-9][a-zA-Z0-9-]{0,31}:[a-zA-Z0-9()+,\-.:=@;$_!*''%\/?#]+$' example: 'urn:bancoex:C1DD33123' description: | 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](https://tools.ietf.org/html/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](https://tools.ietf.org/html/rfc8141). creationDateTime: type: string format: date-time pattern: '^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\d|2[0123]):(?:[012345]\d):(?:[012345]\d)Z$' example: '2020-07-21T08:30:00Z' description: | 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). statusUpdateDateTime: type: string format: date-time pattern: '^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\d|2[0123]):(?:[012345]\d):(?:[012345]\d)Z$' example: '2020-07-21T08:30:00Z' description: | 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). proxy: type: string maxLength: 77 pattern: '[\w\W\s]*' example: '12345678901' description: | Chave cadastrada no DICT pertencente ao recebedor. Os tipos de chaves podem ser: telefone, e-mail, cpf/cnpj ou chave aleatória. No caso de telefone celular deve ser informado no padrão E.1641. Para e-mail deve ter o formato xxxxxxxx@xxxxxxx.xxx(.xx) e no máximo 77 caracteres. No caso de CPF deverá ser informado com 11 números, sem pontos ou traços. Para o caso de CNPJ deverá ser informado com 14 números, sem pontos ou traços. No caso de chave aleatória deve ser informado o UUID gerado pelo DICT, conforme formato especificado na RFC41223. Se informado, a detentora da conta deve validar o proxy no DICT quando localInstrument for igual a DICT, QRDN (uso futuro) ou QRES (uso futuro) e validar o campo creditorAccount. Esta validação é opcional caso o localInstrument for igual a INIC. [Restrição] Se localInstrument for igual a MANU, o campo proxy não deve ser preenchido. Se localInstrument for igual INIC, DICT, QRDN (uso futuro) ou QRES(uso futuro), o campo proxy deve ser sempre preenchido com a chave Pix. status: $ref: '#/components/schemas/EnumPaymentStatusType' rejectionReason: $ref: '#/components/schemas/EnumRejectionReasonType' localInstrument: $ref: '#/components/schemas/EnumLocalInstrument' cnpjInitiator: type: string pattern: '^\d{14}$' maxLength: 14 example: '50685362000135' description: CNPJ do Iniciador de Pagamento devidamente habilitado para a prestação de Serviço de Iniciação no Pix. payment: $ref: '#/components/schemas/PaymentPix' transactionIdentification: type: string pattern: '^[a-zA-Z0-9][a-zA-Z0-9]{0,24}$' maxLength: 25 example: E00038166201907261559y6j6 description: | Trata-se de um identificador de transação que deve ser retransmitido intacto pelo PSP do pagador ao gerar a ordem de pagamento. Essa informação permitirá ao recebedor identificar e correlacionar a transferência, quando recebida, com a apresentação das instruções ao pagador. Os caracteres permitidos no contexto do Pix para o campo txid (EMV 62-05) são: - Letras minúsculas, de ‘a’ a ‘z’ - Letras maiúsculas, de ‘A’ a ‘z’ - Dígitos decimais, de ‘0’ a ‘9’ [Restrição] Se localInstrument for igual a INIC, o campo transactionIdentification deve ser preenchido obrigatoriamente. Se localInstrument for igual a MANU ou DICT, o campo transactionIdentification não deve ser preenchido. A detentora de conta deve validar se a condicionalidade do campo foi atendida pela iniciadora de pagamento. remittanceInformation: type: string maxLength: 140 pattern: '[\w\W\s]*' example: Pagamento da nota RSTO035-002. description: | Deve ser preenchido sempre que o usuário pagador inserir alguma informação adicional em um pagamento, a ser enviada ao recebedor. creditorAccount: $ref: '#/components/schemas/CreditorAccount' additionalProperties: false XFapiInteractionId: type: string pattern: '^[a-zA-Z0-9][a-zA-Z0-9\-]{0,99}$' maxLength: 100 description: 'Um UID [RFC4122](https://tools.ietf.org/html/rfc4122) usado como um ID de correlação. Se fornecido, o transmissor deve "reproduzir" esse valor no cabeçalho de resposta.' parameters: consentId: name: consentId in: path description: | O consentId é o identificador único do consentimento e deverá ser um URN - Uniform Resource Name. Um URN, conforme definido na [RFC8141](https://tools.ietf.org/html/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](https://tools.ietf.org/html/rfc8141). required: true schema: type: string pattern: '^urn:[a-zA-Z0-9][a-zA-Z0-9-]{0,31}:[a-zA-Z0-9()+,\-.:=@;$_!*''%\/?#]+$' maxLength: 256 paymentId: name: paymentId in: path description: Identificador da operação de pagamento. required: true schema: type: string pattern: '^[a-zA-Z0-9][a-zA-Z0-9\-]{0,99}$' maxLength: 100 Authorization: name: Authorization in: header description: Cabeçalho HTTP padrão. Permite que as credenciais sejam fornecidas dependendo do tipo de recurso solicitado required: true schema: type: string pattern: '[\w\W\s]*' maxLength: 2048 xCustomerUserAgent: name: x-customer-user-agent in: header description: Indica o user-agent que o usuário utiliza. required: false schema: type: string pattern: '[\w\W\s]*' minLength: 1 maxLength: 100 xFapiAuthDate: name: x-fapi-auth-date in: header description: 'Data em que o usuário logou pela última vez com o receptor. Representada de acordo com a [RFC7231](https://tools.ietf.org/html/rfc7231).Exemplo: Sun, 10 Sep 2017 19:43:31 UTC' required: false schema: type: string pattern: '^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} (GMT|UTC)$' minLength: 29 maxLength: 29 xFapiCustomerIpAddress: name: x-fapi-customer-ip-address in: header description: O endereço IP do usuário se estiver atualmente logado com o receptor. required: false schema: type: string pattern: '[\w\W\s]*' minLength: 1 maxLength: 100 xFapiInteractionId: name: x-fapi-interaction-id in: header description: 'Um UID [RFC4122](https://tools.ietf.org/html/rfc4122) usado como um ID de correlação. Se fornecido, o transmissor deve "reproduzir" esse valor no cabeçalho de resposta.' required: false schema: type: string pattern: '^[a-zA-Z0-9][a-zA-Z0-9\-]{0,99}$' minLength: 1 maxLength: 100 XIdempotencyKey: name: x-idempotency-key in: header description: Cabeçalho HTTP personalizado. Identificador de solicitação exclusivo para suportar a idempotência. required: true schema: type: string maxLength: 40 pattern: ^(?!\s)(.*)(\S)$ securitySchemes: OpenId: type: openIdConnect openIdConnectUrl: 'https://auth.mockbank.poc.raidiam.io/.well-known/openid-configuration' OAuth2ClientCredentials: type: oauth2 description: Fluxo OAuth necessário para que a iniciadora possa iniciar pagamentos. Requer o processo de redirecionamento e autenticação do usuário. flows: clientCredentials: tokenUrl: 'https://authserver.example/token' scopes: payments: Escopo necessário para acesso à API Payment Initiation. OAuth2AuthorizationCode: type: oauth2 description: Fluxo OAuth necessário para que a iniciadora possa iniciar pagamentos. Requer o processo de redirecionamento e autenticação do usuário. flows: authorizationCode: authorizationUrl: 'https://authserver.example/token' tokenUrl: 'https://authserver.example/token' scopes: payments: Escopo necessário para acesso à API Payment Initiation. responses: BadRequest: description: 'A requisição foi malformada, omitindo atributos obrigatórios, seja no payload ou através de atributos na URL.' content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/ResponseError' headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação. O transmissor deve usar o mesmo valor recebido na requisição para o cabeçalho de resposta recebido na requisição, caso não tenha sido fornecido, deve se usar um UUID RFC4122. schema: $ref: '#/components/schemas/XFapiInteractionId' Forbidden: description: O token tem escopo incorreto ou uma política de segurança foi violada content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/ResponseError' headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação. O transmissor deve usar o mesmo valor recebido na requisição para o cabeçalho de resposta recebido na requisição, caso não tenha sido fornecido, deve se usar um UUID RFC4122. schema: $ref: '#/components/schemas/XFapiInteractionId' InternalServerError: description: Ocorreu um erro no gateway da API ou no microsserviço content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/ResponseError' headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação. O transmissor deve usar o mesmo valor recebido na requisição para o cabeçalho de resposta recebido na requisição, caso não tenha sido fornecido, deve se usar um UUID RFC4122. schema: $ref: '#/components/schemas/XFapiInteractionId' MethodNotAllowed: description: O consumidor tentou acessar o recurso com um método não suportado content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/ResponseError' headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação. O transmissor deve usar o mesmo valor recebido na requisição para o cabeçalho de resposta recebido na requisição, caso não tenha sido fornecido, deve se usar um UUID RFC4122. schema: $ref: '#/components/schemas/XFapiInteractionId' NotAcceptable: description: A solicitação continha um cabeçalho Accept diferente dos tipos de mídia permitidos ou um conjunto de caracteres diferente de UTF-8 content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/ResponseError' headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação. O transmissor deve usar o mesmo valor recebido na requisição para o cabeçalho de resposta recebido na requisição, caso não tenha sido fornecido, deve se usar um UUID RFC4122. schema: $ref: '#/components/schemas/XFapiInteractionId' NotFound: description: O recurso solicitado não existe ou não foi implementado content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/ResponseError' headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação. O transmissor deve usar o mesmo valor recebido na requisição para o cabeçalho de resposta recebido na requisição, caso não tenha sido fornecido, deve se usar um UUID RFC4122. schema: $ref: '#/components/schemas/XFapiInteractionId' TooManyRequests: description: 'A operação foi recusada, pois muitas solicitações foram feitas dentro de um determinado período ou o limite global de requisições concorrentes foi atingido' content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/ResponseError' headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação. O transmissor deve usar o mesmo valor recebido na requisição para o cabeçalho de resposta recebido na requisição, caso não tenha sido fornecido, deve se usar um UUID RFC4122. schema: $ref: '#/components/schemas/XFapiInteractionId' Retry-After: description: | Cabeçalho que indica o tempo (em segundos) que o cliente deverá aguardar para realizar uma nova tentativa de chamada. Este cabeçalho deverá estar presente quando o código HTTP de retorno for 429 Too many requests. schema: description: | Cabeçalho que indica o tempo (em segundos) que o cliente deverá aguardar para realizar uma nova tentativa de chamada. Este cabeçalho deverá estar presente quando o código HTTP de retorno for 429 Too many requests. type: integer UnprocessableEntityConsents: description: 'A solicitação foi bem formada, mas não pôde ser processada devido à lógica de negócios específica da solicitação.' content: application/jwt: schema: $ref: '#/components/schemas/422ResponseErrorCreateConsent' examples: Forma de pagamento inválida: summary: Forma de pagamento inválida value: errors: - code: FORMA_PGTO_INVALIDA title: Forma de pagamento inválida. detail: Meio de pagamento inválido. meta: totalRecords: 1 totalPages: 1 requestDateTime: '2021-05-21T08:30:00Z' headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação. O transmissor deve usar o mesmo valor recebido na requisição para o cabeçalho de resposta recebido na requisição, caso não tenha sido fornecido, deve se usar um UUID RFC4122. schema: $ref: '#/components/schemas/XFapiInteractionId' UnprocessableEntityPixPayments: description: 'A solicitação foi bem formada, mas não pôde ser processada devido à lógica de negócios específica da solicitação.' content: application/jwt: schema: $ref: '#/components/schemas/422ResponseErrorCreatePixPayment' examples: Saldo insuficiente: summary: Saldo insuficiente value: errors: - code: SALDO_INSUFICIENTE title: Saldo insuficiente. detail: A conta selecionada não possui saldo suficiente para realizar o pagamento. meta: totalRecords: 1 totalPages: 1 requestDateTime: '2021-05-21T08:30:00Z' headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação. O transmissor deve usar o mesmo valor recebido na requisição para o cabeçalho de resposta recebido na requisição, caso não tenha sido fornecido, deve se usar um UUID RFC4122. schema: $ref: '#/components/schemas/XFapiInteractionId' Unauthorized: description: Cabeçalho de autenticação ausente/inválido ou token inválido content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/ResponseError' headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação. O transmissor deve usar o mesmo valor recebido na requisição para o cabeçalho de resposta recebido na requisição, caso não tenha sido fornecido, deve se usar um UUID RFC4122. schema: $ref: '#/components/schemas/XFapiInteractionId' UnsupportedMediaType: description: O formato do payload não é um formato suportado. content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/ResponseError' headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação. O transmissor deve usar o mesmo valor recebido na requisição para o cabeçalho de resposta recebido na requisição, caso não tenha sido fornecido, deve se usar um UUID RFC4122. schema: $ref: '#/components/schemas/XFapiInteractionId' 201PaymentsConsentsConsentCreated: description: Consentimento de pagamento criado com sucesso. headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação. O transmissor deve usar o mesmo valor recebido na requisição para o cabeçalho de resposta recebido na requisição, caso não tenha sido fornecido, deve se usar um UUID RFC4122. schema: $ref: '#/components/schemas/XFapiInteractionId' content: application/jwt: schema: $ref: '#/components/schemas/ResponsePaymentConsent' 200PaymentsConsentsConsentIdRead: description: Dados do consentimento de pagamento obtidos com sucesso. headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação. O transmissor deve usar o mesmo valor recebido na requisição para o cabeçalho de resposta recebido na requisição, caso não tenha sido fornecido, deve se usar um UUID RFC4122. schema: $ref: '#/components/schemas/XFapiInteractionId' content: application/jwt: schema: $ref: '#/components/schemas/ResponsePaymentConsent' 201PaymentsInitiationPixPaymentCreated: description: Iniciação de pagamento Pix criada com sucesso. headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação. O transmissor deve usar o mesmo valor recebido na requisição para o cabeçalho de resposta recebido na requisição, caso não tenha sido fornecido, deve se usar um UUID RFC4122. schema: $ref: '#/components/schemas/XFapiInteractionId' content: application/jwt: schema: $ref: '#/components/schemas/ResponsePixPayment' 200PaymentsInitiationPixPaymentIdRead: description: Dados de iniciação de pagamento Pix obtidos com sucesso. headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação. O transmissor deve usar o mesmo valor recebido na requisição para o cabeçalho de resposta recebido na requisição, caso não tenha sido fornecido, deve se usar um UUID RFC4122. schema: $ref: '#/components/schemas/XFapiInteractionId' content: application/jwt: schema: $ref: '#/components/schemas/ResponsePixPayment'