Emissão de cobrança QR Code Pix

Importante para Integração Direta Para você conseguir efetuar essa integração é obrigatória a leitura sobre "Utilização das APIs" e recomendada a leitura sobre "Instruções Iniciais" e "Client Credentials e Client ID"

O que é uma cobrança via QR Code?

A emissão do QR Code permite que você realize cobranças para os seus clientes, que a partir da leitura do QR Code vão poder realizar um pagamento via Pix para a sua conta Cora.

Importante: Essa API não permite a realização de transferência Pix, estamos analisando a possibilidade de disponibilizar APIs de transferência Pix, porém ainda não podemos fornecer um prazo exato para sua implementação.

Quem pode usar esta API?

Clientes Cora que estão cadastrados em Integração Direta ou Parceria Cora.

Quais são requisitos para a utilização desta API?

Integração Direta: Ter finalizado a etapa de autorização

Parceria Cora: Já ter feito a etapa de autorização e autenticação

Escopo: para a modalidade Parceria Cora, é necessário ter ativado o escopo correto ao solicitar autorização e gerar token de acesso para que sua aplicação possa acessar e interagir com as informações da conta de forma segura e autorizada. É possível consultar mais detalhes sobre o escopo e autorização no tópico Redirecionamento.

Nome do escopo	Descrição
`invoice`	API de boleto

Parâmetros da requisição

Parâmetro	Tipo	Descrição
code opcional	String	Código definido por você, pode ser um id do recurso no seu sistema.
customer\ obrigatório	Customer	Objeto Customer
services\ obrigatório	Lista de Services	Lista de Objetos Services
payment_terms\ obrigatório	PaymentTerms	Objeto PaymentTerms
payment_forms\ obrigatório	String	Para criar um QR Code Pix basta inserir a opção de "PIX'.

Parâmetros da resposta

Parâmetro	Tipo	Descrição
id obrigatório	String	Identificador do pagamento na Cora. Esse id poderá ser usado para consultar os detalhes do QR Code Pix.
status\ obrigatório	String	Indica qual é o estado do QR Code. Os status possíveis estão na Tabela de Estados do QR Code Pix.
created_at\ obrigatório	String	Data de criação do QR Code Pix.
total_amount\ obrigatório	Int	Valor total em centavos do QR Code Pix. Esse valor é a soma dos valores informados no parâmetro Services.
total_paid\ obrigatório	Int	Valor total pago (em centavos), caso o QR Code Pix ainda não tenha sido pago, ele estará zerado.
occurrence_date\ opcional	String	Data que o cliente efetuou o pagamento do QR Code Pix.
code\ obrigatório	String	Código definido por você, pode ser um id do recurso no seu sistema.
customer\ obrigatório	Customer	Objeto Customer
services\ obrigatório	Lista de Services	Lista de Objetos Services
payment_terms\ obrigatório	PaymentTerms	Objeto PaymentTerms
payment_options\ obrigatório	PaymentOptions	Objeto PaymentOptions
payments\ obrigatório	Payments	Lista de Objetos Payments. Caso o pagamento ainda não tenha sido feito o array será vazio.
pix\ obrigatório	Pix	Objeto PixResponse

Dicas de implementação

Premissas

Os parâmetros que tratam de valores são tipos primitivos inteiros com os centavos sendo representados pelos dois dígitos iniciais (unidade e dezena). Como exemplo, temos o valor de R$ 10,01 que é representado por 1001 dentro do valor total_amount. Veja o json abaixo:

{  
    "total_amount": 1001
}

Problemas conhecidos

Quando enviado um e-mail ou documentos inválidos a Cora está retornando erros genéricos ao invés de retornar erro 400 (Bad Request)

Erros Comuns

Código de erro	Descrição
401 (Unauthorized)	O token de acesso está inválido ou expirado. Erro comum no momento de trocas de ambientes (Stage/Production).
400 (Bad Request)	Requisição mal formatada. Alguns exemplos comuns: Idempotency-Key que não está no formato correto (uuid) Chave payment_term escrito no singular ao invés de payment_terms que é o correto. Campo valor (amount) mal formatado. Ex: 20,00 ao invés de 2000. - Data de vencimento do QR Code Pix anterior ao dia atual de emissão.
415 (Unsupported Media Type)	Falta do Content-Type application/json no header da requisição.

Código de erro

Descrição

401 (Unauthorized)

O token de acesso está inválido ou expirado. Erro comum no momento de trocas de ambientes (Stage/Production).

400 (Bad Request)

Requisição mal formatada. Alguns exemplos comuns:

Idempotency-Key que não está no formato correto (uuid)
Chave payment_term escrito no singular ao invés de payment_terms que é o correto.
Campo valor (amount) mal formatado. Ex: 20,00 ao invés de 2000. - Data de vencimento do QR Code Pix anterior ao dia atual de emissão.

415 (Unsupported Media Type)

Falta do Content-Type application/json no header da requisição.

Tipos de Objetos

Objeto Customer

Parâmetro	Tipo	Descrição
name obrigatório	String	Nome do seu cliente (máximo 60 caracteres)
email\ opcional	String	E-mail do seu cliente (máximo 60 caracteres)
document\ obrigatório	Document	Objeto Document
address\ opcional	Address	Objeto Address

Objeto Document

