Autorización de un Pago con Tarjeta

Después de tokenizar una tarjeta, envíe el token para crear una autorización de pago. Puede elegir entre:

• Preautorización ("capture": false) — Reserva los fondos sin liquidar. Usted captura más tarde, cuando esté listo.
• Captura directa ("capture": true) — Autoriza y captura en un solo paso. Los fondos se liquidan de inmediato.

Entendiendo la Preautorización vs. la Captura Directa

Este es uno de los conceptos más comúnmente malentendidos en los pagos con tarjeta. Hacerlo bien determina cuánto control tiene sobre su flujo de dinero — y qué tan rápido puede revertir una transacción si algo sale mal.

¿Qué es la preautorización?

Cuando establece "capture": false, el gateway le pide al banco del tarjetahabiente que reserve los fondos en su tarjeta — pero todavía no se mueve dinero. El tarjetahabiente ve un cargo "pendiente" en su estado de cuenta, pero la liquidación (la transferencia real de fondos a su cuenta) no ocurre hasta que usted capture el pago explícitamente.

Piénselo como colocar una retención (hold) sobre los fondos. El dinero sigue en la cuenta del tarjetahabiente, pero no puede gastarlo en otro lugar.

¿Por qué usar la preautorización?

La preautorización le da una ventana para realizar verificaciones adicionales antes de comprometerse con la liquidación financiera:

• Verificación AVS / CVC — Revise los resultados de dirección y código de seguridad de la respuesta de autorización. Si indican riesgo de fraude, puede cancelar de inmediato.
• Análisis antifraude — Pase la transacción por su sistema de puntuación de fraude, colas de revisión manual o herramientas de fraude de terceros.
• Verificaciones de inventario / cumplimiento del pedido — Confirme que el artículo está en stock, que el servicio está disponible o que pasa cualquier validación específica de su negocio.
• Cumplimiento / KYC — Verifique que el cliente cumple los requisitos regulatorios antes de finalizar la transacción.
• Ajustes del pedido — El monto final puede diferir de la retención inicial (p. ej., envíos parciales). Puede capturar un monto menor al autorizado.

La ventaja clave: reversión rápida y limpia

Si necesita cancelar una transacción preautorizada, realiza una anulación (void). Un void libera al instante la retención sobre los fondos del tarjetahabiente — típicamente en minutos. El tarjetahabiente ve desaparecer el cargo pendiente de su estado de cuenta. Nunca se movió dinero, así que no hay nada que "devolver".

Compare esto con lo que ocurre después de la captura: una vez que una transacción se captura, la liquidación ya ocurrió. El dinero salió de la cuenta del tarjetahabiente y llegó a la suya. La única manera de devolver fondos en ese punto es un reembolso, que es una transacción financiera separada que puede tardar de 3 a 10 días hábiles en aparecer en el estado de cuenta del tarjetahabiente.

Comparación lado a lado

Cuándo usar cada una

Use la preautorización (capture: false) cuando:

• Necesite tiempo para verificar señales de fraude, resultados de AVS/CVC o cumplimiento
• El monto final pueda cambiar (envíos parciales, propinas, cargos incidentales de hotel)
• Quiera la capacidad de cancelar limpiamente sin que un reembolso aparezca en el estado de cuenta del tarjetahabiente
• Su entrega tenga cualquier demora entre el pago y la entrega

Use la captura directa (capture: true) cuando:

• La transacción sea final e inmediata (descarga digital, compra en tienda)
• No se necesite revisión ni ajuste
• Quiera la integración más simple con menos llamadas a la API

El ciclo de vida de un vistazo

                 capture: false                    capture: true
                 ─────────────                     ─────────────
POST /v2/payment                          POST /v2/payment
       │                                         │
       ▼                                         ▼
   AUTHORIZED                                CAPTURED
   (funds held)                              (funds settled)
       │                                         │
   ┌───┴───┐                                     ▼
   │       │                                  REFUNDED
   ▼       ▼                               (3-10 days to
CAPTURED  VOIDED                            cardholder)
(settle)  (release hold,
   │       instant)
   ▼
REFUNDED
(3-10 days)

