Gere um QR Code Pix através desta API

154
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 escopoDescrição
invoiceAPI de boleto

Bora pro código?

383

Parâmetros da requisição

ParâmetroTipoDescrição
code
opcional
StringCódigo definido por você, pode ser um id do recurso no seu sistema.
customer
obrigatório
CustomerObjeto Customer
services
obrigatório
Lista de ServicesLista de Objetos Services
payment_terms
obrigatório
PaymentTermsObjeto PaymentTerms
payment_forms
obrigatório
StringPara criar um QR Code Pix basta inserir a opção de "PIX'.

Parâmetros da resposta

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

Dicas de implementação

188

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 erroDescriçã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âmetroTipoDescrição
name
obrigatório
StringNome do seu cliente (máximo 60 caracteres)
email
opcional
StringE-mail do seu cliente (máximo 60 caracteres)
document
obrigatório
DocumentObjeto Document
address
opcional
AddressObjeto Address

Objeto Document

ParâmetroTipoDescrição
identity
obrigatório
StringNúmero do documento do seu cliente (apenas números, sem traços e pontos). Deve ser enviado como uma string.
type
obrigatório
StringTipo 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âmetroTipoDescrição
street
opcional
StringNome da rua do seu cliente.
number
opcional
StringNúmero da rua do seu cliente.
district
opcional
StringBairro do seu cliente.
city
opcional
StringCidade do seu cliente.
state
opcional
StringEstado do seu cliente no formato AA. Exemplos: SP, AC, GO, RJ.
complement
opcional
StringComplemento do endereço do seu cliente.
zip_code
opcional
StringCEP do seu cliente. Formatos possíveis: 00111222 e 00111-222.

Objeto Services

ParâmetroTipoDescrição
name
obrigatório
StringNome do serviço prestado.
description
obrigatório
StringDescrição do serviço prestado. Máximo de 100 caracteres.
amount
obrigatório
IntValor do serviço prestado.

Objeto PaymentTerms

ParâmetroTipoDescrição
due_date
obrigatório
StringData 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
FineObjeto Fine
interest
opcional
InterestObjeto Interest
discount
opcional
DiscountObjeto Discount

Objeto Fine

ParâmetroTipoDescrição
date
opcional
StringData a partir da qual será aplicado os juros diários. Essa data é facultativa, caso não informada, o padrão é data de vencimento +1.
amount
opcional
IntValor 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
DoubleValor 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âmetroTipoDescrição
rate
obrigatório
DoubleTaxa de juros a ser cobrada. Valores possíveis: de 0 a 100 (com duas casas decimais).

Objeto Discount

ParâmetroTipoDescrição
type
obrigatório
StringTipo de desconto aplicado. Valor fixo FIXED ou percentual PERCENT .
value
obrigatório
DoubleValor 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âmetroTipoDescrição
bank_slip
obrigatório
BankSlipObjeto BankSlip

Objeto BankSlip

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

Objeto PixResponse

ParâmetroTipoDescrição
emv
obrigatório
StringQuando 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âmetroDescrição
CANCELLEDCancelado
DRAFTEm rascunho, um estado intermediário entre criação e registro
IN_PAYMENTEm processo de pagamento
LATEPagamento em atraso, ou seja, após a data de vencimento
OPENEm aberto, ainda não foi pago
PAIDPago com sucesso

Integração Direta e Testes

Esta plataforma de documentação, atualmente, não permite o upload de informações importantes como certificados e private keys. Por isso, não recomendamos o uso dela para testes da modalidade de Integração Direta.

Para fazer os testes que incluam essas informações sensíveis pedimos que use um sistema de sua escolha.
Imagem
Opa, agora é hora do lanche! Sim, finalizamos mais uma etapa
Language
Authorization
OAuth2
Click Try It! to start a request and see the response here!