EspañolReferencia de la APICobrosCrear cobro PIX

Crear cobro PIX

POST/v1/pix
Crea un cobro PIX dinámico y devuelve el copiar-y-pegar para pagar.

Solicitud

Encabezados

EncabezadoObligatorioDescripción
AuthorizationBearer <TU_API_KEY>
Content-Typeapplication/json

Cuerpo

{
  "amountCents": 1000,
  "externalRef": "pedido-123",
  "expiresInDays": 2,
  "customer": {
    "name": "Maria Silva",
    "email": "maria@ejemplo.com",
    "phone": "11999998888",
    "document": {
      "number": "12345678901",
      "type": "cpf"
    }
  }
}
CampoTipoObl.Descripción
amountCentsenteroValor en centavos. Mínimo: 100 (R$ 1,00).
customerobjetoDatos del pagador (ver abajo).
customer.namestringNombre del pagador. Máx. 100 caracteres.
customer.emailstringCorreo válido del pagador. Máx. 254 caracteres.
customer.phonestringTeléfono del pagador con DDD (10 u 11 dígitos, solo números).
customer.document.numberstringDocumento. Acepta dígitos, puntos, guiones y barras (el formato se quita). Debe tener 11 dígitos para cpf o 14 dígitos para cnpj tras limpiar.
customer.document.typestring"cpf" o "cnpj". Las variaciones de case y whitespace se normalizan — "CNPJ", "Cpf", " cnpj " son aceptados. Se recomienda enviarlo en minúsculas.
externalRefstringnoIdentificador en tu sistema. Se usa como clave de idempotencia.
expiresInDaysenteronoValidez en días (1 a 30). Por defecto: 2.
Idempotencia vía externalRef

Reenviar el mismo externalRef devuelve el cobro original con "idempotent": true. Úsalo siempre que sea posible, especialmente en reintentos por timeout.

Respuesta 201 Created

{
  "transactionId": "Q4t9aV...",
  "status": "pending",
  "pixPayload": "00020126580014BR.GOV.BCB.PIX...6304ABCD",
  "expiresAt": 1715000000,
  "amountCents": 1000
}
CampoDescripción
transactionIdID interno de la transacción. Úsalo para consultar el estado.
statusSiempre "pending" en la creación.
pixPayloadString copiar-y-pegar PIX (BR Code EMV). Muéstralo al pagador o genera el QR Code.
expiresAtTimestamp Unix en segundos de la expiración.
amountCentsEco del valor enviado.

Respuesta 200 OK (idempotente)

Cuando externalRef ya fue usado antes:

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

Errores

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."

Ejemplos

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@ejemplo.com",
      "phone": "11999998888",
      "document": { "number": "12345678901", "type": "cpf" }
    }
  }'

Próximo paso

Muestra pixPayload al pagador (copiar-y-pegar o genera el QR Code). Espera el webhook transaction.paid o haz polling en GET /v1/transactions/:id.