Headless SDK (Pago iOS)

👍
SDK recomendado
Recomendamos utilizar el Seamless SDK iOS para una experiencia de integración sin problemas. Esta opción ofrece una solución de pago flexible con componentes de interfaz de usuario predefinidos y opciones de personalización.

El SDK Headless para iOS de Yuno te permite crear pagos y registrar métodos de pago simultáneamente. Ten en cuenta que, al usar el SDK Headless, deberás solicitar y enviar por API todos los campos obligatorios que el proveedor de pagos requiere para generar el pago en su API.

El SDK Headless de Yuno le permite crear pagos en dos escenarios diferentes:

Cree un Token de un solo uso utilizando la información de su tarjeta de crédito o métodos de pago alternativos y, a continuación, cree un pago.
Cree un Token de un solo uso usando un vaulted_token desde un método de pago previamente registrado para recopilar información relevante para proveedores de fraude y luego crear un pago.

Los siguientes pasos describen la creación de un pago usando el Headless SDK de Yuno.

Paso 1: Incluya la biblioteca en tu proyecto

El primer paso es instalar el SDK de Yuno en su proyecto iOS.

📘
Comprobar las versiones del SDK de iOS
Para ver todas las versiones disponibles, visita la página de versiones en el repositorio de Yuno iOS SDK.

Puede instalar el SDK de Yuno de dos maneras:

Cocoapods: Si no tiene un Podfile, siga las CocoaPods guía para crear uno. Después de crear el Podfile, integrará el SDK de Yuno con Cocoapods agregando la siguiente línea a su Podfile:
```
pod 'YunoSDK', '~> {last_version}'
```
Administrador de Paquetes Swift: Configure el paquete Swift y luego agregue el SDK de Yuno como una dependencia, como se presenta en el siguiente bloque de código:
```
dependencies: [
    .package(url: "https://github.com/yuno-payments/yuno-sdk-ios.git", .upToNextMajor(from: "{last_version}"))
]
```

Paso 2: Inicialice el SDK Headless con la clave pública

Para initialize el Headless SDK, necesitas importar Yuno y proporcionar una PUBLIC_API_KEY. Si no tienes tus credenciales de API, accede a la página Desarrolladores (Credenciales ) para comprobar cómo recuperarlas desde el panel de control.

🚧
Inicialización de UISceneDelegate
Si tu aplicación utiliza un UISceneDelegateAsegúrese de colocar el código de inicialización de Yuno dentro de su SceneDelegate. Más información

El bloque de código siguiente presenta un ejemplo de importación e inicialización del Yuno.

import YunoSDK

Yuno.initialize(
    apiKey: "PUBLIC_API_KEY"
)

Paso 3: Iniciar el proceso de pago

A continuación, iniciará el proceso de pago utilizando la función apiClientPayment , proporcionando los parámetros de configuración necesarios. Debe llamar a esta función una vez que su cliente seleccione el método de pago. Como resultado, el SDK comenzará a recopilar información relevante para 3DS y las herramientas de prevención de fraude que haya configurado en su enrutamiento.

Parámetros

La siguiente tabla enumera todos los parámetros requeridos y sus descripciones.

Parámetro	Descripción
`countryCode`	Este parámetro determina el país para el cual se está configurando el proceso de pago. La lista completa de países admitidos y sus `countryCode` está disponible en la Cobertura de países .
`checkout_session`	Se refiere a la sesión de pago actual creada mediante el endpoint Crear sesión de pago. Example: '438413b7-4921-41e4-b8f3-28a5a0141638'

El siguiente bloque de código presenta un ejemplo de la configuración de parámetros.

var apiClientPayment: YunoPaymentHeadless?

apiClientPayment = Yuno.apiClientPayment(
 countryCode: "CO",
 checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638"
)

Paso 4: Generar token

Tras recopilar toda la información del usuario, puede iniciar el pago. Primero, debe crear un token de un solo uso (OTT) mediante la función apiClientPayment.generateToken. Como es una función asincrónica, puedes usar do/catch Para garantizar la correcta gestión de los errores generados, a continuación, encontrará dos ejemplos de diferentes escenarios para crear un token de un solo uso:

Ejemplo 1: Crear un token de un solo uso utilizando una tarjeta como método de pago e incluyendo toda la información necesaria de la tarjeta.
Ejemplo 2:Crea un token de un solo uso usando el vaulted_token .

👍
Ventajas de usar un token almacenado en bóveda
El uso de un token almacenado con el SDK garantiza que toda la información sobre fraude de los proveedores configurados se recopile y se adjunte al token de un solo uso. Además, puede incluir detalles de pago y un código de seguridad si el proveedor lo requiere.

