Pagos con tarjeta

Acepta Visa, Mastercard, American Express, Elo, Hipercard y otras redes principales mediante una página de pago alojada por Liqfy: ningún dato de tarjeta pasa por tus servidores y 3D Secure se gestiona automáticamente.

#Resumen del flujo

1. POST /v1/payments  ──────▶  Liqfy returns the payment: id, status WAITING_PAYMENT, cardRedirectUrl + checkoutUrl
2. Redirect (or open in iframe) the customer to cardRedirectUrl
3. Customer enters card details + completes 3DS challenge on Liqfy's secure page
4. Customer is bounced back to your returnUrl (success or failure)
5. Webhook charge.paid (or charge.failed) confirms the outcome — trust the webhook, not the redirect

¿Por qué una redirección? Mantiene los datos del titular de la tarjeta completamente fuera de tu infraestructura. Tu aplicación —backend o frontend— nunca ve un PAN, CVV ni fecha de caducidad. El procesador de Liqfy gestiona 3DS, la tokenización y el análisis de fraude de nuestro lado.

#1. Crear el pago

Endpoint POST /v1/payments

curl -X POST https://api.liqfy.com.br/v1/payments \
  -H "Authorization: Bearer $LIQFY_API_KEY" \
  -H "Idempotency-Key: ORD-9821" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 8990,
    "currency": "EUR",
    "paymentMethods": ["CREDIT_CARD"],
    "customerName": "João Costa",
    "customerEmail": "joao@example.com",
    "customerPhone": "+351912345678",
    "returnUrl": "https://shop.example.com/orders/9821/return",
    "cancelUrl": "https://shop.example.com/cart",
    "metadata": { "orderId": "ORD-9821" }
  }'

Idempotencia. POST /v1/payments acepta la cabecera Idempotency-Key (preferida) o el campo del cuerpo idempotencyKey como alternativa cuando falta la cabecera; envía al menos uno. Si envías ambos, deben coincidir: los valores divergentes devuelven 400, y no enviar ninguno devuelve 400 en esta ruta. Se admite cualquier cadena no vacía (se recortan los espacios en blanco circundantes), con ámbito por comercio ((merchant, key)): repetir la misma clave y el mismo cuerpo devuelve la respuesta almacenada; la misma clave con un cuerpo diferente devuelve 409. La cabecera Idempotency-Replayed no se emite en esta ruta: no construyas lógica de reintentos basada en ella.

Respuesta 201 Created: la respuesta de creación ya incluye los artefactos del método (aquí cardRedirectUrl) y checkoutUrl; no necesitas un GET posterior para verlos.

{
  "id": "b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
  "status": "WAITING_PAYMENT",
  "amount": 8990,
  "currency": "EUR",
  "paymentMethods": ["CREDIT_CARD"],
  "customerName": "João Costa",
  "customerEmail": "joao@example.com",
  "customerPhone": "+351912345678",
  "cardRedirectUrl": "https://checkout.liqfy.com.br/c/b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
  "checkoutUrl": "https://checkout.liqfy.com.br/b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
  "createdAt": "2026-04-25T15:50:11.000Z"
}

checkoutUrl solo está presente en la creación y la consulta; las filas del listado y la respuesta de cancelación lo omiten.

#Errores en la creación

Los errores 4xx del lado del proveedor mantienen el estado HTTP que devolvió la capa de enrutamiento. Los mensajes de error son neutros por diseño: nunca nombran al proveedor ni sus códigos internos; indica el id de la solicitud al soporte si necesitas el detalle.