Conclusión: Si existe cualquier posibilidad de que necesite cancelar la transacción después de la autorización, use la preautorización. Es más rápida de revertir, más limpia para el tarjetahabiente y le da control total sobre el momento de la liquidación.

Endpoint

POST https://{FQDN}/v2/payment

Headers:

Cuerpo de la Solicitud

Objeto Raíz

Objeto amount

Objeto sender

Objeto sender.address

Objeto sender.paymentMethod (Tarjeta)

Ejemplo de Solicitud

curl -X POST https://{FQDN}/v2/payment \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalPaymentId": "order-12345",
    "ipAddress": "203.0.113.42",
    "paymentType": "PULL",
    "capture": false,
    "amount": {
      "total": 99.99,
      "currency": "USD"
    },
    "sender": {
      "firstName": "John",
      "lastName": "Smith",
      "address": {
        "countryCode": "US",
        "stateCode": "NY",
        "city": "New York",
        "line1": "123 Main Street",
        "line2": "Apt 4B",
        "zipCode": "10001"
      },
      "paymentMethod": {
        "type": "CARD",
        "cardTokenId": "ab5fc589-8b48-4531-94c0-68b0629c13fe"
      }
    }
  }'

Respuesta

Autorización Exitosa (200)

{
  "status": 200,
  "data": {
    "paymentId": "dce568c6-98ec-456c-bb33-4a6809c4fff8",
    "parentPaymentId": "dce568c6-98ec-456c-bb33-4a6809c4fff8",
    "externalPaymentId": "order-12345",
    "amount": 99.99,
    "created": "2025-03-31 03:49:05",
    "approved": true,
    "message": "Payment Approved",
    "automaticReversed": false,
    "status": "AUTHORIZED",
    "captured": false,
    "voided": false,
    "responseCode": "00",
    "issuerName": "BANK OF AMERICA",
    "issuerCountry": "UNITED STATES",
    "cvcResult": "APPROVED",
    "avsResult": "APPROVED",
    "avsCardholderNameResult": "N/A",
    "avsTelephoneResult": "N/A"
  }
}

Challenge 3DS Requerido (200)

Cuando el banco emisor requiere la verificación del tarjetahabiente, la respuesta devuelve status: "CHALLENGE" con un redirectAcsUrl:

{
  "status": 200,
  "data": {
    "paymentId": "dce568c6-98ec-456c-bb33-4a6809c4fff8",
    "externalPaymentId": "order-12345",
    "redirectAcsUrl": "https://{FQDN}/secure-code/start-challenge?token=dce568c6-...",
    "amount": 99.99,
    "approved": false,
    "message": "Payment awaiting 3DS challenge verification",
    "status": "CHALLENGE",
    "captured": false,
    "voided": false,
    "responseCode": "00",
    "cvcResult": "N/A",
    "avsResult": "N/A"
  }
}

Cuando reciba CHALLENGE, redirija al tarjetahabiente a redirectAcsUrl. Vea Manejo de 3D Secure para el flujo completo.

Rechazado (400)

{
  "status": 400,
  "data": {
    "paymentId": "abc12345-...",
    "externalPaymentId": "order-12345",
    "amount": 99.99,
    "approved": false,
    "message": "Not sufficient funds",
    "status": "DECLINED",
    "responseCode": "PAY_084"
  }
}

Campos de la Respuesta

Uso de un Token Recurrente

Si la tarjeta se tokenizó con storeLaterUse: true, puede reutilizar el token para cargos futuros incluyendo el previousPaymentId:

{
  "sender": {
    "paymentMethod": {
      "type": "CARD",
      "cardTokenId": "ab5fc589-8b48-4531-94c0-68b0629c13fe",
      "previousPaymentId": "dce568c6-98ec-456c-bb33-4a6809c4fff8"
    }
  }
}

Qué Sigue

• ¿Autorizado? → Capture el pago cuando esté listo para liquidar
• ¿Necesita cancelar? → Anule (void) la autorización antes de la captura
• ¿Challenge 3DS? → Maneje el flujo de redirección de 3D Secure
• ¿Verificar la validación? → Resultados de AVS / CVC