Personalización de comportamiento del Card Payment
El Mercado Pago SDK Checkout ofrece recursos adicionales para la integración móvil del Card Payment Brick para pagos con tarjeta en aplicaciones iOS y Android. En esta sección, verás cómo tokenizar una tarjeta sin realizar un cobro, gestionar la cancelación por parte del usuario y restringir los medios de pago aceptados. Consulta a continuación cómo configurar estos recursos.
Si tu operación no acepta determinados tipos de tarjeta o marcas, o trabaja con un rango específico de cuotas, es posible aplicar estas reglas directamente en el checkout a través del método setPaymentMethodConfiguration del Builder del SDK.
La validación ocurre en el client-side, antes de la tokenización: las tarjetas fuera de la regla son rechazadas en el propio formulario, sin que se genere ningún token, y solo se muestran al comprador las cuotas dentro del rango configurado. La configuración se realiza por exclusión, es decir, informas lo que no aceptas.
kotlinMercadoPagoCheckout.Builder( context = this, checkoutType = MPCheckoutType.CardTransaction( order = MPOrder( orderId = "id-de-la-orden", clientToken = "client-token-de-la-orden" ) ) ).setPaymentMethodConfiguration( listOf( MPPaymentMethodConfig.Card( excludedPaymentTypes = listOf(MPCardType.DEBIT, MPCardType.PREPAID), excludedPaymentMethods = listOf(MPCardBrand.AMEX), installment = MPInstallment(minInstallments = 1, maxInstallments = 6) ) ) ).build()
| Parámetro | Tipo | Descripción |
excludedPaymentTypes | MPCardType | Tipos de tarjeta excluidos, pudiendo ser: DEBIT, PREPAID o CREDIT. |
excludedPaymentMethods | MPCardBrand | Marcas excluidas, como MPCardBrand.Visa, MPCardBrand.Mastercard o MPCardBrand.AMEX. Usa MPCardBrand.Custom(...) para marcas fuera de la lista predeterminada. |
installment | MPInstallment | Mínimo y máximo de cuotas aceptadas. |
En aplicaciones de suscripción, delivery o servicios recurrentes, es común capturar los datos de la tarjeta en un momento y efectuar el cobro en otro. Para esos casos, el SDK ofrece un flujo que muestra el formulario de tarjeta, valida los datos completados y genera el token sin crear una order ni mover dinero.
Al finalizar, el SDK devuelve un token de uso único junto con paymentMethodId, paymentTypeId e issuerId. Para ello, sigue los pasos a continuación de acuerdo con el sistema operativo elegido.
CardSave no asocia la tarjeta a un cliente ni realiza un cobro. Para almacenar la tarjeta, envía el token a tu backend siguiendo el flujo de Guardar tarjetas.Para aplicaciones Android, el flujo responsable de esa tokenización es el CardSave, definido en el checkoutType al construir el checkout.
kotlinval checkout = MercadoPagoCheckout.Builder( context = this, checkoutType = MPCheckoutType.CardSave ).build() checkout.show { result -> when (result) { is MercadoPagoCheckoutResult.Success -> { val data = result.paymentData // MPPaymentData.CardSave // Envía data.token a tu backend para continuar el flujo de almacenamiento } is MercadoPagoCheckoutResult.Error -> { // Muestra un mensaje de error u ofrece retry } is MercadoPagoCheckoutResult.UserCancelled -> { // Vuelve al carrito o al paso anterior } } }
En caso de éxito, el SDK devolverá en MPPaymentData.CardSave la siguiente información:
| Parámetro | Tipo | Descripción | Obligatoriedad |
token | String | Token de pago generado para la transacción. | Obligatorio |
paymentMethodId | String | Identificador del medio de pago seleccionado. | Obligatorio |
paymentTypeId | String | Identificador del tipo de pago seleccionado. | Obligatorio |
payer | Payer? | Información del pagador (documentType y documentNumber). | Opcional |
issuerId | String? | Identificador del emisor de la tarjeta. | Opcional |
El comprador puede abandonar el checkout antes de concluir la operación, ya sea cerrando la pantalla, volviendo a la navegación anterior o interrumpiendo el completado del formulario. En esos casos, el SDK devuelve un resultado específico de cancelación (MercadoPagoCheckoutResult.UserCancelled) que contiene el estado de cada campo en el momento en que se cerró el flujo.
Utiliza esa información para definir el comportamiento de la aplicación después del abandono, como retomar el completado desde el punto en que el comprador se detuvo o identificar en qué etapa del formulario ocurrió el abandono. Consulta a continuación los datos devueltos en cada sistema operativo.
En Android, los datos de la cancelación están disponibles en la propiedad cancelledData, siendo el tipo concreto definido por el checkoutType configurado en el Builder.
kotlincheckout.show { result -> when (result) { is MercadoPagoCheckoutResult.UserCancelled -> { // Recorre los campos para saber qué se había completado result.cancelledData.fields.forEach { fieldState -> when (fieldState.state) { is State.Valid -> { /* Campo válido: reutilízalo en el próximo intento */ } is State.Empty -> { /* Campo no completado */ } is State.Incomplete -> { /* Campo completado parcialmente */ } is State.Invalid -> { /* Campo con valor inválido */ } is State.CardBrandNotAccepted -> { /* Marca no aceptada */ } is State.CardTypeNotAccepted -> { /* Tipo de tarjeta no aceptado */ } } } } is MercadoPagoCheckoutResult.Success -> { /* Gestiona el éxito */ } is MercadoPagoCheckoutResult.Error -> { /* Gestiona el error */ } } }
El objeto recibido en cancelledData es un MPUserCancelledContext y posee las siguientes propiedades.
| Propiedad | Tipo | Descripción |
fields | List<MPCancelledFieldState> | Estado de cada campo del formulario en el momento de la cancelación. |
screens | List<Screen> | Pantallas visitadas por el comprador antes de cancelar, en el orden de acceso. Disponible solo en el flujo CardTransaction. Valores posibles: CARD_FORM e INSTALLMENTS. |
Cada ítem de fields es un MPCancelledFieldState, compuesto por:
| Propiedad | Tipo | Descripción |
field | Field | Campo del formulario, pudiendo ser: CARD_NUMBER, CARD_HOLDER, EXPIRATION_DATE, SECURITY_CODE y DOCUMENT. |
state | State | Estado del campo, pudiendo ser: Valid, Empty, Incomplete, Invalid, CardBrandNotAccepted(brand) y CardTypeNotAccepted(cardType). |