Con el SDK oficial (el mismo paquete neutro para todas las marcas; configúralo con https://api.liqfy.com.br):

payments.list (GET /v1/payments) devuelve el sobre de página { data, total, page, limit }. Parámetros de consulta: page (por defecto 1), limit (por defecto 20, máx. 100), status, currency, startDate / endDate (fecha-hora ISO-8601), source (API, PANEL, MANUAL, INDEFINIDO), sortBy, sortOrder (asc / desc).

#2. Redirigir al cliente

cardRedirectUrl viene en la respuesta de creación (y en cada GET /v1/payments/{id}), así que puedes redirigir de inmediato:

curl https://api.liqfy.com.br/v1/payments/b2c3d4e5-f6a7-4890-9bcd-ef0123456789 \
  -H "Authorization: Bearer $LIQFY_API_KEY"

{
  "id": "b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
  "status": "WAITING_PAYMENT",
  "amount": 8990,
  "currency": "EUR",
  "cardRedirectUrl": "https://checkout.liqfy.com.br/c/b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
  "createdAt": "2026-04-25T15:50:11.000Z"
}

Envía al cliente a cardRedirectUrl:

<a href="{{ cardRedirectUrl }}">Pay with card</a>

O haz un 303 See Other del lado del servidor:

res.redirect(303, transaction.cardRedirectUrl);

Cuando el cliente completa el flujo (o lo abandona), vuelve a la returnUrl que proporcionaste (el checkout alojado lee la misma redirección de metadata.returnUrl), con ?transactionId=...&status=... añadido. No confíes en esos parámetros de consulta. Son solo informativos: espera al webhook antes de completar el pedido.

#3. Confirmar mediante webhook

{
  "id": "evt_00000000000000000000000000000001",
  "object": "event",
  "api_version": "2026-07-23",
  "type": "charge.paid",
  "created_at": "2026-04-25T15:52:34.000Z",
  "data": {
    "object": {
      "id": "ch_b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
      "object": "charge",
      "status": "paid",
      "amount": 8990,
      "currency": "EUR",
      "payment_method": "card",
      "settlement": {}
    }
  }
}

El estado público del cobro es paid para los pagos con tarjeta correctos. El vocabulario de estados públicos es pending, processing, paid, failed, expired, cancelled, refunded, disputed.

Los rechazos llegan como charge.failed; para la caducidad se prefiere charge.expired. Lee data.object.status para conocer el resultado público. El evento no expone los motivos de rechazo del emisor.

#Ciclo de vida

WAITING_PAYMENT  ──▶  PROCESSING  ──▶  APPROVED    ✓ fulfill order
                                  ──▶  REFUSED     issuer declined
                                  ──▶  CANCELLED   customer abandoned
                                  ──▶  EXPIRED     redirect link aged out (24h)

Después de la liquidación (de D+1 a D+30 según la red y tu contrato), también puedes ver:

APPROVED  ──▶  CHARGEBACK   issuer raised a chargeback
APPROVED  ──▶  DISPUTE      cardholder opened a dispute
APPROVED  ──▶  REFUNDED     you (or Liqfy) issued a refund

Cada uno dispara un webhook para que puedas sincronizar el estado del pedido.

#Otras operaciones sobre el pago

#Tarjetas de prueba

En sandbox, la página de redirección acepta estos números deterministas (cualquier fecha de caducidad futura, cualquier CVV):

Los cobros de sandbox se ejecutan en el simulador: nunca abonan saldo en tu monedero y se excluyen de las cifras de volumen, ingresos y métricas (aun así aparecen en los listados y en el detalle del cobro). Usa POST /v1/payments/{id}/confirm-sandbox para disparar el webhook de finalización de extremo a extremo con una clave de prueba.

Consulta sandbox para ver la lista completa.

#FAQ

P: ¿Puedo mantener al cliente en mi dominio? R: En la fase 2 lanzaremos un widget integrable (iframe + tokenizador) que conserva tu marca y, a la vez, mantiene los datos del titular de la tarjeta fuera de tu infraestructura. Por ahora: redirección alojada.

P: ¿Admiten tarjetas guardadas? R: Sí, pero requiere que tu lado cuente con su propia certificación de cumplimiento de seguridad de datos de tarjetas. Escribe a suporte@liqfy.com.br para habilitar la Vault API.

P: ¿Qué versión de 3DS se usa? R: 3DS 2.x con flujo sin fricción cuando el emisor lo permite. La autenticación reforzada de clientes (SCA) es obligatoria para EUR; se aplica del lado del servidor.

P: ¿Reembolsos? R: Hoy los reembolsos se solicitan desde el panel de administración, totales o parciales; la API no expone un endpoint de reembolso utilizable por el comercio: POST /v1/payments/{id}/refund con una clave de API devuelve 403 REFUND_ADMIN_ONLY. Aun así, puedes leer el historial de reembolsos con GET /v1/payments/{id}/refunds.

P: A mi cliente se le cobró, pero nunca recibí un webhook. R: Revisa GET /v1/webhooks/deliveries: probablemente lo intentamos y tu endpoint devolvió una respuesta distinta de 2xx. Reintentamos hasta 15 veces. Después, usa POST /v1/payments/{id}/resend-webhook o contacta con soporte para reenviarlo.

#Siguiente

→ MB WAY · Multibanco · Referencia de la API