Introducción

Esta sección te explica paso a paso como integrar métodos de pago alternativos tu comercio a través de DEUNA. Los métodos de pago alternativos (APMs) son sistemas diferentes a tarjetas de crédito y débito que existen actualmente en el mundo digital para pagar online. Algunos ejemplos son SPEI, PayPal, PSE, ApplePay, Webpay, etc.

Para explorar la lista completa de APMs que puedes integrar a través de DEUNA, consulta nuestra sección de conexiones en la documentación. Por ejemplo, la lista de APMs disponibles en México está aquí.

Si quieres explorar como se ven los formularios de pago, puedes hacerlo en nuestra página de pruebas:

1. Visita nuestra página de pruebas haciendo click a este link.
2. Selecciona un producto y agrégalo al carrito
3. Haz click en el botón finalizar compra y en el popup/modal que te va a aparecer selecciona la opción de formularios. Haz click en confirmar
4. Vas a ver en la pantalla los diferentes botones de pago con diferentes APMs. Está página es como si fuera la página del checkout de tu comercio. Al seleccionar un método de pago y hacerle click al botón Pagar se abrirá el formulario de DEUNA asociado a ese APM quien se encargará de recolectar la información necesaria para procesar el pago y posteriormente procesarlo.

👍

Para probar un flujo de compra completo contacta a tu agente en DEUNA para obtener los datos de prueba.

Formulario de pagos

Los formularios de pagos son una solución híbrida que combina headless (UI/UX controlado completamente por el comercio) y el widget de pagos ya que no reemplaza por completo la sección y manejo de métodos de pago a disponerle al usuario pero tampoco le deja el trabajo pesado y complicado al comercio de tener que construir la experiencia que cada APM requiere desde cero. Estos formularios permiten al comercio mantener su flujo de pagos y simplemente agregar botones para los APMs que desean soportar. Cuando el usuario escoja uno de esos botones, el comercio abriría el formulario pre-construido de DEUNA para ese APM, facilitando así la recolección y validación de la información necesaria para el pago con DEUNA.

Experiencia en web (tipo de presentación modal)

Puedes experimentar cómo funcionan formularios en nuestra página de demostración: Explora DEUNA.

Experiencia en app (tipo de presentación modal)

Integración de formularios en app:

Integración vía payment link

1. Asegúrate de configurar en el admin de DEUNA los APMs que deseas ofrecer en tu comercio y los procesadores de pago asociados, por ejemplo, en México, podrías ofrecer pagos en efectivo con OXXO a través de Conekta.

