Integración: Direct API

Introducción

Esta sección te explica paso a paso como poder integrar en tu comercio via Direct API (headless) la solución de payments and fraud orchestration de DEUNA. Nuestro que DEUNA son organizados alrededor de REST, es decir, son orientados sobre recursos, reciben y retornan JSON responses, al igual que usan lo códigos standard de respuesta de HTTP al igual que los estándares en autenticación y los verbos (GET, POST, PATCH, etc.)

Pros y Cons de la integración Headless

Ventajas:

Si el comercio no quiere cambiar su UI/UX en la sección de su checkout donde el usuario selecciona el método de pago, este manera de integración optimiza para ello.
Si se desea, se provee la opción, tanto para pagos con tarjeta o métodos de pago alternativos (APMS) podemos retornar la URL al formulario web white-label necesario para poder procesar el pago con ese método de pago. De esta manera, el comercio no necesita crear sus propios formularios y flujos especiales para cada APM que quiera integrar. El formulario web para tarjetas incluiría (si se desea):
- Permitirle a los usuarios almacenar y administrar sus tarjetas para futuras compras.
- Manejar nativamente el flujo de 3DS
- Para menor exposición a sensitive PCI payment data, al usar nuestro formulario, es este quien estaría recolectando la información de la tarjeta client-side y por ende ni siquiera esta información tocaría el client-side code del comercio. Es importante aclarar que DEUNA es PCI Compliant.

Desventajas:

El comercio es el encargado de agregar nuevos botones a su UI cada vez que quiera agregar un método de pago adicional. Esto conlleva una integración adicional por cada APM (método de pago alternativo). Y en caso no quiera usar los formularios pre-construidos de DEUNA, el comercio debe construir y mantener sus propios flujos y formularios de pago.
Si el comercio quiere conservar su propio formulario de pagos con tarjeta, va a requerir manejar la lógica de almacenamiento de tarjetas y del flujo de 3DS directamente desde la lógica del comercio.

Ambientes

DEUNA cuenta con dos ambientes 100% independientes:

Sandbox: Este es el ambiente que se usa para realizar pruebas. Este ambiente contiene las conexiones a los diferentes proveedores de pagos y fraude apuntando a sus respectivos ambientes de prueba, por ende, las pruebas deben realizarse con datos de pruebas (tarjetas, etc.) que disponga cada proveedor.
1. URL: https://api.sandbox.deuna.io
2. Timeout: debido a que los ambientes de prueba de los diferentes proveedores ofrecen tiempos de respuesta más altos tenemos un timeout en este ambiente de 75 segundos. El tiempo de respuesta promedio es una fracción de este tiempo.
Producción: Este es el ambiente real que usará el comercio para procesar transacciones en su ambiente productivo. Lo más recomendado es que el comercio siempre pruebe su integración primero en el ambiente de Staging antes de moverse al productivo.
1. URL: https://api.deuna.io
2. Timeout: contamos con un timeout duro de 60 segundos. Este timeout time tiene en consideración que la transacción puede contactar multiples proveedores anti-fraude y de pagos.

Autenticación

DEUNA creará para tu comercio un API Key privado y uno público que son usados para autenticarte como comercio a nuestro API. En los APIs usados para crear un cargo, almacenar tarjetas a nombre de un cliente/usuario, etc. usamos un Token de autenticación tipo JWT con expiración para hacer operaciones a nombre del usuario.

Cuando crees tu cuenta de Sandbox de DEUNA, desde el ADMIN o por ayuda a soporte, puedes obtener tu API Key publica y privada. Estas pueden ser renovadas en cualquier momento así mismo como poder crear múltiples API Keys asociadas a la misma cuenta.

Idempotencia (Opcional)

