Transferencia PIX
Descripción general
El endpoint POST /dict/pix inicia una transferencia PIX a la clave especificada. La clave puede ser un CPF, CNPJ, correo electrónico, número de telefono o EVP (clave aleatoria).
Este endpoint sigue la especificacion del Banco Central para transferencias PIX via DICT (Directorio de Identificadores de Cuentas Transaccionales).
Endpoint
POST /dict/pixAutenticación
Token Bearer obtenido via /oauth/token.
Identificador único de la solicitud para soporte de idempotencia. Debe ser un UUID v4.
Ejemplo: 550e8400-e29b-41d4-a716-446655440000
Cuerpo de la Solicitud
Clave PIX de destino. Puede ser:
- CPF: 11 digitos numericos
- CNPJ: 14 digitos numericos
- Email: dirección de correo electrónico valida
- Telefono: +55CODIGOAREANUMERO (ej., +5511999999999)
- EVP: Clave aleatoria (UUID)
Documento del acreedor (CPF o CNPJ). Requerido cuando priority = HIGH para validación instantanea.
Prioridad de procesamiento:
HIGH: Procesado instantaneamente (requierecreditorDocument)NORM: Procesamiento estandar en cola
Mensaje que acompana la transferencia PIX. Se mostrara al destinatario.
Flujo de pago (opcional). Usado para categorizacion interna.
Tiempo máximo en segundos que la operación puede permanecer en la cola antes de ser cancelada.
- Mínimo: 1 segundo
- Máximo: 10800 segundos (3 horas)
- Por defecto: 600 segundos (10 minutos)
Datos del pago.
Lista de códigos ISPB para los cuales no se permitiran pagos. Útil para bloquear transferencias a instituciones especificas.
Ejemplo: ["12345678", "87654321"]
Solicitud
curl -X POST https://api.gateway.goforge.com.br/dict/pix \
-H "Authorization: Bearer <token>" \
-H "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{
"pixKey": "12345678909",
"creditorDocument": "12345678909",
"priority": "NORM",
"description": "Pagamento referente a NF 12345",
"expiration": 600,
"payment": {
"currency": "BRL",
"amount": 100.50
}
}'const response = await fetch('https://api.gateway.goforge.com.br/dict/pix', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'x-idempotency-key': crypto.randomUUID(),
'Content-Type': 'application/json',
},
body: JSON.stringify({
pixKey: '12345678909',
creditorDocument: '12345678909',
priority: 'NORM',
description: 'Pagamento referente a NF 12345',
expiration: 600,
payment: {
currency: 'BRL',
amount: 100.50,
},
}),
});
const transfer = await response.json();import requests
import uuid
response = requests.post(
'https://api.gateway.goforge.com.br/dict/pix',
headers={
'Authorization': f'Bearer {token}',
'x-idempotency-key': str(uuid.uuid4()),
'Content-Type': 'application/json',
},
json={
'pixKey': '12345678909',
'creditorDocument': '12345678909',
'priority': 'NORM',
'description': 'Pagamento referente a NF 12345',
'expiration': 600,
'payment': {
'currency': 'BRL',
'amount': 100.50,
},
}
)
transfer = response.json()Respuesta
{
"endToEndId": "550e8400-e29b-41d4-a716-446655440000",
"eventDate": "2024-01-15T10:30:00.000Z",
"id": 12345,
"payment": {
"amount": 100.50
},
"type": "PENDING"
}{
"statusCode": 400,
"message": "Chave PIX invalida",
"error": "Bad Request"
}{
"statusCode": 422,
"message": "Chave PIX nao encontrada no DICT",
"error": "Unprocessable Entity"
}Campos de Respuesta
endToEndIdstringIdentificador único de la transacción PIX. El valor E2E real sera enviado en el webhook cuando la transacción se liquide.
eventDatestringFecha y hora del evento (ISO 8601).
idnumberIdentificador único de la transacción.
paymentobjecttypestringTipo/estado de la transacción:
PENDING: Transferencia en procesamientoCOMPLETED: Transferencia completadaERROR: Transferencia fallida
Idempotencia
El header x-idempotency-key asegura que la misma solicitud no sea procesada mas de una vez:
// Misma clave de idempotencia = misma respuesta
const key = '550e8400-e29b-41d4-a716-446655440000';
// Primera llamada - crea la transferencia
const res1 = await createTransfer(key, { amount: 100 });
// { id: 123, type: 'PENDING' }
// Segunda llamada con la misma clave - retorna la misma transferencia
const res2 = await createTransfer(key, { amount: 100 });
// { id: 123, type: 'PENDING' } (no crea una nueva)El x-idempotency-key es obligatorio. Las solicitudes sin este header seran rechazadas.
Webhook de Transferencia
Cuando la transferencia es procesada, recibira un webhook V2 de tipo TRANSFER:
{
"type": "TRANSFER",
"data": {
"id": 12345,
"txId": null,
"pixKey": "12345678909",
"status": "LIQUIDATED",
"payment": {
"amount": "100.50",
"currency": "BRL"
},
"endToEndId": "E12345678901234567890123456789012",
"creditDebitType": "DEBIT",
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
"creditorAccount": {
"name": "Joao Silva",
"document": "123.xxx.xxx-xx",
"ispb": "18236120"
},
"remittanceInformation": "Pagamento referente a NF 12345"
}
}Webhooks TRANSFER
Vea la documentación completa del webhook TRANSFER
Tipos de Clave PIX
| Tipo | Formato | Ejemplo |
|---|---|---|
| CPF | 11 digitos | 12345678909 |
| CNPJ | 14 digitos | 12345678000195 |
| correo valido | joao@email.com | |
| Telefono | +55CODIGOAREANUMERO | +5511999999999 |
| EVP | UUID | 7d9f0335-8dcc-4054-9bf9-0dbd61d36906 |
Prioridad de Procesamiento
Bloqueo por ISPB
Use ispbDeny para bloquear transferencias a instituciones especificas:
{
"pixKey": "joao@email.com",
"payment": { "amount": 100.00 },
"ispbDeny": [
"12345678",
"87654321"
]
}Si la clave PIX pertenece a una institucion bloqueada, la transferencia sera rechazada.
Errores Comunes
| Código | Error | Solución |
|---|---|---|
| 400 | Clave PIX invalida | Verifique el formato de la clave |
| 400 | Valor invalido | Use un número con hasta 2 decimales |
| 400 | Clave de idempotencia faltante | Incluya el header x-idempotency-key |
| 401 | Token invalido | Renueve el token de acceso |
| 422 | Clave no encontrada | La clave no existe en el DICT |
| 422 | Saldo insuficiente | Verifique el saldo disponible |
| 422 | ISPB bloqueado | La institucion esta en la lista ispbDeny |