- Pautas de integración
- SDK de QNB ALAHLI para iOS
SDK de QNB ALAHLI para iOS
Compatibilidad
El SDK para el motor de pagos requiere iOS 11+ cómo mínimo y es compatible con los proyectos de Swift 5.
Instalación
Siga estos pasos para agregar el SDK para el motor de pagos a su proyecto de Xcode:
- Desde su portal de Merchant Administration, descargue la última versión del SDK en un formato de archivo ZIP.
- 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 Gatewaydel marco de trabajo cuando sea necesario. - También puede definir el
Gateway-SDK.xcframeworkcomo un paquete swift local con la opción.binaryTarget. - El SDK depende del
uSDK.xcframeworkincluido en el archivo zip. Asegúrese de incluir esto en su proyecto.
Para obtener más información sobre cómo descargar el SDK, consulte Integración de Mobile SDK.
// AppDelegate.swift import Gateway
Inicializar el SDK
El SDK de iOS debe inicializarse antes de usarlo. Se recomienda realizar esta operación en la clase AppDelegate.
// AppDelegate.swift
GatewaySDK.shared.initialize(
merchantId: "YOUR_MERCHANT_ID",
merchantName: "Your Merchant Name",
merchantUrl: "https://your-merchant-url.com",
region: "Your gateway region"
)
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 |
Una vez que se crea una sesión en el servidor, se debe devolver la información de la sesión para usarla en operaciones posteriores.
let sessionId = "your-session-id" let apiVersion = "61" // api version used to create the session let orderId = "your-order-id" // must match order id used on your server let amount = "1.23" let currency = "USD"
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 a través 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 una 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()
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
}
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.
Apple Pay
Su aplicación puede usar Apple Pay para recopilar detalles de la tarjeta como alternativa a la recopilación de detalles de la tarjeta de pago mediante campos.
Configuración
Para aceptar pagos con Apple Pay, primero debe configurar su aplicación para Apple Pay. Para obtener más información, consulte Configuring your Environment (Configuración del entorno) en la documentación para desarrolladores de Apple.
Visualización del botón de Apple Pay
Apple proporciona el botón PKPaymentButton, que puede usar en las pantallas de pago de su aplicación.
Para determinar si el dispositivo es compatible con Apple Pay, use el método canMakePayments en PKPaymentAuthorizationController.
Crear y utilizar una PKPaymentRequest
Para obtener información sobre cómo crear y utilizar una PKPaymentRequest, consulte Creating Payment Requests (Creación de solicitudes de pago) en la documentación para desarrolladores de Apple.
Actualizar una sesión con un PKPAYMENTTOKEN
Después de que un usuario haya autorizado Apple Pay, la aplicación debe actualizar la sesión del motor de pagos con ese token de pago.
Siga estos pasos para actualizar una sesión con un PKPAYMENTTOKEN.
- Obtenga el token de pago como una cadena para enviar el token de pago al motor de pagos.
- Rellene la cadena del token en
GatewayMapcomodevicePaymenty especifique que el token procede de Apple Pay mediante la configuración dewalletProvider. - El
GatewayMappara su solicitud ahora se puede enviar al motor de pagos utilizando el métodoupdateSessionen el objetoGatewayAPI.
let tokenString = String(data: payment.token.paymentData, encoding.utf8)
var request = GatewayMap() request.sourceOfFunds.provided.card.devicePayment.paymentToken = tokenString request.order.walletProvider = "APPLE_PAY"
GatewayAPI.shared.updateSession("< session id#>", apiVersion: ""< Gateway API Version#>", payload: request) { (result) in
switch result {
case .successi(let response):
print(response.description)
case .error(let error):
print(error)
}
}
Completar una transacción de Apple Pay
Una vez que se ha actualizado una sesión con el token de pago de Apple Pay
- el pago se puede llevar a cabo desde el servicio de su negocio como cualquier otro pago.
- establezca el campo order.walletProvider en APPLE_PAY al completar un pago en una sesión que utilice Apple Pay.
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 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 nuevo Mobile SDK 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.
let request = AuthenticationRequest (navController: navController,
apiVersion: apiVersion,
sessionId: sessionId,
orderId: orderId,
transactionId: authenticationTxnId)
AuthenticationHandler.shared.authenticate(request) { (response) in
// handle response
}
authenticationTxnId 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á authenticationTxnId 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 devuelve 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 doNotProceed.
- proceed: indica "OK para continuar con un pago o autorización".
- doNotProceed: 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.shared.authenticate(request) { (response) in
DispatchQueue.main.async {
switch response.recommendation {
case .doNotProceed:
if let error = response.error {
print ("SDK Error:\(error.localizedDescription)")
if let authError = error as? AuthenticationError,
authError ==
.recommendation_ResubmitWithAlternativePaymentDetails {
//"Authentication not successful, re-enter card details"
}
}
// "Authentication not successful"
case .proceed:
// Proceed to submit the payment, authorization etc
}
}
}
Si la autenticación falla, examine response.error para obtener más información sobre la causa.
Información adicional
Compilaciones de dispositivo y de simulador
El SDK del motor de pagos se proporciona con dos compilaciones: una versión de dispositivo y una versión de simulador.
El código intermedio solo se puede habilitar para binarios que no admitan x86_64. Es probable que los clientes prefieran la versión del SDK de dispositivo en el momento del lanzamiento, por lo que pueden habilitar el código intermedio en sus aplicaciones, lo que permite que la aplicación ocupe menos espacio en el dispositivo de un usuario.
Sin embargo, muchos desarrolladores prefieren usar un simulador mientras desarrollan, por lo que la arquitectura x86_64 es necesaria. Además, durante el desarrollo, el espacio que ocupa la aplicación no suele ser un problema. El motor de pagos proporciona tanto versiones del SDK para dispositivos compatibles con código intermedio y para simuladores no compatibles con código intermedio para permitir que los clientes elijan lo que deseen para trabajar en cualquier escenario específico.
Es importante recalcar que la funcionalidad y la interfaz son exactamente iguales.
Consulte la documentación de Apple para obtener más información.