- Pautas de integración
- SDK de Mastercard Gateway para Android
SDK de Mastercard Gateway para Android
Instalación
Este SDK está empaquetado como un depósito maven. Debe descomprimirse en una ubicación del proyecto y agregarse como depósito en el archivo build.gradle del proyecto.
- Desde su portal de Merchant Administration, descargue la última versión del SDK en un formato de archivo ZIP.
- Descomprima este archivo en el directorio raíz de su proyecto de Android. (Por ejemplo, ~/my-android- project/gateway- repo)
- Agregue una referencia a este depósito local en el archivo
build.gradledel proyecto. - En el archivo
build.gradlede los módulos de la aplicación, incluya el SDK del motor de pagos como una dependencia.
Para obtener más información sobre cómo descargar el SDK, consulte Integración de Mobile SDK.
// build.gradle
allprojects {
repositories {
mavenCentral()
google()
// Gateway Android SDK repo
maven {
url "$rootDir/gateway-repo"
}
}
}
// app/build.gradle implementation 'com.mastercard.gateway:Mobile_SDK_Android:x.x.x'
La carpeta Mobile_SDK_Android contiene un archivo maven-metadata.xml que tiene información para crear la referencia de implementación para la biblioteca. El formato gradle de implementación es implementation <groupId>:<artifactId>:<version>
Inicializar el SDK
Inicialice el SDK de Android antes de usarlo. Se recomienda realizar esta operación en su clase de aplicación personalizada en el método onCreate() .
// CustomApplication.kt
override fun onCreate()
{
super.onCreate()
// init Gateway SDK
GatewaySDK.initialize
(
this,
"YOUR_MERCHANT_ID",
"Your Merchant Name",
"https://your-merchant-url.com",
"Your gateway region",
callback
)
}
Resumen de la sesión
El flujo del SDK del motor de pagos se basa en el concepto de una sesión. Una sesión es un contenedor temporal para cualquier campo de solicitud y valor de operaciones que hagan referencia a una sesión. Para obtener más información, consulte la documentación de Sesión de pago.
Beneficios clave
- Reduce los costos de cumplimiento de PCI, ya que usted no administra ni almacena ningún detalle de pago.
- Facilita la integración, ya que no necesita administrar directamente los valores para los campos de solicitud almacenados en una sesión.
- Reduce el fraude interno, ya que su personal tiene acceso limitado a los detalles del pagador.
- Le permite actualizar los campos de solicitud y los valores almacenados para una sesión. Esto es útil cuando una tarjeta de crédito vence o cambian otros detalles del pagador.
- Le permite recuperar los campos de solicitud y los valores contenidos en una sesión al especificar el identificador de sesión.
Crear una sesión
Cree una sesión con el motor de pagos para iniciar el flujo de pago en un dispositivo móvil.
- Para preparar esta sesión para transacciones móviles, se deben realizar dos llamadas a API.
- Estas llamadas están protegidas por una contraseña de API y, por lo tanto, deben realizarse desde su servidor privado.
| Parámetro de solicitud | Ejemplo |
|---|---|
| authenticationLimit | 25 |
Actualizar la sesión
| Parámetro de solicitud | Existencia | Ejemplo |
|---|---|---|
| order.id | Obligatorio | your-order-id |
| order.amount | Obligatorio | 1.23 |
| order.currency | Obligatorio | AUD |
| authentication.acceptVersions | Obligatorio | 3DS2 |
| authentication.channel | Obligatorio | PAYER_APP |
| authentication.purpose | Obligatorio | PAYMENT_TRANSACTION |
Cuando se haya creado una sesión en su servidor, deberá
- devolver la información de la sesión a la aplicación móvil, y
- crear una instancia del objeto
Session.
// example
val session = Session(
id = "your-session-id",
amount = "1.23",
currency = "USD",
apiVersion = "61", // api version used to create the session
orderId = "your-order-id" // must match order id used on your server
)
Recopilación de información de la tarjeta
El método SDK para updateSession es de uso opcional, pero se recomienda para ayudar con el alcance de PCI del servidor del negocio. Sin embargo, la información de la tarjeta y el token se puede cargar por medio de un diseño de API diferente y debe estar presente en la sesión antes de que se realice la llamada en el SDK para autenticar al pagador.
Ingreso manual de tarjeta
Pase la información directamente al motor de pagos utilizando un ID de sesión existente.
// The GatewayMap object provides support for building a nested map structure using key-based dot(.) notation.
// Each parameter is similarly defined in your online integration guide.
val request = GatewayMap()
.set("sourceOfFunds.provided.card.nameOnCard", nameOnCard)
.set("sourceOfFunds.provided.card.number", cardNumber)
.set("sourceOfFunds.provided.card.securityCode", cardCvv)
.set("sourceOfFunds.provided.card.expiry.month", cardExpiryMM)
.set("sourceOfFunds.provided.card.expiry.year", cardExpiryYY);
GatewayAPI.updateSession(session, request, callback);
Tokenización
El SDK brinda soporte para actualizar una sesión con información de la tarjeta, puede usar esa sesión para realizar varias operaciones con el motor de pagos. La tokenización proporciona una forma de retener una tarjeta en el archivo y se puede realizar en el servidor con una sesión válida.
Siga estos pasos para usar el Mobile SDK para facilitar la creación de un token de tarjeta.
- Cree y actualice una sesión usando el SDK.
- Actualice la sesión con los detalles de la tarjeta de los clientes a través del método SDK.
GatewayAPIupdateSessiondel motor de pagos. - Devuelva el ID de sesión al servidor y llame al método Create or Update Token en el motor de pagos con sus credenciales de API privadas.
- Se devuelve un ID de token y se puede retener en los servidores como una tarjeta en archivo.
Para obtener más información sobre la tokenización, consulte la documentación de Create or Update Token.
Google Pay
El SDK del motor de pagos incluye una utilidad auxiliar, denominada GooglePayHandler, para recopilar información de tarjetas de una billetera de Google Pay.
Configuración
Para habilitar la compatibilidad con Google Pay en su aplicación, consulte la documentación de Google Pay.
Estas instrucciones deben guiarlo sobre cómo:
- configurar la API de Google Pay;
- solicitar información de pago de la billetera de Google;
- Incorporar el botón en el diseño; y
- gestionar la respuesta de la API de Google Pay.
Puesto que la integración de Google Pay es opcional con el SDK del motor de pagos, debe proporcionar la dependencia de servicios de pago adecuada.
implementation 'com.google.android.gms:play-services-wallet:X.X.X'
El motor de pagos está integrado con Google Pay como un tipo de PAYMENT_GATEWAY.
Para solicitar información de tarjeta cifrada de Google Pay
- utilice el nombre válido
mpgsen la solicitud; y - reemplace
YOUR_MERCHANT_IDpor el ID de negocio que utilice en el motor de pagos.
val tokenizationSpecification = JSONObject()
.put("type", "PAYMENT_GATEWAY")
.put("parameters", JSONObject()
.put("gateway", "mpgs")
.put("gatewayMerchantId", "YOUR_MERCHANT_ID"))
Solicitar información de la billetera
Utilice el GooglePayHandler para iniciar la billetera de Google Pay con su cliente de pagos construido y solicitar los datos.
// YourActivity.kt
fun googlePayButtonClicked()
{ try {
val request = PaymentDataRequest.fromJson(paymentDataRequest.toString())
// use the Gateway convenience handler for launching the Google Pay flow
GooglePayHandler.requestData(this, paymentsClient, request)
} catch (e: JSONException) {
Toast.makeText(this, "Could not request payment data", Toast.LENGTH_SHORT).show()
}
}
Administrar la respuesta de la billetera
El SDK del motor de pagos ofrece un controlador de ciclo de vida de Google Pay para mayor comodidad. Puede implementar la devolución de llamada proporcionada de Google Pay y usar el controlador de resultados dentro de su actividad.
Esto evita la necesidad de administrar manualmente los resultados de la actividad de Google Pay y delega los pasos de transacción importantes a los métodos de devolución de llamada.
// YourActivity.kt
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?)
{
// handle the Google Pay response
if (GooglePayHandler.handleActivityResult(requestCode, resultCode, data, callback)) {
return
}
super.onActivityResult(requestCode, resultCode, data)
}
val googlePayCallback = object : GooglePayCallback {
override fun onReceivedPaymentData(paymentData: JSONObject) {
try {
val description = paymentData.getJSONObject("paymentMethodData")
.getString("description")
Log.d(MyGooglePayCallback::class.java.simpleName,"ReceivedPaymentData: $description")
} catch (e: Exception) {
// handle exception
}
handleGooglePayData(paymentData)
}
override fun onGooglePayCancelled() {
// handle cancelled
}
override fun onGooglePayError(status: Status) {
// handle error
}
}
Actualizar una sesión con el token de pago
Actualice una sesión con el motor de pagos una vez que reciba los datos de pago de Google Pay.
fun handleGooglePayData(paymentData: JSONObject) {
val token = paymentData.getJSONObject("paymentMethodData")
.getJSONObject("tokenizationData")
.getString("token")
val request = GatewayMap()
.set("sourceOfFunds.provided.card.devicePayment.paymentToken", token)
GatewayAPI.updateSession(session, request, callback)
}
Autenticación del pagador
3D Secure
La autenticación 3-D Secure o 3DS está diseñada para proteger las compras en línea contra fraudes de tarjeta de crédito, al permitirle autenticar al pagador antes de enviar una transacción Authorization o Pay.
El EMV 3DS, también conocido como 3DS2 en el motor de pagos, es la nueva versión diseñada para mejorar la seguridad en las compras en línea, mientras que proporciona procesos de pago sin problemas a los pagadores que son considerados de bajo riesgo por el servidor de control de acceso (ACS).
El ACS puede determinar el riesgo utilizando la información proporcionada por el negocio, huellas digitales del dispositivo o interacciones anteriores con el pagador. El servidor ACS plantea un desafío al pagador (por ejemplo, el ingreso de un PIN) solo cuando se requiere una verificación adicional para autenticar al pagador, lo que proporciona un aumento de las tasas de conversión.
Entre los esquemas de autenticación compatibles se encuentran Mastercard Identity Check, Visa Secure y American Express SafeKey.
La autenticación dentro de los Mobile SDK está limitada solo a 3DS2. Si 3DS2 no está disponible, la autenticación no continuará. Sin embargo, puede continuar igualmente con el pago si el motor de pagos le recomienda que lo haga.
Para obtener más información sobre Autenticación 3D Secure, consulte la documentación de Autenticación 3-D Secure.
Detalles de autenticación
El Mobile SDK incorporado recopila métricas del dispositivo para enviarlas al motor de pagos junto con la información de la transacción cuando se realiza la autenticación de Mobile SDK, es decir, verifica la identidad del titular de una tarjeta en una aplicación móvil.
Facilite tanta información como sea posible sobre el pagador y la transacción para aumentar la probabilidad de que la autenticación sea correcta.
Esta información adicional se puede agregar a la session con una solicitud de Update Session.
| Parámetro | Existencia | Descripción |
|---|---|---|
| order.merchantCategoryCode | Opcional | Igual que el código en su perfil de negocio |
| Grupo de parámetros de billing.address | Opcional | Se recomienda encarecidamente que incluya esto en su solicitud siempre que sea posible. |
| Grupo de parámetros de shipping.address | Opcional | Se recomienda encarecidamente que incluya esto en su solicitud siempre que sea posible. |
| Grupo de parámetros de customer | Opcional | Se recomienda encarecidamente que incluya esto en su solicitud siempre que sea posible. |
device tal como se ve en la documentación solo es relevante para pagos mediante explorador. No debe usarse para autenticaciones de pago basadas en dispositivos móviles.Estas métricas ayudan al sistema a determinar cómo se debe autenticar al titular de la tarjeta o si es necesario hacerlo. Durante la autenticación, el usuario puede encontrarse con uno de dos flujos de autenticación:
- Fluido: el ACS ha recopilado suficiente información sobre el titular de la tarjeta para autenticarlo. No se necesita ninguna otra acción por parte del usuario.
- Desafío: el ACS requiere que el titular de la tarjeta complete un paso de autenticación adicional, que consiste en ingresar una contraseña de un solo uso, iniciar sesión en su banco emisor, etc. El Mobile SDK incorporado gestiona la visualización de una interfaz de dispositivo nativa para este desafío. La interfaz de usuario para estas pantallas se puede personalizar pasando parámetros
UICustomizationen el SDK del motor de pagos durante la inicialización.
Para obtener más información, consulte la documentación de Authenticate Payer.
authentication.PSD2.exemption actualmente no es compatible con el SDK. Realizar una autenticación
La autenticación del pagador se considera una transacción en sí misma en el motor de pagos y, por lo tanto, necesita un ID de transacción único.
Si está cobrando el pago de un pedido:
- Correlacione un pago y una transacción de autenticación utilizando el mismo ID de pedido para cada transacción.
- Cada transacción se muestra como una transacción distinta en el portal web del motor de pagos, como por ejemplo un UUID.
AuthenticationHandler.authenticate(activityContext, session, "your-auth- transaction-id", callback)
your-auth-transaction-id es un identificador único para esta transacción que la distingue de cualquier otra transacción del pedido. Esto es necesario ya que el motor de pagos usará your-auth-transaction-id para buscar los resultados de autenticación que almacenó cuando se solicitó al SDK que autenticara al pagador. Luego, el motor de pagos pasa la información necesaria al adquirente para la solicitud de pago.Interpretar la respuesta
El método authenticate devolverá un objeto AuthenticationResponse que contiene:
- información importante sobre el resultado; y
- las acciones realizadas durante la operación.
El campo más importante para el consumo es response.recommendation. Puede contener el valor PROCEED o DO_NOT_PROCEED.
- PROCEED: indica "OK para continuar con un pago o autorización".
- DO_NOT_PROCEED: indica que algo falló durante la operación de autenticación. El objeto
AuthenticationErrorse puede utilizar para determinar más.
Desde la API del motor de pagos versión 70 y superior, puede obtener los siguientes errores:
AuthenticationError.recommendation_ResubmitWithAlternativePaymentDetails: indica que debe solicitar al pagador detalles de pago alternativos. Por ejemplo, una nueva tarjeta u otro método de pago, y vuelva a enviar la solicitud con los nuevos detalles.AuthenticationError.recommendation_AbandonOrder: indica que el proveedor de servicios de pago, el esquema o el emisor le solicitan que abandone el pedido.AuthenticationError.recommendation_DoNotProceed: indica que el motor de pagos falla en la solicitud, pero no hay forma de que esta transacción se realice correctamente.
Para obtener más información, consulte las guías de integración.
AuthenticationHandler.authenticate(activityContext, session, "your-auth-transaction-id") { response ->
when(response.recommendation) {
AuthenticationRecommendation.PROCEED -> {
// continue to payment/authorization
}
AuthenticationRecommendation.DO_NOT_PROCEED -> {
if (response.error !=null) {
if (response.error is AuthenticationError.RecommendationResubmitWithAlternativePaymentDetails) {
// "Authentication not successful, re-enter card details
}
} else {
// "Authentication not successful"
}
}
}
}
Si la autenticación falla, puede examinar el response.error para obtener más información sobre la causa.