PortuguêsReferência da APICobrançasCriar cobrança PIX

Criar cobrança PIX

POST/v1/pix
Cria uma cobrança PIX dinâmica e retorna o copia-e-cola para pagamento.

Request

Cabeçalhos

CabeçalhoObrigatórioDescrição
AuthorizationsimBearer <SUA_API_KEY>
Content-Typesimapplication/json

Corpo

{
  "amountCents": 1000,
  "externalRef": "pedido-123",
  "expiresInDays": 2,
  "customer": {
    "name": "Maria Silva",
    "email": "maria@exemplo.com",
    "phone": "11999998888",
    "document": {
      "number": "12345678901",
      "type": "cpf"
    }
  }
}
CampoTipoObrig.Descrição
amountCentsinteirosimValor em centavos. Mínimo: 100 (R$ 1,00).
customerobjetosimDados do pagador (ver abaixo).
customer.namestringsimNome do pagador. Máx. 100 caracteres.
customer.emailstringsimE-mail válido do pagador. Máx. 254 caracteres.
customer.phonestringsimTelefone do pagador, com DDD (10 ou 11 dígitos, somente números).
customer.document.numberstringsimDocumento. Aceita dígitos, pontos, traços e barras (formatação é removida). Deve ter 11 dígitos para cpf ou 14 dígitos para cnpj após remover formatação.
customer.document.typestringsim"cpf" ou "cnpj". Variações de case e whitespace são normalizadas automaticamente — "CNPJ", "Cpf", " cnpj " são aceitos. Recomendado enviar em lowercase.
externalRefstringnãoIdentificador no seu sistema. Usado como chave de idempotência.
expiresInDaysinteironãoValidade em dias (1 a 30). Default: 2.
Idempotência via externalRef

Reenviar a mesma externalRef retorna a cobrança original com "idempotent": true. Use sempre que possível, especialmente em retries de timeout.

Resposta 201 Created

{
  "transactionId": "Q4t9aV...",
  "status": "pending",
  "pixPayload": "00020126580014BR.GOV.BCB.PIX...6304ABCD",
  "expiresAt": 1715000000,
  "amountCents": 1000
}
CampoDescrição
transactionIdID interno da transação. Use para consultar status.
statusSempre "pending" na criação.
pixPayloadString copia-e-cola PIX (BR Code EMV). Apresente ao pagador ou gere o QR Code dela.
expiresAtUnix timestamp em segundos da expiração.
amountCentsEco do valor enviado.

Resposta 200 OK (idempotente)

Quando externalRef já foi usada antes:

{
  "transactionId": "Q4t9aV...",
  "status": "pending",
  "pixPayload": "...",
  "expiresAt": 1715000000,
  "amountCents": 1000,
  "idempotent": true
}

Erros

HTTPerror
400"amountCents deve ser inteiro ≥ 100 (R$1,00 mínimo)."
400"customer.name obrigatório."
400"customer.document.number e customer.document.type obrigatórios."
400"customer.document.type é obrigatório."
400"customer.document.type deve ser 'cpf' ou 'cnpj'. Recebido: '<valor>'."
400"customer.document.number deve ter 11 dígitos para cpf. Recebido: <N> dígitos."
400"customer.document.number deve ter 14 dígitos para cnpj. Recebido: <N> dígitos."
400"customer.email é obrigatório e deve ser válido."
400"customer.phone é obrigatório (DDD + número, 10 ou 11 dígitos)."
400"Valor abaixo do mínimo (R$ X,YY)."
400"Valor acima do máximo (R$ X,YY)."
401"API key inválida ou revogada."
403"Conta não está aprovada para uso da API."
403"IP de origem não autorizado para esta chave."
429"Limite de requisições atingido. Tente em 1 hora."
502"Erro ao comunicar com gateway. Tente novamente."

Exemplos

curl -X POST https://api.internationalfinance.com.br/v1/pix \
  -H "Authorization: Bearer $INFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 1000,
    "externalRef": "pedido-123",
    "expiresInDays": 2,
    "customer": {
      "name": "Maria Silva",
      "email": "maria@exemplo.com",
      "phone": "11999998888",
      "document": { "number": "12345678901", "type": "cpf" }
    }
  }'

Próximo passo

Apresente pixPayload ao pagador (copia-e-cola ou gere o QR Code dela). Aguarde o webhook transaction.paid ou faça polling em GET /v1/transactions/:id.