Pasos de integración
Para usar el Mobile SDK iOS o Android con el QNB ALAHLI, siga estas instrucciones.
Paso 1: Descargue el SDK y la documentación
El Mobile SDK iOS y Android y la documentación relacionada se pueden descargar desde Merchant Administration (MA):
- Inicie sesión en MA y, luego, seleccione Admin > Descarga de software.
- Seleccione el vínculo correspondiente y siga las instrucciones para descargar el archivo requerido.
Aparece la página Administración - Descargas de software y documentación. Contiene el Mobile SDK y las guías de integración de Mobile SDK.
Compilaciones de dispositivos y simuladores para iOS
El Mobile SDK para iOS se lanza con dos compilaciones:
- Versión del dispositivo: la versión del dispositivo tiene habilitado el código intermedio, lo que permite que la aplicación ocupe menos espacio en el dispositivo del usuario. Sin embargo, la versión no es compatible con la arquitectura x86_64. Los desarrolladores tienden a preferir la versión del SDK para dispositivos como versión de lanzamiento.
- Versión del simulador: Para utilizar un simulador, necesita la arquitectura x86_64. Esto significa que el código intermedio está deshabilitado, lo que genera una mayor huella de la aplicación. Los desarrolladores tienden a preferir la versión del simulador durante el desarrollo, donde el consumo de recursos no es una preocupación real.
Para obtener más información, consulte la documentación de Apple:
Paso 2: Instale e inicialice el SDK
Esta sección incluye instrucciones sobre cómo instalar e inicializar el SDK.
iOS
Para instalar el SDK en su proyecto Xcode:
- Arrastre la carpeta
Gateway-SDK.xcframeworka su proyecto de Xcode. - Agregue la biblioteca a "Frameworks, Libraries and Embedded Content" de su objetivo.
- Ejecute la operación import Gateway del marco de trabajo cuando sea necesario.
- Si es necesario, configure Gateway-SDK.xcframework como un paquete Swift local con la opción .binaryTarget.
- Asegúrese de incluir uSDK.xcframework en su proyecto. El SDK depende del uSDK.xcframework incluido en el archivo ZIP.
// AppDelegate.swift import Gateway
Debe inicializar el SDK antes de usarlo. Se recomienda realizar esta operación en la clase AppDelegate.
// AppDelegate.swift
GatewaySDK.shared.initialize(
merchantId: "MERCHANT_ID",
merchantName: "Merchant Name",
merchantUrl: "https://merchant-url.com",
region: "Your gateway region"
Android
El SDK está empaquetado como un depósito maven.
Para instalar el SDK en su proyecto:
- Descomprima el 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.gradlede su proyecto. - En el archivo
build.gradledel módulo de su aplicación, incluya el Mobile SDK como dependencia.
// 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>.
Debe inicializar el SDK antes de usarlo. Se recomienda realizar esta operación en su clase de Application personalizada en la función 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",
region: "Your gateway region",
callback
)
}
Recomendaciones de seguridad para la integración de nuestro SDK
- Limitación de intentos de actualización de la sesión: implemente la limitación de intentos de actualización de la sesión para evitar ataques de fuerza bruta y acceso no autorizado.
- Medidas de seguridad adicionales:
- Integración de CAPTCHA: utilice CAPTCHA para validar la autenticidad del usuario y evitar ataques automatizados.
- Autenticación biométrica: emplee reconocimiento facial o de huellas dactilares para una autenticación sólida del usuario y para frustrar intentos de acceso no autorizados.
- Protección DDoS: implemente mecanismos sólidos de protección DDoS para resguardarse de ataques volumétricos y garantizar la disponibilidad continua del servicio.
- Detección de bots: incorpore técnicas avanzadas para identificar y mitigar actividades de bots maliciosos que exploten las vulnerabilidades de las aplicaciones.
- Limitación de tasa: aplique políticas estrictas de limitación de tasas para regular las solicitudes de clientes o direcciones IP, garantizando una asignación justa de recursos y mitigando el abuso.
- Fijación de SSL con nuestro propio servidor: incluya fijación de SSL para garantizar una comunicación segura, evitando ataques de intermediarios y accesos no autorizados al servidor.
Paso 3: Crear y actualizar una sesión
El flujo de Mobile SDK se basa en el concepto de 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 Conceptos básicos de las sesiones.
Cree y actualice 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, envíe una solicitud de API de
CREATE SESSION. Para los campos de solicitud, consulte la tabla de campos de la solicitudCREATE SESSION. - Para actualizar la sesión, envíe la solicitud
UPDATE SESSIONcon los campos obligatorios. Para los campos de la solicitud, consulte la tabla de campos obligatorios de la solicitudUPDATE SESSION.
Tabla: Campos de la solicitud CREATE SESSION
| Parámetro de solicitud | Descripción | Ejemplo |
|---|---|---|
| authenticationLimit | Número de operaciones que se pueden enviar al motor de pagos utilizando el ID de esta sesión como contraseña. El ID de sesión se utiliza como contraseña en solicitudes autenticadas por sesión relacionadas con la autenticación 3D Secure (3DS). | 25 |
Tabla: Campos obligatorios de la solicitud UPDATE SESSION
| Parámetro de solicitud | Descripción | Ejemplo |
|---|---|---|
| order.id | Identificador único para este pedido. | your-order-id |
| order.amount | Importe total del pedido. | 1.23 |
| order.currency | Moneda del pedido. | AUD |
| authentication.acceptVersions | Versión de 3DS que acepta para este pago. Si no especifica una versión, se acepta 3DS2. El motor de pagos utiliza 3DS2, si el emisor y la tarjeta lo admiten. Si 3DS2 no está disponible, la autenticación no continúa. | 3DS2 |
| authentication.channel | Canal en el que se inicia la solicitud de autenticación. | PAYER_APP |
| authentication.purpose | Finalidad de la autenticación. | PAYMENT_TRANSACTION |
Una vez creada una sesión en su servidor:
- Devuelva la información de la sesión a la aplicación móvil para usarla en operaciones posteriores.
- Cree una instancia del objeto
Session.
let sessionId = "session-id" let apiVersion = "61" // api version used to create the session let orderId = "order-id" // must match order id used on your server let amount = "1.23" let currency = "USD"
// example
val session = Session(
id = "session-id",
amount = "1.23",
currency = "USD",
apiVersion = "61", // api version used to create the session
orderId = "order-id" // must match order id used on your server
)
apiVersion debe ser la misma durante todo el ciclo de vida de la transacción, desde la creación de la sesión hasta el pago final.Paso 4: Recopilar información de pago
Puede recopilar la información de pago del pagador de varias maneras:
- Si su nivel de cumplimiento de PCI lo permite, puede recopilar los detalles de la tarjeta manualmente y agregarlos a la sesión. Para obtener más información, consulte Detalles de la tarjeta manualmente.
- Si su nivel de cumplimiento de PCI no le permite manejar datos confidenciales, puede utilizar el método de pago Apple Pay o Google Pay para obtener un token de pago que represente una tarjeta que el pagador ha agregado a su billetera Apple o Google Pay. Luego, agregue el token a la sesión. Para obtener más información, consulte Apple Pay y Google Pay.
La función updateSession() se utiliza en el Mobile SDK para agregar la información de pago, los detalles de la tarjeta o el token a la sesión. La información de pago debe estar presente en la sesión antes de continuar con la autenticación opcional del pagador y la transacción de pago real.
updateSession() es la forma más sencilla de cargar los detalles de pago en la sesión sin afectar el alcance de su PCI. Sin embargo, si el alcance de la PCI no es un problema, también puede cargar los detalles de otras maneras, como a través de la solicitud UPDATE SESSION desde su servidor.Detalles de la tarjeta manualmente
Recopile los detalles de la tarjeta del pagador en la pantalla de la aplicación y pase la información directamente al motor de pagos utilizando el ID de sesión que se devolvió en la respuesta de CREATE SESSION anterior.
// 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()
request.sourceOfFunds.provided.card.nameOnCard.value = nameOnCard
request.sourceOfFunds.provided.card.number.value = cardNumber
request.sourceOfFunds.provided.card.securityCode.value = cvv
request.sourceOfFunds.provided.card.expiry.month.value = cardExpiryMM
request.sourceOfFunds.provided.card.expiry.year.value = cardExpiryYY
GatewayAPI.shared.updateSession(sessionId, apiVersion: apiVersion, payload: request) { (response) in
// handle result
}
// 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);
Después de actualizar la sesión con los detalles de la tarjeta, puede tokenizar los detalles de la tarjeta para permitirle almacenar el token para uso futuro cuando el pagador regrese o cuando necesite realizar transacciones iniciadas por el negocio. Por ejemplo, debido a pagos recurrentes. Para tokenizar los detalles de la tarjeta, utilice la operación CREATE Or UPDATE TOKEN en su servidor con el ID de sesión válido. Para obtener más información, consulte Tokenización.
Paso 5: Crear la transacción de pago
Cuando el pagador se haya autenticado y la sesión contenga los detalles de pago, como los detalles de la tarjeta o un token, envíe la solicitud de transacción de pago PAY o AUTHORIZE desde su servidor, incluido el ID de sesión en la solicitud. Para obtener más información, consulte Realizar una solicitud de API de servidor.