Nuestro API soporta idempotencia para que puedas tranquilamente reintentar peticiones a nuestro API sin preocuparte que accidentalmente generes la misma operación dos veces. Para poder realizar peticiones idempotentes, debes mandar en cada peticion como header la llave X-Idempotency-Key. DEUNA guarda el codigo de respuesta y el payload de la primer peticion para cada valor del idempotency key que nos mandes. Sugerimos usar UUIDs versión 4 para evitar colisiones. DEUNA puede remover los idempotency keys despues de 24 horas desde la primer peticion con ese idempotency key. Los idempotency keys son usado para el verbo HTTP: POST.

Colección de Postman

DEUNA cuenta con la siguiente colección de Postman pública para que los comercios y sus desarrolladores puedan basar sus integraciones y hacer pruebas de una manera más conveniente: https://docs.deuna.com/reference/colecciones-de-postman

Diagrama de integración

Ejemplo de integración en un comercio que contiene manejo y creación de usuarios (login, signup, etc.)

📘
Este flujo de integración demuestra la creación de usuario, tarjeta y orden y por ende el pago. Recordar que la mayoría de estos pasos son opcionales.

Manejo de usuarios

DEUNA permite la creación de usuarios para un mejor manejo y estructura de todos los recursos y servicios ofrecidos. De esta manera el comercio va a poder asociarle tarjetas almacenadas a un usuario, asociar pagos a usuarios, etc.

Pasos para el manejo de usuarios:

Creación de usuarios:
1. https://docs.deuna.com/reference/create-user
2. Ejemplo: https://www.postman.com/deunaonline/workspace/deuna/request/30572503-8fd8a768-14ec-4d47-9e2b-8aaae5af6c38?action=share&source=copy-link&creator=26335913&ctx=documentation
3. Ejemplo de respuesta exitosa:
```
{
    "token": "<user token (JWT token usado para autenticación)>",
    "user_id": "<user ID v4 UUID>"
}
```
Operaciones adicionales sobre usuarios DEUNA:
1. Eliminar un usuario: https://docs.deuna.com/reference/delete-user
  1. Ejemplo: https://www.postman.com/deunaonline/workspace/deuna/request/30572503-495df316-877b-4d4a-b40e-b4ff9cad0d95?action=share&source=copy-link&creator=26335913&ctx=documentation
2. Obtener un usuario: https://docs.deuna.com/reference/get-user
  1. Ejemplo: https://www.postman.com/deunaonline/workspace/deuna/request/30572503-d2cc6b2e-bb1d-474d-af33-fad090dac4f3?action=share&source=copy-link&creator=26335913&ctx=documentation

Almacenamiento de tarjetas para uso futuro

DEUNA cuenta con la funcionalidad de almacenamiento de tarjetas para permitirle a sus comercios recordarle las tarjetas previamente almacenadas y por ende darles una mejor experiencia de usuario. DEUNA genera un token único por cada tarjeta creada que puede ser almacenada sin ningún riesgo por parte del comercio. Si tu comercio no es PCI compliant, esta funcionalidad te permite tokenizar client-side la tarjeta y enviar este token a tu servidor (backend) y procesar el pago desde allí sin ningún problema.

Revisa esta sección para una guía paso a paso: https://docs.deuna.com/docs/headless-payments-and-fraud-module

📘
Si tu comercio es PCI compliant, puedes procesar pagos sin previamente haber tenido que tokenizar la tarjeta con DEUNA.

Procesar un pago

Con DEUNA puedes procesar mediante una sola integración pagos de tus usuarios usando nuestro motor de pagos y fraude que te permite, entre muchos beneficios, orquestrar en tiempo real el pago por multiples proveedores de pagos y fraude manteniendo una misma estructura de respuesta y una estandarización de códigos de error entre los proveedores, lo que hace esta integración con DEUNA mucho mas sencilla.

Pasos para procesar un pago

