Integrar para aplicaciones móviles - Tarjeta - Mercado Pago Developers
Integración para aplicaciones móviles
La integración mediante los Core Methods del SDK Nativo de Mercado Pago ofrece control total sobre la captura y el procesamiento de la información de pago, permitiendo crear y personalizar formularios según tus necesidades.
Para integrar el SDK Nativo de Mercado Pago utilizando los Core Methods, consulta las instrucciones específicas para cada tecnología:
Requisitos
Antes de comenzar la integración, asegúrate de que tu proyecto cumpla con los siguientes requisitos:
Requisito
Descripción
SDK
Versión 23 o superior
Jetpack Compose BoM
Versión 2024.12.01 o superior
Kotlin
Versión 2.0 o superior
Public Key
La Public KeyClave pública que se utiliza en el frontend para acceder a la información y cifrar datos. Puedes acceder a ella a través de Tus integraciones > Detalles de la aplicación > Producción > Credenciales de producción. está directamente vinculada a la aplicaciónEntidad registrada en Mercado Pago que actúa como identificador para gestionar tus integraciones. Para más información, accede al enlace abajo.Detalles de la aplicación que creaste, por lo tanto, cada una es única para cada integración.
Integrar SDK
El SDK nativo de Mercado Pago proporciona una solución robusta y segura para la integración de tarjetas, asegurando el total cumplimiento con las normas PCI.
Para integrar el SDK de Mercado Pago en tu proyecto Android, sigue los pasos descritos en la documentación del SDK Nativo.
Configurar campos seguros
Los campos seguros son componentes desarrollados para garantizar la privacidad y la protección de los datos sensibles introducidos por el comprador. En total conformidad con los estándares PCIConjunto de reglas de seguridad que buscan proteger los datos de las tarjetas de pago contra fraudes y filtraciones de datos., estos campos aseguran que la aplicación nunca tenga acceso directo a la información ingresada, que se transmite de forma segura solo para la creación de tokens y transacciones.
Todas las interacciones con estos campos ocurren mediante callbacks, permitiendo la captura de eventos relevantes sin exponer los datos del usuario. Los métodos descritos a continuación utilizan instancias de estos campos seguros, por lo que es esencial que estén debidamente configurados en la interfaz del checkout antes de utilizarlos.
Cada componente notifica a la aplicación integradora cuando ocurre un cambio en el valor, sin exponer los datos introducidos, e informa también el resultado de la validación del campo según las reglas de PCI y de la tarjeta.
Los datos introducidos en los campos seguros nunca están disponibles para la aplicación integradora. Se envían de forma segura solo para la creación de tokens y transacciones.
En la tabla a continuación encontrarás el detalle de los componentes disponibles. Para más información sobre la configuración, consulta la referencia correspondiente a cada uno de ellos en GitHub.
Campo seguro para ingresar el código de seguridad (CVV).
Core Methods
Los Core Methods son esenciales para construir un flujo de checkout integrado con Mercado Pago. Utilizan la información capturada por los campos seguros y permiten ejecutar las principales operaciones de pago.
Cada método debe ser utilizado según las necesidades de tu flujo de pago. Para utilizarlos, comienza creando una instancia de Core Methods en tu clase utilizando el siguiente código Kotlin: val coreMethods = MercadoPagoSDK.getInstance().coreMethods.
A continuación, consulta los diferentes métodos y conoce cómo puedes utilizarlos:
El método Obtener medios de pago devuelve la lista de medios de pago disponibles a partir del BIN de la tarjeta informada, considerando las reglas e instituciones financieras válidas para el país configurado. A través de este método podrás identificar la marca de la tarjeta, definir correctamente los siguientes pasos del checkout y validar la aceptación de la tarjeta.
kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
// Se debe usar el bin retornado del CardNumberTextFieldEvent.OnBinChanged
val result = coreMethods.getPaymentMethods(bin = bin)
when (result) {
is Result.Success -> {
// Éxito de la llamada
print("Éxito de la request: ${result.data}")
}
is Result.Error -> {
when (result.error) {
is ResultError.Request -> {
// Error de la llamada de tipo request
print("Error de request: ${result.error}")
}
is ResultError.Validation -> {
// Error de la llamada de tipo validation
print("Error de validación: ${result.error}")
}
}
}
}
}
Los parámetros están listados en la tabla a continuación.
Parámetro
Tipo
Descripción
Obligatorio
bin
String
Los primeros 8 dígitos de la tarjeta de crédito, obtenidos por el callbackonBinChange de CardNumberTextFieldEvent.
Este método te permite realizar la búsqueda de todas las opciones de cuotas disponibles para una tarjeta y un monto de transacción determinados. Considera las reglas del emisor, del método de pago y del valor de la compra, devolviendo todas las opciones válidas de cuotas, incluyendo cantidad de cuotas, intereses, valor de cada cuota, valor total, entre otros.
La llamada al método getInstallments debe hacerse para todos los tipos de tarjeta (débito y crédito) para verificar si el pago puede completarse por ese medio.
kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
// Se debe usar el bin retornado del CardNumberTextFieldEvent.OnBinChanged
val result = coreMethods.getInstallments(
bin = bin,
amount = BigDecimal("100.00")
)
when (result) {
is Result.Success -> {
// Éxito de la llamada
print("Éxito de la request: ${result.data}")
}
is Result.Error -> {
when (result.error) {
is ResultError.Request -> {
// Error de la llamada de tipo request
print("Error de request: ${result.error}")
}
is ResultError.Validation -> {
// Error de la llamada de tipo validation
print("Error de validación: ${result.error}")
}
}
}
}
}
Utiliza la información del Installment para mostrar al comprador todos los detalles del valor y del plan de cuotas de la compra, antes de finalizar el pago.
Los parámetros están listados en la tabla a continuación.
Parámetro
Tipo
Descripción
Obligatorio
bin
String
Los primeros 8 dígitos de la tarjeta de crédito, obtenidos por el callbackonBinChange de CardNumberTextFieldEvent.
En determinados medios de pago y marcas, Mercado Pago exige la identificación del emisor de la tarjeta (issuer). Este método devuelve la lista de emisores disponibles para el BIN informado, permitiendo al usuario seleccionar el emisor correcto cuando sea necesario.
kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
// Se debe usar el bin retornado del CardNumberTextFieldEvent.OnBinChanged
// Se debe usar el paymentMethodId retornado de la request de PaymentMethods
val result = coreMethods.getCardIssuers(
bin = bin,
paymentMethodId = paymentMethodId,
)
when (result) {
is Result.Success -> {
// Éxito de la llamada
print("Éxito de la request: ${result.data}")
}
is Result.Error -> {
when (result.error) {
is ResultError.Request -> {
// Error de la llamada de tipo request
print("Error de request: ${result.error}")
}
is ResultError.Validation -> {
// Error de la llamada de tipo validation
print("Error de validación: ${result.error}")
}
}
}
}
}
Los parámetros están listados en la tabla a continuación.
Parámetro
Tipo
Descripción
Obligatorio
bin
String
Los primeros 8 dígitos de la tarjeta de crédito, obtenidos por el callbackonBinChange de CardNumberTextFieldEvent.
Obligatorio
paymentMethodId
String
ID del método de pago, normalmente obtenido a partir del resultado del método PaymentMethods.
Mercado Pago exige la validación de un documento de identificación del titular de la tarjeta. Utiliza este método para recibir todos los tipos de documentos aceptados, como CPF, RG, DNI, para el país configurado en la integración.
kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
val result = coreMethods.getIdentificationTypes()
when (result) {
is Result.Success -> {
// Éxito de la llamada
print("Éxito de la request: ${result.data}")
}
is Result.Error -> {
when (result.error) {
is ResultError.Request -> {
// Error de la llamada de tipo request
print("Error de request: ${result.error}")
}
is ResultError.Validation -> {
// Error de la llamada de tipo validation
print("Error de validación: ${result.error}")
}
}
}
}
}
Este método genera un token temporal a partir de los datos de la tarjeta informada. El uso del token generado es obligatorio para realizar la transacción de pago mediante la API de Mercado Pago, ya que reemplaza los datos sensibles de la tarjeta, garantizando mayor seguridad en el proceso.
La llamada a este método utiliza una instancia de los campos seguros previamente configurados en la interfaz del checkout. Asegúrate de que estos se encuentren implementados y configurados antes de usar el método generateCardToken.
Crear un token para una nueva tarjeta
Para generar un token para una nueva tarjeta de forma segura, utiliza la clase que protege los datos ingresados y pásala al método generateCardToken. Antes de ejecutar el método, verifica que todos los campos obligatorios estén correctamente completados.
kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
val result = coreMethods.generateCardToken(
cardNumberState = cardNumberPCIFieldState,
expirationDateState = expirationDatePCIFieldState,
securityCodeState = securityCodePCIFieldState,
buyerIdentification = BuyerIdentification(
name = "APRO",
number = "12345678909",
type = "CPF"
)
)
when (result) {
is Result.Success -> {
// Éxito de la llamada
print("Éxito de la request: ${result.data}")
}
is Result.Error -> {
when (result.error) {
is ResultError.Request -> {
// Error de la llamada de tipo request
print("Error de request: ${result.error}")
}
is ResultError.Validation -> {
// Error de la llamada de tipo validation
print("Error de validación: ${result.error}")
}
}
}
}
}
Los parámetros están listados en la tabla a continuación.
En las transacciones con Mercado Pago, los datos de las tarjetas registradas por el comprador se almacenan de forma segura y no son accesibles desde tu backend. Sólo se proporciona el ID de la tarjeta a la aplicación, que deberás utilizar para generar un token temporal. Esto protege la información sensible, ya que sólo se maneja el ID, mientras que el número de tarjeta, CVV y fecha de vencimiento no se exponen y se mantienen seguros.
kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
val result = coreMethods.generateCardToken(
cardId = cardId,
expirationDateState = expirationDatePCIFieldState,
securityCodeState = securityCodePCIFieldState,
buyerIdentification = BuyerIdentification(
name = "APRO",
number = "12345678909",
type = "CPF"
)
)
when (result) {
is Result.Success -> {
// Éxito de la llamada
print("Éxito de la request: ${result.data}")
}
is Result.Error -> {
when (result.error) {
is ResultError.Request -> {
// Error de la llamada de tipo request
print("Error de request: ${result.error}")
}
is ResultError.Validation -> {
// Error de la llamada de tipo validation
print("Error de validación: ${result.error}")
}
}
}
}
}
Los parámetros están listados en la tabla a continuación.
El envío debe realizarse mediante la creación de un pago que contenga la transacción asociada.
Para ello, envía un POST con tu Access Token productivoClave privada de la aplicación creada en Mercado Pago y que se utiliza en el backend en ambientes de desarrollo y para recibir pagos reales. Puedes acceder a ella a través de Tus integraciones > Detalles de la aplicación > Producción > Credenciales de producción. y los parámetros requeridos listados abajo al endpoint /v1/paymentsAPI y ejecuta la solicitud.
Consulta en la siguiente tabla las descripciones de los parámetros que tienen alguna particularidad importante a destacar:
Atributo
Tipo
Descripción
Obligatoriedad
Authorization
Header
Hace referencia a tu clave privada, el Access Token.
Obligatorio
X-Idempotency-Key
Header
Clave de idempotencia. Esta clave garantiza que cada solicitud sea procesada solo una vez, evitando duplicidades. Usa un valor exclusivo en el header de la solicitud, como un UUID V4 o una cadena aleatoria.
Obligatorio
token
Body.String
Identificador del token de la tarjeta. El token se genera a partir de los datos de la propia tarjeta, proporcionando mayor seguridad en el proceso de pago. Tras ser utilizado en una compra, el token se descarta, exigiendo la creación de un nuevo token para cada transacción.
Obligatorio
transaction_amount
Body.String
Costo del producto. Para Chile, debe ser un número entero.
Obligatorio
installments
Body.String
Número de cuotas seleccionadas.
Obligatorio
payment_method_id
Body.String
Indica el identificador del medio de pago seleccionado para realizar el pago. Obtén todos los medios de pago disponibles enviando un GET al endpoint /v1/payment_methods de la API.
Obligatorio
payer.email
Body.String
Correo electrónico asociado al pagador.
Obligatorio
Para conocer en detalle todos los parámetros enviados en esta solicitud, consulta la Referencia de API.
Ejemplos y referencias
Para profundizar en la implementación y uso del SDK, revisa el repositorio en GitHub.
El repositorio incluye un módulo de ejemplo completo, que demuestra la integración de campos seguros y los Core Methods, además de presentar un flujo de checkout integrado y seguro.