Transferencia PIX

Visión General

El endpoint POST /api/dict/pix inicia una transferencia PIX a la clave informada. La clave puede ser CPF, CNPJ, correo electrónico, teléfono o EVP (clave aleatoria).

La respuesta síncrona confirma que la transferencia fue aceptada para procesamiento. El resultado final (LIQUIDATED o ERROR) llega por el webhook TRANSFER.

Endpoint

POST https://api.fypay.me/api/dict/pix

Headers

stringobrigatorio

Token Bearer obtenido en POST https://api.fypay.me/api/auth/token. Esta ruta no usa certificado de cliente.

stringobrigatorio

Identificador único de la transferencia generado por su sistema. Hasta 50 caracteres y único por cuenta (un UUID es una buena opción). Se convierte en el identificador externo de la transacción y vuelve en los campos endToEndId de la respuesta e idempotencyKey del webhook TRANSFER.

Ejemplo: 550e8400-e29b-41d4-a716-446655440000

Request Body

stringobrigatorio

Clave PIX de destino. El tipo se identifica por el formato:

Correo electrónico: contiene @
EVP: UUID (clave aleatoria)
Teléfono: con código de país, en el formato +55DDDNUMERO (ej.: +5511999999999)
CPF: 11 dígitos
CNPJ: 14 dígitos

string

CPF o CNPJ del destinatario. Se envía al proveedor de liquidación, y algunos proveedores exigen ese documento. Cuando se omite, la API usa los dígitos de la propia clave.

string

Mensaje que acompaña la transferencia PIX. Vuelve en data.remittanceInformation en el webhook TRANSFER.

objectobrigatorio

Datos del pago.

string

HIGH o NORM. Se acepta por compatibilidad y se valida, pero no altera el procesamiento.

string

Se acepta por compatibilidad, sin efecto.

number

Entre 1 y 10800. Se acepta por compatibilidad y se valida, pero no altera el procesamiento.

array

Lista de strings. Se acepta por compatibilidad, sin efecto: la API no bloquea instituciones por ISPB.

Request

curl -X POST https://api.fypay.me/api/dict/pix \
  -H "Authorization: Bearer <token>" \
  -H "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "pixKey": "destino@email.com",
    "creditorDocument": "12345678909",
    "description": "Pago referente a la factura 12345",
    "payment": {
      "currency": "BRL",
      "amount": 100.50
    }
  }'

const idempotencyKey = crypto.randomUUID();

const response = await fetch('https://api.fypay.me/api/dict/pix', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'x-idempotency-key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    pixKey: 'destino@email.com',
    creditorDocument: '12345678909',
    description: 'Pago referente a la factura 12345',
    payment: {
      currency: 'BRL',
      amount: 100.50,
    },
  }),
});

const transfer = await response.json();

import requests
import uuid

idempotency_key = str(uuid.uuid4())

response = requests.post(
    'https://api.fypay.me/api/dict/pix',
    headers={
        'Authorization': f'Bearer {token}',
        'x-idempotency-key': idempotency_key,
        'Content-Type': 'application/json',
    },
    json={
        'pixKey': 'destino@email.com',
        'creditorDocument': '12345678909',
        'description': 'Pago referente a la factura 12345',
        'payment': {
            'currency': 'BRL',
            'amount': 100.50,
        },
    }
)

transfer = response.json()

Response

{
  "endToEndId": "550e8400-e29b-41d4-a716-446655440000",
  "eventDate": "2024-01-15T10:30:00.000Z",
  "id": 12345,
  "payment": {
    "amount": 100.5
  },
  "type": "PENDING"
}

{
  "statusCode": 400,
  "code": "PIX_INSUFFICIENT_BALANCE",
  "userMessage": "Saldo insuficiente para realizar esta operação.",
  "details": {
    "availableReais": "50.00",
    "requiredReais": "100.50"
  },
  "errorId": "c0a8012e-7b1f-4c55-9d1e-2f9a8c3b4d5e"
}

{
  "statusCode": 422,
  "code": "PIX_KEY_NOT_FOUND",
  "details": {
    "cached": true,
    "retryAfterSeconds": 300
  },
  "errorId": "c0a8012e-7b1f-4c55-9d1e-2f9a8c3b4d5e"
}