Crea una orden y el pago en un solo paso: para algunos comercios, es mas conveniente y sencillo procesar el pago sin tener que haber creado previamente una orden con DEUNA.
1. https://docs.deuna.com/reference/purchase-v2
2. Ejemplo: https://www.postman.com/deunaonline/workspace/deuna/request/30572503-148791f4-b739-42e3-895a-29d643d4b2ef?action=share&source=copy-link&creator=26335913&ctx=documentation
3. 📘
  El method_type siempre debe ser "credit_card" independiente del tipo de tarjeta

Crea una orden: Para procesar un pago, primero se debe crear una orden con DEUNA. A esta operación usualmente tambien le conocemos como tokenizar una orden.
1. https://docs.deuna.com/reference/create-order
2. Ejemplos: https://www.postman.com/deunaonline/workspace/deuna/folder/30572503-336ddbb2-3784-467b-bef9-0e7c5f425d7c?action=share&source=copy-link&creator=26335913&ctx=documentation
  1. NOTAS:
    1. En el link de la documentación de esta API puedes encontrar todos los campos que puedes compartirnos y varian según lo que tu comercio necesite.
    2. Puedes crear una order con DEUNA donde solo tenga disponible ciertos métodos de pago (asociados a los procesadores que quieres tener disponibles para cada uno de eses métodos de pagos) usando la propiedad include_payment_options. Esta propiedad es opcional. En caso de no usarse, los métodos de pago que estarán disponibles para la orden serán los activos a nivel tu comercio en DEUNA.
      1. Para consultar los métodos de pago disponibles para una orden: https://docs.deuna.com/reference/get-merchants-payments-methods
3. Ejemplo de respuesta exitosa:
```
{
    "token": "<token de la orden creado pro DEUNA>",
    "order_type": "...",
    "order": {
        "order_id": "<el id de la orden en tu comercio>",
        "currency": "MXN",
        ...
        "total_amount": 3000,
        "items": [],
        "discounts": [],
        "shipping_address": {
            ...
        },
        "shipping_options": {
            ...
        },
        ...
        "status": "pending",
        "payment": {
            "data": {
                ...
            }
        },
        "gift_card": [],
        "redirect_url": "",
        "webhook_urls": null,
        "shipping": {
            "original_amount": 0,
            "total_discount": 0,
            "discounts": []
        },
        "shipping_method": {
            ...
        },
        "shipping_methods": [],
        "billing_address": {
            ...
        },
        ...
    },
}
```

Realiza el pago sobre la orden creada: En caso de que hayas decido crear la orden previamente, puedes procesar el pago a esa orden de la siguiente manera:

https://docs.deuna.com/reference/purchase-v1
DEUNA por medio de este API se encarga en tiempo real de evaluar las diferentes estrategias de pago (workflows) para determinar la ruta de proveedores por los cuales debemos mandar esta transacción.
Para probar crear pagos en el ambiente de Sandbox de DEUNA debes usar las tarjetas de prueba de los procesadores de pago que tienes configuradas en DEUNA.

DEUNA permite realizar un purchase usando una tarjeta previamente creada o enviando los datos de la tarjeta directamente en el payload. En el caso de querer enviar los datos de la tarjeta directamente en el payload, debes contar con una certificación PCI si vas a hacer ese llamado API desde tu servidor.

Para procesar un purchase con una tarjeta previamente guardada:

Enviar el token de la tarjeta en el campo “card_id” y el campos de “credit_card” lo puedes enviar vacío (”credit_card”: {}).
En el caso que se quiera refrescar el CVV de una tarjeta previamente guardada o quizás sea una tarjeta dinámica donde el CVV va cambiando, puedes mandar el “card_id” y dentro el objeto “credit_card” el CVV
1. “credit_card”: {”card_cvv”: “XXX”}
📘
El method_type siempre debe ser "credit_card" independiente del tipo de tarjeta

Ejemplo básico de como crear una pago/purchase:

