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çalho | Obrigatório | Descrição |
|---|---|---|
Authorization | sim | Bearer <SUA_API_KEY> |
Content-Type | sim | application/json |
Corpo
{
"amountCents": 1000,
"externalRef": "pedido-123",
"expiresInDays": 2,
"customer": {
"name": "Maria Silva",
"email": "maria@exemplo.com",
"phone": "11999998888",
"document": {
"number": "12345678901",
"type": "cpf"
}
}
}| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
amountCents | inteiro | sim | Valor em centavos. Mínimo: 100 (R$ 1,00). |
customer | objeto | sim | Dados do pagador (ver abaixo). |
customer.name | string | sim | Nome do pagador. Máx. 100 caracteres. |
customer.email | string | sim | E-mail válido do pagador. Máx. 254 caracteres. |
customer.phone | string | sim | Telefone do pagador, com DDD (10 ou 11 dígitos, somente números). |
customer.document.number | string | sim | Documento. 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.type | string | sim | "cpf" ou "cnpj". Variações de case e whitespace são normalizadas automaticamente — "CNPJ", "Cpf", " cnpj " são aceitos. Recomendado enviar em lowercase. |
externalRef | string | não | Identificador no seu sistema. Usado como chave de idempotência. |
expiresInDays | inteiro | não | Validade 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
}| Campo | Descrição |
|---|---|
transactionId | ID interno da transação. Use para consultar status. |
status | Sempre "pending" na criação. |
pixPayload | String copia-e-cola PIX (BR Code EMV). Apresente ao pagador ou gere o QR Code dela. |
expiresAt | Unix timestamp em segundos da expiração. |
amountCents | Eco 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
| HTTP | error |
|---|---|
| 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.