2. Crear una orden DEUNA de tipo PAYMENT_LINK e incluye el nombre del APM en el objeto de include_payment_options. Encuentra más información sobre el token de orden en nuestra documentación.

   Ejemplo de request:

   1. curl --location 'https://api.stg.deuna.io/merchants/orders' \
      --header 'x-api-key: <merchant-api-key>' \
      --header 'Content-Type: application/json' \
      --data '{
          "order": {
              "order_id": "<order id of the merchant>",
              "currency": "MXN",
              "items_total_amount": 3000,
              "sub_total": 3000,
              "total_amount": 3000,
              "store_code": "all",
              "include_payment_options": [
                   {
                     payment_method: "bnpl",
                     processors: ["paypal_commerce_platform"],
                   },
              ],
              "metadata": {
                  "site_domain": "https://www.laika.com"
              },
              // indica el uso de formularios
              "checkout_modules": [
              	{
                  "name": "PaymentFormPattern",
                  "url": ""
                }
          		],
          },
          "order_type": "PAYMENT_LINK"
      }'

      Otros ejemplos de APMs que puedes usar eninclude_payment_options son PSE, SPEI, Webpay, Nequi Push, DaviPlata, ApplePay, entre otros. Recuerda que puedes encontrar más opciones en la sección de conexiones, por ejemplo, las conexiones en México están aquí.

   • Pix (Brazil)
     Contacta a tu asesor comercial para que te cuente sobre los diferentes tipos de integración que tenemos con Pix

   • {
     	"include_payment_options": [
        		{
          		"payment_method": "pse",
      	    	"processors": ["kushki_pse"],
        		},
     	],
     }

     
     
   • PSE (Colombia)

   Está disponible a través de varios PSPs como MercadoPago, Kushki, PayU, etc.

   • Kushki

   {
   	"include_payment_options": [
      		{
        		"payment_method": "pse",
    	    	"processors": ["kushki_pse"],
      		},
   	],
   }

   • Mercado Pago

   {
   	"include_payment_options": [
      		{
        		"payment_method": "pse",
        		"processors": ["mercadopago"],
      		},
   	],
   }

   
   
   • SPEI (México)

   Está disponible a través de varios PSPs como Nuvei, Conekta, etc.

   • {
     	"include_payment_options": [
        		{
          		"payment_method": "voucher",
          		"processors": ["conekta_spei"],
        		},
     	],
     }

   • Webpay (Chile)
     • Está disponible actualmente a través de Kushki.

       • {
         	"include_payment_options": [
            		{
              		"payment_method": "webpay",
              		"processors": ["webpay_kushki"],
            		},
         	],
         }

   • Nequi Push (Colombia)

     • {
       	"include_payment_options": [
          		{
            		"payment_method": "voucher",
            		"processors": ["nequi_push_voucher"],
         	 	},
       	],
       }

   • DaviPlata (Colombia)

     • {
       	"include_payment_options": [
          		{
            		"payment_method": "voucher",
            		"processors": ["daviplata"],
          		},
       	],
       }

   • ApplePay (México y Brazil)
     • Actualmente se encuentra disponible a través de Stripe

       • {
         	"payment": {
           		"data": {
              		"processor": "stripe_apple_pay",
              		"method_type": "voucher",
            		},
         	},
         }

   🚧

   Si alguna información de la orden va a cambiar, por ejemplo, el monto, etc. deben volver a crear una nueva orden en DEUNA con la nueva información.

   1. Ejemplo de response:

      1. Se encuentra dentro del objeto order el campo payment_link que va a ser la URL del formulario de pago.

         {
         	{  
             	"token": "ac588cb0-a46e-4a39-b103-04661f54d428",  
                "order_type": "PAYMENT_LINK",  
                "order": {  
                	"order_id": "order-test-123",  
                   "store_code": "all",  
                   "currency": "MXN",  
                    ...  
                   "total_amount": 5000,  
                   ...  
                   "payment_link": {  
                    	...  
                      "include_payment_options": [  
                      		{  
                         		"payment_method": "bnpl",  
                             "processors": ["paypal_commerce_platform"]  
                          }  
                      ]  
                   }  
             }
         }

         👍

         Ese payment_link es lo que deberás renderizar en un webView para que el usuario pueda proceder con el pago. En este ejemplo, sería para que el usuario realize el pago con PayPal Wallet.

3. Cuando el usuario termine el flujo de compra en el formulario, existen tres formas en las que el comercio puede obtener el resultado y continuar con el flujo de compra (i.e. mostrar el thank you page)

   1. Webhook: cuando el pago se complete y sea exitoso o fallido le comunicaremos al comercio via webhooks. El comercio puede usar esta notificación para enviarle el resultado final del pago al usuario (i.e. recibo de compra)
      1. Puedes leer más como configurar webhooks aquí.
   2. Polling: una vez se le muestre al usuario el formulario de pagos, el cliente de la app puede empezar a hacer polling del API de DEUNA llamado Get Order para revisar si es status del pago ha cambiado.
   3. Configurar callbacks/redirect URLs: al crear la orden el comercio puede configurar redirect/callback URLs (al tokenizar la orden con DEUNA) donde podemos redirigir al usuario a diferentes páginas.

      1. {
         	"redirect_urls": {
           		"success": "https://www.success.com",
           		"failure": "https://www.failure.com",
           		"pending": "https://www.pending.com",
           		"close": "https://www.close.com"
         	},
         }

A diferencia de success, pending, failure que hacen referencia al estado del pago, ya el close hace referencia a que el usuario decidió no proseguir con el pago y/o cerro la vista mediante alguna acción en la vista.

Integración vía SDKs

En el caso que quieras usar directamente los SDKs, DEUNA ofrece SDKs nativos para Swift (iOS) y Kotlin (Android).

Integración de formularios en web:

Para integración en web puedes usar la integración via payment link descrita dentro de la sección de integración para App o usar directamente el Web SDK de DEUNA. Algunas diferencias para que tengas en consideración al momento de decidir que manera de integrar quieres usar son las siguientes:

1. Usando el web SDK, los formularios de pago se van a abrir como un modal dentro de la misma página del comercio ya que queremos evitar redireccionamientos o cambiar significativamente la experiencia de compra dentro de la página del comercio. Este modal recibe constantes mejoras de UI/UX para cada vez ayudar a mejorar la conversión. Este modal ya está diseñado para que se ajuste correctamente a vistas en dispositivos móbiles como en desktops.

   1. 👍

      Nota: integración recomendada por DEUNA

2. Usando la integración vía payment link, le da la flexibilidad al comercio a abrir el formulario en una pestaña aparte si es algo que se espera o incluso permitirle que el comercio sea el dueño del iframe/webView donde puede abrir el formulario de pagos.

Integración vía Web SDK

1. Agrega el script del web sdk de DEUNA a tu página web:

   1. <script type="text/javascript" src="https://cdn.stg.deuna.io/now-widget/v0.1/index.js" />

2. Crea una orden en DEUNA de la misma manera descrita en esta sección.

3. Inicializa y configura el SDK con el token de la orden y el publicKey asociado a tu comercio en DEUNA:

   1. const deunaPayGlobal = new window.DeunaPay();
      
      await deunaPayGlobal.configure({
        orderToken: "<token de la orden creada en el paso 2.>",
        apiKey: "<public key de tu comercio en DEUNA>",
        env: "<staging o production>"
        onEventDispatch: (event, payload) => {
          console.log({ event, payload });
        },
        widget: "forms", // indica que se usará el flujo de formularios de pago
      });

4. Una vez que el usuario escoja el método de pago y se deba proceder con el pago. Puedes invocar el siguiente método ofrecido por el SDK para abrir el formulario de pago:

   1. await deunaPayGlobal.show({
        callbacks: {
          onClose: () => console.log("hola"),
          onPaymentSuccess: () => {
            console.log("this worked");
            resetAllStoreValues();
            router.push("/thank-you");
          },
          onPaymentError: () => alert("Payment Error"),
          onUserConfirm: () => {
            console.log("steps completed");
            router.push("/thank-you");
          },
          onPendingPayment: () => console.log("pending payment"),
        },
      });

      • Los callbacks te permiten poder registrar lógica de negocio según el resultado del pago y/o interacción con del usuario con el formulario de pagos

Integración vía Direct API

Para la integración vía API los diferentes APMs es necesario revisar la interfaz de los siguientes servicios, ambos contienen información necesaria como por ejemplo los campos requeridos.

1. Crear token de orden
2. Realizar pago de orden

Una vez revisado ambos servicios detallaremos los campos específicos o mínimos que son requeridos para ejecutar correctamente el flujo del pago de una orden.

PSE (Colombia) vía Kushki

Actualmente nuestra implementación cuenta con certificación PSE Avanza, a seguir detallamos los campos necesarios para realizar un pago con PSE Avanza.

Petición al API de /purchase

{
    "token": "<information retrieved on create order step>", //uuid
    "email": "[email protected]",
    "store_code": "all",
    "method_type": "pse",
    "processor_name": "kushki",
    "billing_address": {
        // Needed for PSE Avanza
        "first_name": "John",
        // Needed for PSE Avanza
        "last_name": "Doe",
        // Needed for PSE Avanza
        "phone": "56728887272",
        // Needed for PSE Avanza
        "address1": "user address",
        // It can be CC or NIT
        "identity_document_type": "CC",
        "identity_document": "Match pattern [0-9]{10}"
    },
    "specific_fields": {
        // this information is retrieved on resource payment options is the bank identification
        "financial_institution": "0001"
    },
    // URL that will redirect after actions on PSE page
    "callback_url": "https://www.your.url.goes.here.com"
}

🚧

Observación referente al callback_url la página de PSE tanto para casos de éxito con de error retornará a la misma URL definida en el callback

Respuesta

En la respuesta del pago se obtiene la URL(external_resource_url) que permitirá al usuario proceder con el pago mediante este método. Recuerda debes abrir esta URL para que el usuario pueda terminal el pago.

Apple Pay vía Stripe

Actualmente nuestra implementación es vía Stripe por lo que necesitamos seguir unos pasos previos para obtener el medio de pago o identificador de instrumento de pago, mediante el botón de Apple Pay, esta información la puedes obtener mediante soporte técnico y además se brindará soporte a la mejor solución que se ajuste a su flujo de pagos, a seguir detallamos los campos necesarios para realizar un pago con Apple Pay.

Petición al API de /purchase

{
    "token": "order token",
    "email": "[email protected]",
    "store_code": "all",
    "method_type": "voucher",
    "processor_name": "stripe_apple_pay",
    "specific_fields": {
        "apple_pay": {
            "payment_method_id": "payment method identifier"
        }
    },
    "callback_url": "https://deuna.com"
}

Google Pay vía Stripe

Actualmente nuestra implementación es vía Stripe por lo que necesitamos seguir unos pasos previos para obtener el medio de pago o identificador de instrumento de pago, mediante el botón de Google Pay, esta información la puedes obtener mediante soporte técnico y además se brindará soporte a la mejor solución que se ajuste a su flujo de pagos, a seguir detallamos los campos necesarios para realizar un pago con Google Pay.

Petición al API de /purchase

{
    "token": "order token",
    "email": "[email protected]",
    "store_code": "all",
    "method_type": "wallet",
    "processor_name": "stripe_google_pay",
    "specific_fields": {
        "google_pay": {
            "payment_method_id": "payment method identifier"
        }
    },
    "callback_url": "https://deuna.com"
}

Estado de la orden

Cuando el usuario complete la transacción mediante en link de PSE, existen tres formas en las que el comercio puede obtener el resultado de la orden y continuar con el flujo de compra (i.e. mostrar el thank you page)

1. Webhook: cuando el pago se complete y sea exitoso o fallido le comunicaremos al comercio via webhooks. El comercio puede usar esta notificación para enviarle el resultado final del pago al usuario (i.e. recibo de compra)
   1. Puedes leer más como configurar webhooks aquí.
2. Polling: una vez se le muestre al usuario el formulario de pagos, el cliente de la app puede empezar a hacer polling del API de DEUNA llamado Get Order para revisar si es status del pago ha cambiado.
3. Configurar callbacks URL: Importante tener presente que el callback_url siempre será usado independiente del estado del pago que retorne el APM.
   1. NOTA: los redirect_urls solo están disponibles cuando se integra usando el Widget de Formularios y no cuando se integra vía direct API.

Requisitos para implementación

Los proveedores de métodos de pago alternativos (APMs) han definido requisitos específicos para obtener una implementación certificada. A continuación, proporcionamos los datos esenciales que deben reflejarse en tu comprobante de pago al utilizar uno de estos APMs:

¿Tienes dudas o preguntas sobre formularios de pago?

No dudes en contactarnos al correo [email protected] y con gusto resolveremos todas tus dudas.