curl --location 'https://<base url deuna env>/merchants/transactions/purchase' \
--header 'x-api-key: <merchant-api-key>' \
--header 'Authorization: Bearer <user-auth-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
      "token": "<order token creado en el paso anterior>",
      "email": "<email del cliente>",
      "method_type": "credit_card", // type for card-based purchases, regardless if the card is debit or credit
      "card_id":"<card id obtenido cuando se guardó la tarjeta>",
	    "store_code": "all",
	    "credit_card": {
         "card_cvv": "567" // opcional para refrescar
      },
      // campo opcional aunque para varios proveedores es requerido
      "shipping_address": {
      	"first_name": "Esteban",
        "last_name": "Posada",
        "phone": "{country_code}{phone}",
        "city": "CDMX",
        "state_name": "CDMX",
        // usar: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
        "country": "MEX",
        "zipcode": "03100",
        "address1": "Edgar Allan Poe 102",
      },
      // campo opcional aunque para varios proveedores es requerido
      "billing_address": {
      	"first_name": "Esteban",
        "last_name": "Posada",
        "phone": "{country_code}{phone}",
        "city": "Medellin",
        "state_name": "ANT",
        // usar: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
        "country": "COL",
        "zipcode": "51111",
        "address1": "Carrera 57 #11-57",
			}
 }'

Ejemplo de respuesta exitosa:

{
    "order": {
        "order_id": "915cefaa-9f52-445e-a239-270c9268dc2f",
        "currency": "MXN",
        "total_amount": 30000,
        ...,
        "status": "succeeded", // status of the order
        "from_card": {
            "card_brand": "visa",
            "first_six": "411111",
            "last_four": "1111"
        },
        "payment": {
            "data": {
                ...
                "method_type": "credit_card",
                "processor": "stripe_direct",
                "status": "<payment status>",
                "external_transaction_id": "<transaction_id of the processor>"
                ...
            },
            ...
         },
     }
}

Para procesar un purchase con los datos de la tarjeta directos:

Enviar el campo credit_card .

Ejemplo básico de como crear un pago:

curl --location 'https://<base url deuna env>/merchants/transactions/purchase' \
--header 'x-api-key: <merchant api key>' \
--header 'Authorization: Bearer <user-auth-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "<order token creado en el paso anterior>",
    "email": "<email del cliente>",
    "method_type": "credit_card",
    "store_code": "all",
    "credit_card": {
        "expiry_month": "MM",
        "expiry_year": "YYYY",
        "card_holder": "Posada",
        "card_holder_dni": "185396924",
        "card_number": "4111111111111111",
        "card_cvv": "XXX",
        "address1": "Vergara 548",
        "zip": "03100",
        "city": "Cuahutemoc",
        "state": "CDMX",
        // usar: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
        "country": "MEX",
        "phone": "{country_code}{phone}"
    },
    // campo opcional aunque para varios proveedores es requerido
    "shipping_address": {
    	"first_name": "Esteban",
      "last_name": "Posada",
      "phone": "{country_code}{phone}",
      "city": "CDMX",
      "state_name": "CDMX",
      // usar: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
      "country": "MEX",
      "zipcode": "03100",
      "address1": "Edgar Allan Poe 102",
    },
    // campo opcional aunque para varios proveedores es requerido
    "billing_address": {
    	"first_name": "Esteban",
      "last_name": "Posada",
      "phone": "{country_code}{phone}"
      "city": "Medellin",
      "state_name": "ANT",
      // usar: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
      "country": "COL",
      "zipcode": "51111",
      "address1": "Carrera 57 #11-57",
    	}
}'

Ejemplo de respuesta exitosa:

{
    "order": {
        "order_id": "915cefaa-9f52-445e-a239-270c9268dc2f",
        "currency": "MXN",
        "total_amount": 30000,
        ...,
        "status": "succeeded", // status of the order
        "from_card": {
            "card_brand": "visa",
            "first_six": "411111",
            "last_four": "1111"
        },
        "payment": {
            "data": {
                ...
                "method_type": "credit_card",
                "processor": "stripe_direct",
                "status": "<payment status>",
                "external_transaction_id": "<transaction_id of the processor>"
                ...
            },
            ...
         },
     }
}