Parâmetro	Tipo	Descrição
identity obrigatório	String	Número do documento do seu cliente (apenas números, sem traços e pontos). Deve ser enviado como uma string.
type\ obrigatório	String	Tipo de documento, os valores possíveis são "CPF" e "CNPJ". Caso não informado, iremos inferir pela quantidade de caracteres informado no parâmetro identity.

Objeto Address

Parâmetro	Tipo	Descrição
street opcional	String	Nome da rua do seu cliente.
number\ opcional	String	Número da rua do seu cliente.
district\ opcional	String	Bairro do seu cliente.
city\ opcional	String	Cidade do seu cliente.
state\ opcional	String	Estado do seu cliente no formato AA. Exemplos: SP, AC, GO, RJ.
complement\ opcional	String	Complemento do endereço do seu cliente.
zip_code\ opcional	String	CEP do seu cliente. Formatos possíveis: 00111222 e 00111-222.

Objeto Services

Parâmetro	Tipo	Descrição
name obrigatório	String	Nome do serviço prestado.
description\ obrigatório	String	Descrição do serviço prestado. Máximo de 100 caracteres.
amount\ obrigatório	Int	Valor do serviço prestado.

Objeto PaymentTerms

Parâmetro	Tipo	Descrição
due_date obrigatório	String	Data de vencimento do QR Code Pix. Deve seguir o formato AAAA-MM-DD. O QR Code é válido até 30 dias após a data de vencimento.
fine\ opcional	Fine	Objeto Fine
interest\ opcional	Interest	Objeto Interest
discount\ opcional	Discount	Objeto Discount

Objeto Fine

Parâmetro	Tipo	Descrição
date opcional	String	Data a partir da qual será aplicada multa mensal. Essa data é facultativa, caso não informada, o padrão é data de vencimento +1.
amount\ opcional	Int	Valor em centavos da multa a ser cobrada. Atenção O parâmetro amount tem precedência sobre o parâmetro rate. Portanto, se for informado os dois parâmetros no objeto fine, apenas o atributo amount será considerado.
rate\ opcional	Double	Valor percentual da multa a ser cobrada. Atenção Esse parâmetro tem menor prioridade em relação ao parâmetro amount. Portanto, só será considerado caso o valor amount seja nulo. Valores possíveis: de 0 a 100 (com duas casas decimais).

Parâmetro

Tipo

Descrição

date opcional

String

Data a partir da qual será aplicada multa mensal. Essa data é facultativa, caso não informada, o padrão é data de vencimento +1.

amount\ opcional

Int

Valor em centavos da multa a ser cobrada.

Atenção

O parâmetro amount tem precedência sobre o parâmetro rate. Portanto, se for informado os dois parâmetros no objeto fine, apenas o atributo amount será considerado.

rate\ opcional

Double

Valor percentual da multa a ser cobrada.

Atenção

Esse parâmetro tem menor prioridade em relação ao parâmetro amount. Portanto, só será considerado caso o valor amount seja nulo. Valores possíveis: de 0 a 100 (com duas casas decimais).

Objeto Interest

Parâmetro	Tipo	Descrição
rate obrigatório	Double	Taxa de juros a ser cobrada. Valores possíveis: de 0 a 100 (com duas casas decimais).

Objeto Discount

Parâmetro	Tipo	Descrição
type obrigatório	String	Tipo de desconto aplicado. Valor fixo FIXED ou percentual PERCENT .
value\ obrigatório	Double	Valor do desconto a ser aplicado. Apesar do campo ser Double, caso o tipo seja FIXED o valor decimal será truncado, mantendo o padrão de envio de valores fixos com centavos. Ex: R$ 20,50 é representado como 2050.

Objeto PaymentOptions

Parâmetro	Tipo	Descrição
bank_slip obrigatório	BankSlip	Objeto BankSlip

Objeto BankSlip

Parâmetro	Tipo	Descrição
url obrigatório	String	URL do PNG do QR Code Pix (os QR Codes são disponibilizados apenas em PNG, não há versão HTML).

Objeto PixResponse

Parâmetro	Tipo	Descrição
emv obrigatório	String	Quando um QR Code Pix é gerado esse campo virá preenchido. Código do Pix Copia e Cola, o mesmo que é utilizado para gerar o QR Code Pix.

Tipos de Enumeradores

Enum de Estados do QR Code Pix

Parâmetro	Descrição
CANCELLED	Cancelado
DRAFT	Em rascunho, um estado intermediário entre criação e registro
IN_PAYMENT	Em processo de pagamento
LATE	Pagamento em atraso, ou seja, após a data de vencimento
OPEN	Em aberto, ainda não foi pago
PAID	Pago com sucesso

Opa, agora é hora do lanche! Sim, finalizamos mais uma etapa

O que é uma cobrança via QR Code?

Quem pode usar esta API?

Quais são requisitos para a utilização desta API?

Bora pro código?

Parâmetros da requisição

Parâmetros da resposta

Dicas de implementação

Premissas

Problemas conhecidos

Erros Comuns

Tipos de Objetos

Objeto Customer

Objeto Document

Objeto Address

Objeto Services

Objeto PaymentTerms

Objeto Fine

Objeto Interest

Objeto Discount

Objeto PaymentOptions

Objeto BankSlip

Objeto PixResponse

Tipos de Enumeradores

Enum de Estados do QR Code Pix