Guías

Cobrar a cuotas

Solo la tarjeta de crédito hace cuotas, y el plan lo decide el banco emisor, no tú.

Hay dos formas de llegar a un cobro a cuotas, y no funcionan igual. En la pantalla de pago solo puedes abrir o cerrar la puerta: si la abres, el comprador elige el plan con su banco. En un cobro directo contra una tarjeta guardada sí puedes fijar la cantidad.

En la pantalla de pago

Abrir la opción de cuotas

{
  "amount": 89000000,
  "currency": "COP",
  "description": "Pedido #4821",
  "checkout_options": { "allow_installments": true }
}

Con eso, la pantalla le ofrece cuotas a quien pague con crédito. Cuántas y a qué interés lo define el emisor: Lane no impone el plan ni lo conoce de antemano.

En un cobro directo

Contra una tarjeta ya guardada sí puedes pedir una cantidad concreta. El mínimo es 2: para un pago normal, omite el objeto installments en vez de mandar 1.

Tres cuotas

curl -X POST https://api.lane.money/v1/payments \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 89000000,
    "currency": "COP",
    "instrument_id": "c1a9…",
    "initiator": "customer",
    "cvv": "123",
    "order_type": "purchase",
    "installments": { "quantity": 3 }
  }'

Verifica el BIN antes de ofrecer

Consulta el BIN —los primeros 6 a 8 dígitos— o lee la tarjeta guardada, y ofrécele cuotas al comprador solo si supports_installments viene en true, que es cuando la tarjeta es de crédito. Una débito puede aprobar el cobro en una sola cuota aunque hayas pedido más. Si es false, no muestres la opción. La respuesta trae también issuer_country, el país del banco emisor: es informativo y no cambia supports_installments.

Consultar un BIN

curl "https://api.lane.money/v1/bins/518617" \
  -H "Authorization: Bearer sk_test_…"

Respuesta 200

{
  "object": "bin",
  "bin_number": "518617",
  "brand": "MASTERCARD",
  "product": "CREDIT",
  "issuer_country": "US",
  "supports_installments": true
}

Cuando el emisor aplica menos cuotas

supports_installments: true dice que tiene sentido ofrecer cuotas, no que se vayan a aplicar: el plan lo decide el emisor al autorizar. La respuesta del cobro trae installments (lo que pediste) e installment (lo que aplicó el emisor).

No reintentes: el cobro ya está hecho. Si installment.quantity vuelve menor a lo que pediste, el cobro quedó autorizado por el total. No es un error. Reintentarlo cobra dos veces. Acepta el pago en una cuota y avísale al comprador, o anúlalo con POST /v1/payments/{id}/cancel-or-refund, que sirve tanto si la captura ya pasó como si no.

En sandbox, cuenta con una sola cuota. Hay tarjetas de crédito de prueba (4258 1800 0000 0001 y 4242 4242 4242 4242: la consulta de BIN dice que admiten cuotas), pero no hemos visto al simulador aplicar un plan: la que se probó pidiendo uno se aprobó con una cuota. Puedes probar el camino completo —consultar, pedir cuotas, leer lo aplicado— sin esperar que el emisor aplique el plan. La API acepta de 2 a 48 cuotas.

Esta página en markdown: /docs/guias/cuotas.md · Toda la documentación: /docs/llms-full.txt