Pagos con tarjeta (checkout alojado)

Los pagos con tarjeta pasan siempre por la página de pago alojada de Cashela (checkout). Tu cliente introduce la tarjeta en una página de Cashela, así que los datos de la tarjeta nunca tocan tus sistemas y no tienes que gestionar el alcance PCI por ellos.

Elegir una opción de tarjeta

1. Llama a Obtener métodos de pago para el país y el importe.
2. Busca el tipo de pago CREDIT_CARD. Sus opciones son por marca de tarjeta, por ejemplo international-credit-debit-card-visa, international-credit-debit-card-mastercard, international-credit-debit-card-amex o international-credit-debit-card-discover. Los códigos y marcas disponibles dependen de tu cuenta y del país: usa los que devuelva el catálogo.
3. Deja que tu cliente elija la marca con la que va a pagar.

La opción es por marca

La página de pago solo acepta la marca de la opción que elegiste. Una Mastercard no puede pagar un depósito creado con una opción Visa. Si tu cliente cambia de opinión, crea un depósito nuevo con la opción correcta.

Dos tipos de opción de tarjeta

	Cobro en USD	Cobro en moneda local
Cómo reconocerla	La opción trae charge_breakdown (siempre en USD) y local_estimate	Los importes de la opción están en la moneda del país (payment_info)
Qué ve tu cliente	El importe en USD y una estimación en moneda local	El importe y la comisión en moneda local
Qué se cobra a la tarjeta	USD. El emisor de la tarjeta fija la tasa de cambio final en el extracto de tu cliente.	Moneda local

En las opciones que cobran en USD:

• El importe en moneda local (local_estimate, y details.invoice_* en el depósito) es solo informativo.
• Lo que se cobra de verdad está en charge_breakdown antes del depósito, y en details.charged_amount / details.charged_currency en el depósito. La notificación lleva la misma cifra en USD en amount / currency (por ejemplo 5.00 USD, no su equivalente en pesos).
• El diferencial cambiario (fx_spread) se cobra solo cuando hay conversión de moneda. Un cobro en USD acreditado en un saldo en USD no lleva diferencial (fx_spread_amount: 0 en la notificación).

Flujo

1. Crea el depósito con payment_type: "CREDIT_CARD", el payment_method de la marca, los datos de tu cliente y su client_ip real. En tarjetas, la ubicación de la IP debe coincidir con country.
2. Redirige a tu cliente a data.details.paying.metadata.redirect_url. En producción tiene la forma https://www.cashela.com/partner-checkout/{token}. Ábrelo como página completa o en una pestaña nueva: nunca en un iframe (iframe: false).
3. Tu cliente paga en la página: nombre del titular, número de tarjeta, fecha de vencimiento y CVV, y marca la casilla de autorización para aceptar el cargo. La página muestra el importe que se va a cobrar.
4. La página muestra el resultado y devuelve a tu cliente a tu redirect_url (su dominio debe estar en tus URLs de retorno aprobadas).
5. Recibes la notificación firmada con el estado final y card: { "network": "visa", "last4": "4242" }.

// Extracto del depósito que devuelve POST /deposit-creation para una opción de tarjeta que cobra en USD
"details": {
  "invoice_country": "MEX",
  "invoice_currency": "MXN",
  "invoice_amount": 92.18,
  "paying": {
    "method": "Credit Card",
    "code": "international-credit-debit-card-visa",
    "metadata": {
      "iframe": false,
      "redirect_url": "https://www.cashela.com/partner-checkout/<token>",
      "validity_period": "2026-10-20T16:05:00+00:00"
    }
  },
  "charged_amount": 5,
  "charged_currency": "USD"
}

Vencimiento de la sesión y tarjetas rechazadas

• El enlace de pago es válido hasta validity_period (alrededor de una hora). Después, el depósito termina en CANCELLED y no se cobra nada. Tu notificación llega con status: "CANCELLED".
• Si una tarjeta es rechazada, la página se lo indica a tu cliente y le deja probar con otra tarjeta. El depósito sigue en PROCESSING mientras tu cliente pueda reintentar, hasta que se pague (COMPLETED) o venza la sesión (CANCELLED). El número de intentos es limitado.
• Un intento rechazado no cobra la tarjeta ni te acredita nada.

Consejo

No crees un depósito nuevo cuando tu cliente vuelve después de una tarjeta rechazada: el mismo enlace sigue sirviendo hasta que vence.

Datos de tarjeta que recibes

El depósito y la notificación solo llevan card.network (visa, mastercard, amex, discover, o null si se desconoce) y card.last4. Nunca el número completo, el CVV, la fecha de vencimiento ni un token. card es null en métodos sin tarjeta y antes del cobro.

Anulaciones y reembolsos

Los depósitos con tarjeta se pueden anular o reembolsar por API. Ver Anulaciones y reembolsos.

Pruebas

En sandbox, lleva los depósitos con tarjeta a su estado final con simulate. Antes de salir a producción, asegúrate de que tu client_ip y los datos del pagador son coherentes con el país del depósito.