let tokenCollectedData: TokenCollectedData = TokenCollectedData(
 checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638",
    método de pago: CollectedData(
        tipo: "TARJETA",
 vaultedToken: nil,
        tarjeta: CardData(
            guardar: true,
            detalle: CardData.Detail(
                número: "4111111111111111",
                expirationMonth: 12,
                expirationYear: 25,
                securityCode: "123",
                holderName: "Andrea",
                type: .credit
            ),
            installment: CardData.Installment(
                id: "64ceacef-0886-4c81-9779-b2b3029c4e8b",
                value: 1
            )
        ),
        customer: Customer()
    )
)

let result = try await apiClientPayment.generateToken(
    data: tokenCollectedData
)

let tokenCollectedData: TokenCollectedData = TokenCollectedData(
 checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638",
    paymentMethod: CollectedData(
        type: "CARD",
 vaultedToken: "c8bb2bd8-8abf-4265-b478-0ec4e3c10cd5",
        card: CardData(
            installment: CardData.Installment(
                id: "64ceacef-0886-4c81-9779-b2b3029c4e8b",
                value: 1
            )
        ),
        customer: Customer()
    ))


let result = try await apiClientPayment.generateToken(
    data: tokenCollectedData
)

El siguiente bloque de código presenta el apiClientPayment.generateToken para los dos ejemplos anteriores. La respuesta es un diccionario de tipo. [String: Any].

 ["token": "9ee44ac7-9134-4598-ae28-a26fec03099d",
     "type": "CARD",
     "customer": ["billing_address": nil,
                  "first_name": nil,
                  "gender": "",
                  "phone": nil,
                  "browser_info": ["color_depth": nil,
                                   "language": "en",
                                   "accept_header": "*/*",
                                   "browser_time_difference": nil,
                                   "accept_content": nil,
                                   "accept_browser": nil,
                                   "java_enabled": nil,
                                   "user_agent": "YunoSDK_Example/1 CFNetwork/1406.0.4 Darwin/22.6.0",
                                   "screen_height": "844.0",
"screen_width": "390.0",
"javascript_enabled": nil],
                  "document": nil,
                  "last_name": nil,
                  "device_fingerprint": nil,
                  "email": nil],
     "country": "BR",
     "vaulted_token": nil,
     "installment": ["rate": "",
                     "id": "cca80084-961b-4212-9c34-54f03f4f10ae",
                     "value": 24,
                     "amount": nil],
     "card_data": nil]

["token": "9ee44ac7-9134-4598-ae28-a26fec03099d",
     "type": "CARD",
     "customer": ["billing_address": nil,
                  "first_name": nil,
                  "gender": "",
                  "phone": nil,
                  "browser_info": ["color_depth": nil,
                                   "language": "en",
                                   "accept_header": "*/*",
                                   "browser_time_difference": nil,
                                   "accept_content": nil,
                                   "accept_browser": nil,
                                   "java_enabled": nil,
                                   "user_agent": "YunoSDK_Example/1 CFNetwork/1406.0.4 Darwin/22.6.0",
                                   "screen_height": "844.0",
"screen_width": "390.0",
"javascript_enabled": nil],
"document": nil,
"last_name": nil,
"device_fingerprint": nil,
"email": nil],
     "country": "BR",
     "vaulted_token": "a1c7c5d1-b260-4dc6-909a-8368704233cf",
     "installment": ["rate": "",
                     "id": "cca80084-961b-4212-9c34-54f03f4f10ae",
                     "value": 24,
                     "amount": nil],
     "card_data": nil]

Paso 5: Crea el pago

Una vez completados los pasos descritos anteriormente, puede crear un pago. La creación de pagos consecutivos debe realizarse utilizando el endpoint Create Payment . El comerciante debe llamar a su backend para crear el pago dentro de Yuno, utilizando el token de un solo uso y la sesión de pago.

La respuesta endpoint incluye sdk_action_required que indica si se necesitan acciones adicionales para completar el pago:

En los métodos de pago síncronos, el pago se completa instantáneamente. En este caso sdk_action_required será falso en la respuesta de la API y el pago finalizará. Si el pago una interacción adicional por parte del SDK para completar el flujo, sdk_action_required será cierto; en este caso, continúa con el paso 6 para obtener instrucciones.

Paso 6: Procesar pagos asincrónicos (opcional)

Un pago con 3DS puede requerir una impugnación adicional para comprobar la identidad del cliente, como se describe en la página Verificación de tarjeta 3DS. Si es necesaria una impugnación de verificación 3DS, la respuesta endpoint Crear pago contendrá:

Estado igual a PENDING y subestado igual a WAITING_ADDITIONAL_STEP
sdk_action_required = true
Un tipo de transacción redirect_url definido en payment.payment_method.payment_method_detail.card

Para realizar el reto y finalizar el pago, tienes dos opciones de integración:

Obtener la URL del desafío 3DS

Obtener la URL del desafío 3DS

Para obtener la URL del desafío 3DS, debes llamar al getThreeDSecureChallenge proporcionando la función checkoutSession. La función checkoutSession solo es obligatoria si no está utilizando el que se utilizó para crear el pago. A continuación encontrará un ejemplo del uso de la función getThreeDSecureChallenge . Como getThreeDSecureChallenge es una función asincrónica, puedes usar do/catch para asegurarte de manejar correctamente los errores desencadenados.