Campos de la Respuesta

endToEndIdstring

No es el End to End ID del PIX. Este campo devuelve el valor del header x-idempotency-key. El End to End ID real llega en data.endToEndId en el webhook TRANSFER.

eventDatestring

Fecha y hora de creación de la transferencia (ISO 8601).

idnumber

ID de la transacción en FyPay. Es el mismo valor de data.id en el webhook TRANSFER.

paymentobject

typestring

Estado de la transacción en el momento de la respuesta:

PENDING: transferencia en procesamiento (caso normal)
CONFIRMED: transferencia ya confirmada
ERROR: falla en la transferencia

Idempotencia

El x-idempotency-key es obligatorio y debe ser único por cuenta. Protege contra el envío duplicado: si repite una clave ya usada, no se crea ninguna transferencia nueva y la API responde 400 con el código PIX_DUPLICATE_EXTERNAL_ID. El campo details.existingTransactionId trae el ID de la transferencia original.

const key = '550e8400-e29b-41d4-a716-446655440000';

const res1 = await createTransfer(key, { amount: 100 });

const res2 = await createTransfer(key, { amount: 100 });

La primera llamada crea la transferencia (201, type: "PENDING"). La segunda se rechaza con 400 PIX_DUPLICATE_EXTERNAL_ID, sin débito. Para seguir el resultado de la primera, espere el webhook TRANSFER o consulte GET https://api.fypay.me/api/pix/transaction/{id} con el id numérico o con la propia clave.

Después de un error 5xx o de un timeout, no cambie la clave para intentarlo de nuevo: el pago puede haber salido. Espere el webhook TRANSFER correlacionando por data.idempotencyKey. Vea TRANSFER.

Webhook de Transferencia

Cuando se procesa la transferencia, las URLs registradas para el evento cash_out con el formato PIX BACEN reciben un webhook del tipo TRANSFER (fragmento):

{
  "data": {
    "id": 12345,
    "txId": "550e8400-e29b-41d4-a716-446655440000",
    "pixKey": "destino@email.com",
    "status": "LIQUIDATED",
    "payment": {
      "amount": "100.5",
      "currency": "BRL"
    },
    "endToEndId": "E12345678202401151030abcdefghijk",
    "creditDebitType": "DEBIT",
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "creditorAccount": {
      "ispb": "12345678",
      "name": "João Silva",
      "bankName": "Banco Exemplo S.A.",
      "issuer": "000",
      "number": "123456",
      "document": "12345678909",
      "accountType": null
    },
    "remittanceInformation": "Pago referente a la factura 12345"
  },
  "type": "TRANSFER"
}

Webhook TRANSFER

Vea la documentación completa del webhook TRANSFER

Errores Comunes

Código HTTP	`code`	Causa	Qué hacer
400	`PUB_REQUEST_BODY_INVALID`	Cuerpo inválido (`amount` ausente o menor que `0.01`, `priority` distinto de `HIGH`/`NORM` etc.)	Revise `details.violations`
400	`PIX_DUPLICATE_EXTERNAL_ID`	`x-idempotency-key` ya usado en esta cuenta	No se creó nada; vea `details.existingTransactionId`
400	`PIX_INSUFFICIENT_BALANCE`	Saldo insuficiente	Consulte el saldo e intente con una nueva clave
401		Token ausente, inválido o expirado	Genere un nuevo token
422	`PIX_KEY_NOT_FOUND`	La clave no existe en el DICT	Confirme la clave con el destinatario. Con `details.cached: true`, espere `details.retryAfterSeconds`. Vea Clave inexistente
429	`TOO_MANY_PIX_KEYS_NOT_FOUND`	Demasiadas claves inexistentes en el retiro por clave	Espere el tiempo del header `Retry-After`. Vea Proveedor bloqueando consultas

Transferencia PIX

Visión General

Endpoint

Headers

Request Body

Request

Response

Campos de la Respuesta

Idempotencia

Webhook de Transferencia

Webhook TRANSFER

Errores Comunes

Próximos Pasos

Consultar Saldo

Webhook TRANSFER

En esta página

Transferencia PIX

Propiedades

Propiedades

Webhook TRANSFER

Consultar Saldo

Webhook TRANSFER

En esta página