Importante:
1. En la respuesta del API de /purchase viene:
  1. el nombre de pasarela de pagos que procesó la transacción (order.payment.data.processor).
  2. el transaction_id de la pasarela que procesó la transacción (order.payment.data.external_transaction_id)
Operaciones adicionales sobre un pago:
1. Anular (Void) una transacción autorizada: Este API se utiliza para anular (void) una transacción autorizada que aún no ha sido capturada.
  1. Documentación: https://docs.deuna.com/reference/void
2. Reembolsar una transacción previamente capturada: Este API se utiliza para reembolsar total o parcialmente una transacción que ya ha sido capturada.
  1. Documentación: https://docs.deuna.com/reference/refund-v2
  2. DEUNA soporta múltiples reembolsos parciales si el procesador con el que trabaje el comercio lo permite.
3. Capturar una transacción previamente autorizada: Este API se utiliza para capturar total o parcialmente una transacción que ha sido previamente autorizada.
  1. Documentación: https://docs.deuna.com/reference/capture

Webhooks

DEUNA puede mandarle al comercio actualizaciones sobre cambios de estado de una orden (por ejemplo cambio de estado del pago asociado a la orden). Los webhooks son recomendados ya que existen métodos de pagos que son asíncronos y es la manera de comunicarles cuando el pago es aprobado o rechazado. Igualmente, con nuevas tecnologias con 3DS, incluso las transacciones con tarjetas se vuelven asíncronas y es importante que puedas escuchar una vez el usuario concluye la autenticación con su banco y posteriormente recibimos un estado final sobre el pago.

Descubre más información sobre los webhooks: https://docs.deuna.com/docs/que-son-webhooks

Integración: Direct API

Introducción

Pros y Cons de la integración Headless

Ambientes

Autenticación

Idempotencia (Opcional)

Colección de Postman

Diagrama de integración

📘
Este flujo de integración demuestra la creación de usuario, tarjeta y orden y por ende el pago. Recordar que la mayoría de estos pasos son opcionales.

Manejo de usuarios

Almacenamiento de tarjetas para uso futuro

📘
Si tu comercio es PCI compliant, puedes procesar pagos sin previamente haber tenido que tokenizar la tarjeta con DEUNA.

Procesar un pago

📘
El method_type siempre debe ser "credit_card" independiente del tipo de tarjeta

📘
El method_type siempre debe ser "credit_card" independiente del tipo de tarjeta

Webhooks

Introducción

Pros y Cons de la integración Headless

Ambientes

Autenticación

Idempotencia (Opcional)

Colección de Postman

Diagrama de integración

📘Este flujo de integración demuestra la creación de usuario, tarjeta y orden y por ende el pago. Recordar que la mayoría de estos pasos son opcionales.

Manejo de usuarios

Almacenamiento de tarjetas para uso futuro

📘Si tu comercio es PCI compliant, puedes procesar pagos sin previamente haber tenido que tokenizar la tarjeta con DEUNA.

Procesar un pago

📘El method_type siempre debe ser "credit_card" independiente del tipo de tarjeta

📘El method_type siempre debe ser "credit_card" independiente del tipo de tarjeta

Webhooks

📘
Este flujo de integración demuestra la creación de usuario, tarjeta y orden y por ende el pago. Recordar que la mayoría de estos pasos son opcionales.

📘
Si tu comercio es PCI compliant, puedes procesar pagos sin previamente haber tenido que tokenizar la tarjeta con DEUNA.

📘
El method_type siempre debe ser "credit_card" independiente del tipo de tarjeta

📘
El method_type siempre debe ser "credit_card" independiente del tipo de tarjeta