func getThreeDSecureChallenge(checkoutSession: String?) async throws -> ThreeDSecureChallengeResponse

El objeto getThreeDSecureChallenge devolverá el ThreeDSecureChallengeResponse, presentado en el siguiente bloque de código:

public struct ThreeDSecureChallengeResponse {
    public let url: String
}

El objeto url contendrá una URL válida que necesita para redirigir a su cliente para completar el desafío.

Tu eres responsable de redirigir a tus clientes a la URL proporcionada por el getThreeDSecureChallenge() función para completar el desafío. Una vez que el cliente complete con éxito el desafío 3DS, será redirigido automáticamente a la callback_url, que proporcionó al crear el checkout_session con el endpoint Crear Sesión de Checkout endpoint.

Para confirmar que se completó el desafío, puede abrir una vista web para cargar la URL proporcionada y escuchar el messageFromWeb evento. A continuación se muestra un código de ejemplo que demuestra cómo escuchar este evento.

class HeadlessWebView: UIViewController, WKScriptMessageHandler, WKNavigationDelegate {

    private var webView: WKWebView!
    private var url: String = ""
    private let configuration = WKWebViewConfiguration()

    init(url: String) {
        self.url = url
        super.init(nibName: nil, bundle: nil)
    }

    required init?(coder: NSCoder) {
        nil
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        view.backgroundColor = .white
        webViewConfig()
    }

    func webViewConfig() {
   
        configuration.preferences.javaScriptEnabled = true
        configuration.userContentController.add(self, name: "messageFromWeb")
        webView = WKWebView(frame: view.bounds, configuration: configuration)
        webView.navigationDelegate = self

        guard let url = URL(string: url) else {
            return
        }
        let request = URLRequest(url: url)
        webView.load(request)

    }

    func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
        if message.name == "messageFromWeb", let messageBody = message.body as? String {
            self.dismiss(animated: true)

        }
    }

    override func viewDidDisappear(_ animated: Bool) {
        super.viewDidDisappear(animated)
        self.configuration.userContentController.removeScriptMessageHandler(forName: "messageFromWeb")
    }

}

La respuesta informará el estado del desafío, que puede ser COMPLETED o ERROR. El siguiente bloque de código presenta ejemplos para cada opción posible.

{
   "origin":"CHALLENGE",
   "status":"COMPLETED",
   "data":"callback_url"
}

{
   "origin":"CHALLENGE",
   "status":"ERROR",
   "data":"Invalid 3DS provider"
}

Para completar el flujo de pago de Headless SDK , necesita utilizar Yuno Webhooks, que le notificará puntualmente sobre el resultado del desafío 3DS y el estado final de pago. El uso de webhooks garantiza que reciba actualizaciones en tiempo real sobre el progreso de la transacción de pago. Además de los webhooks, puede recuperar la información de pago utilizando el endpoint Recuperar pago por ID.

Para terminar la implementación de pago y comprender los pasos restantes, accede al SDK Headless (pago).

Paso 7: Gestionar el estado del pago (opcional)

🚧
Enlaces profundos y Mercado Pago Checkout Pro
Este paso solo es necesario si utilizas un método de pago que utiliza enlaces profundos o Mercado Pago Checkout Pro. Si tus métodos de pago no utilizan enlaces profundos, puedes omitir este paso.

Algunos métodos de pago sacan a los usuarios de la app para completar la transacción. Una vez finalizado el pago, se redirige al usuario a la app mediante un enlace profundo. El SDK utiliza este enlace profundo para comprobar qué ha sucedido, verificando si el pago se realizó correctamente, falló o se canceló, y puede mostrar una pantalla de estado al usuario.

Para solucionar esto, necesita actualizar su AppDelegate Para devolver la URL entrante al SDK de Yuno. Esto permite que el SDK lea el resultado y, opcionalmente, muestre el estado del pago. El siguiente fragmento de código muestra cómo añadirlo a la aplicación:

func application(_ app: UIApplication,
                 open url: URL,
                 options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {

  guard url.scheme == "yunoexample" else { return false }

  return Yuno.receiveDeeplink(url, showStatusView: true)
}

Este código detecta enlaces profundos que abren tu aplicación. Al recibir una URL, comprueba si el esquema coincide con el que usaste en el callback_url durante la configuración de la sesión de pago. Si coincide, la URL se pasa al SDK de Yuno mediante Yuno.receiveDeeplink(...). A continuación, el SDK lee el resultado del pago y, si showStatusView está configurado para true, muestra la pantalla de estado apropiada al usuario.

Asegúrese de que url.scheme En este código coincide con el callback_url que usted proporcionó al crear el checkout_session.

📘
App Demo
Además de los ejemplos de código proporcionados, puedes acceder al repositorio de Yuno para una implementación completa de Yuno iOS SDKs.