Primeros pasos

Cinco minutos para tu primer Cobro (charge).

#1. Obtén tu clave de API

Inicia sesión en el Dashboard de Liqfy → Settings → API Keys → Create key, o hazlo mediante HTTP / CLI como se documenta en Claves de API.

Recibirás una clave con este aspecto:

lq_test_8f3a9b2c1d4e5f6a7b8c9d0e1f2a3b4c

Las claves lq_test_* acceden a la misma infraestructura de producción con un comportamiento seguro para pruebas durante el trabajo de integración; las claves lq_live_* mueven dinero real. Trata ambas como una contraseña. Cualquiera que tenga una clave puede crear cobros facturados a tu cuenta. Guárdala solo en el servidor — nunca la incluyas en un navegador ni en una app móvil. El texto en claro se muestra exactamente una vez al emitirla — consulta Claves de API para rotarla si la pierdes.

#2. Elige tu entorno

Todos los ejemplos de esta guía usan la URL base de producción.

#3. Haz tu primera llamada

curl -X POST https://api.liqfy.com.br/v1/charges \
  -H "Authorization: Bearer $LIQFY_API_KEY" \
  -H "Idempotency-Key: order-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "BRL",
    "payment_method": "pix",
    "description": "Pedido #12345",
    "customer": { "name": "Maria Silva", "document": "12345678901" },
    "metadata": { "order_id": "12345" }
  }'

Respuesta exitosa (201 Created):

{
  "id": "ch_a1b2c3d4-0000-0000-0000-000000000009",
  "object": "charge",
  "amount": 1000,
  "currency": "BRL",
  "status": "pending",
  "payment_method": "pix",
  "customer": { "name": "Maria Silva", "document": "12345678901" },
  "pix": {
    "br_code": "000201BRCODEPIX",
    "qr_code_url": "https://qr.example/img.png",
    "expires_at": "2026-07-23T15:00:00.000Z"
  },
  "settlement": {},
  "metadata": { "order_id": "12345" },
  "created_at": "2026-07-23T14:30:00.000Z"
}

El id (ch_…) es el identificador de tu cobro — úsalo para consultar el estado y conciliar los webhooks. Para Pix, el BR Code y el código QR ya vienen en la respuesta de creación: no hace falta hacer polling posterior para renderizar el checkout.

pix.txid y settlement.end_to_end_id son datos contextuales de Pix del BACEN, no identificadores — consulta PIX. settlement permanece en {} hasta que el cobro esté paid.

#4. Convenciones

Estas reglas se aplican a todos los endpoints Liqfy de la familia /v1/charges.

#Autenticación

Cada solicitud a un endpoint con ámbito de comercio incluye tu clave de API en el encabezado Authorization: Bearer:

Authorization: Bearer lq_live_...

El encabezado heredado apikey: lq_live_... se sigue aceptando por compatibilidad — las nuevas integraciones deben usar Bearer y nada más.

Las claves ausentes o no válidas devuelven 401 Unauthorized.

#Los importes son enteros en la unidad monetaria más pequeña

Por ahora, los cobros Pix se liquidan solo en BRL. Nunca envíes decimales — 10.00 se rechaza.

#La idempotencia es obligatoria en las escrituras

Cada POST /v1/charges debe incluir el encabezado Idempotency-Key (cualquier cadena no vacía, con ámbito por (merchant, key) — la misma clave de otro comercio nunca entra en conflicto). En POST /payments se acepta el campo del cuerpo idempotencyKey como alias del mismo encabezado.

Reenviar la misma clave con el mismo cuerpo de solicitud devuelve la respuesta almacenada, lo que garantiza que un reintento de red, un doble toque en la app móvil o el reinicio de un job en segundo plano nunca cobre dos veces. Reutilizar la clave con un cuerpo diferente devuelve 409 y error.code: "idempotency_key_reused" (consulta Errores). El servidor conserva el registro durante al menos 24 horas.

Recomendado: usa tu id de pedido interno (p. ej., order-12345) o un UUID v4.

#Las marcas de tiempo están en ISO 8601 UTC

2026-07-23T14:30:00.000Z

#Identificadores

El id de un cobro siempre lleva el prefijo ch_ seguido de una cadena opaca con forma de UUID — por ejemplo, ch_a1b2c3d4-e5f6-4789-9abc-def012345678. Trátalo como una cadena opaca: no lo analices, no lo ordenes lexicográficamente y no deduzcas ningún orden a partir del valor. ch_… es siempre el id de Liqfy; el pix.txid y el settlement.end_to_end_id del BACEN son datos contextuales de Pix y nunca lo sustituyen.

#Errores

Todos los errores devuelven el sobre canónico:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "Validation failed",
    "details": [
      { "param": "amount", "message": "must be a positive integer" }
    ]
  },
  "request_id": "req_01J..."
}

Cada respuesta — de éxito o de error — también incluye X-Request-Id. Consulta Errores para ver el sobre completo y el mapa de códigos de estado.

#Límites de tasa

200 req/sec, 5000 req/min, 50000 req/hour por clave de API autenticada de forma predeterminada (plugin rate-limiting de Kong, con ámbito por consumidor). ¿Necesitas más? Escribe a suporte@liqfy.com.br.

#5. Ciclo de vida del cobro

                  ┌──────────────────────┐
                  │        pending        │  ← created, awaiting payer
                  └──────────┬───────────┘
                             │
                ┌────────────┼────────────┐
                ▼            ▼            ▼
          ┌─────────┐  ┌──────────┐  ┌─────────┐
          │  paid   │  │ expired  │  │ failed  │
          └────┬────┘  └──────────┘  └─────────┘
               │
               ▼
          ┌──────────┐
          │ refunded │
          └──────────┘

Vocabulario público de estados: pending, processing, paid, failed, expired, cancelled, refunded, disputed. Son estados estables sobre los que puedes ramificar tu lógica; los estados internos de los que se derivan nunca aparecen en una respuesta /v1/charges.

Tu hook de fulfillment debe dispararse en paid. Todo lo demás es informativo — para esa transición, prefiere los webhooks en lugar del polling.

#6. Consulta tu saldo

En cuanto los cobros empiecen a liquidarse, tu saldo disponible está a una llamada de distancia — la misma clave, sin cuerpo. El parámetro de consulta currency es opcional; sin él obtienes todas las monedas de la cuenta:

curl "https://api.liqfy.com.br/v1/wallets/balance" \
  -H "Authorization: Bearer $LIQFY_API_KEY"

{
  "available": 880,
  "pending": 0,
  "total": 880,
  "retained": 0,
  "currency": "BRL",
  "next_release_at": null,
  "next_release_amount": null,
  "balances": [
    { "currency": "BRL", "available": 880, "held": 0, "pending": 0, "total": 880 }
  ],
  "primary": { "currency": "BRL", "available": 880, "held": 0, "pending": 0, "total": 880 }
}

Los importes están en centavos (880 = R$ 8,80). available es lo que puedes gastar o pagar ahora mismo (con signo — puede ser negativo; sumado sobre las billeteras de la moneda); held es dinero en tránsito que está retenido; pending es lo liquidado pero aún no liberado e incluye las retenciones por reembolsos en curso, por lo que puede ser mayor que retained. total es available + held + pending. Cuando hay una liberación programada, next_release_at / next_release_amount te indican cuándo y cuánto. Cada moneda de la cuenta aparece en balances[].

¿Solo una moneda? Añade ?currency=BRL para obtener la forma plana. ¿Necesitas todas las billeteras (por tipo)? GET /v1/wallets devuelve la lista completa. Consulta la Referencia de la API.

#Siguiente

→ Construye el flujo PIX