Crear cobro PIX
POST/v1/pix
Crea un cobro PIX dinámico y devuelve el copiar-y-pegar para pagar.Solicitud
Encabezados
| Encabezado | Obligatorio | Descripción |
|---|---|---|
Authorization | sí | Bearer <TU_API_KEY> |
Content-Type | sí | application/json |
Cuerpo
{
"amountCents": 1000,
"externalRef": "pedido-123",
"expiresInDays": 2,
"customer": {
"name": "Maria Silva",
"email": "maria@ejemplo.com",
"phone": "11999998888",
"document": {
"number": "12345678901",
"type": "cpf"
}
}
}| Campo | Tipo | Obl. | Descripción |
|---|---|---|---|
amountCents | entero | sí | Valor en centavos. Mínimo: 100 (R$ 1,00). |
customer | objeto | sí | Datos del pagador (ver abajo). |
customer.name | string | sí | Nombre del pagador. Máx. 100 caracteres. |
customer.email | string | sí | Correo válido del pagador. Máx. 254 caracteres. |
customer.phone | string | sí | Teléfono del pagador con DDD (10 u 11 dígitos, solo números). |
customer.document.number | string | sí | Documento. 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.type | string | sí | "cpf" o "cnpj". Las variaciones de case y whitespace se normalizan — "CNPJ", "Cpf", " cnpj " son aceptados. Se recomienda enviarlo en minúsculas. |
externalRef | string | no | Identificador en tu sistema. Se usa como clave de idempotencia. |
expiresInDays | entero | no | Validez 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
}| Campo | Descripción |
|---|---|
transactionId | ID interno de la transacción. Úsalo para consultar el estado. |
status | Siempre "pending" en la creación. |
pixPayload | String copiar-y-pegar PIX (BR Code EMV). Muéstralo al pagador o genera el QR Code. |
expiresAt | Timestamp Unix en segundos de la expiración. |
amountCents | Eco 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
| 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." |
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.