Documentación

Headless: Payments and Fraud

Suggest Edits

Introducción

Esta sección te explica paso a paso como poder integrar en tu comercio via API (headless) la solucion de payments and fraud orchestration de DEUNA. Nuestro que DEUNA son organizados alrededor de REST, es decir, son orientados sobre recuersos, reciben y retornan JSON responses, al igual que usan lo códigos standard de respuesta de HTTP al igual que los estandares en autenticacion 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:

  1. Staging: tambien conocido como STG o Sandbox. Este es el ambiente que se usa para realizar pruebas. Este ambiente contiene las conecciones a los diferentes provedores de pagos y fraude apuntado tambien a sus ambientes de prueba, por ende, las pruebas deben realizarse con datos de pruebas (tarjetas, etc.) que disponga cada proveedor en sus ambientes de prueba.
    1. URL: https://api.stg.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.
  2. 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 para permitir transaccionar, almacenar tarjetas a nombre de un cliente/usuario, usamos un Token de autenticación tipo JWT con expiración para hacer operaciones a nombre del usuario.

Cuando crees tu cuenta de staging de DEUNA, desde el ADMIN o por ayuda a soporte, puedes obtener tu API Key publica y privada. Estas pueden ser eliminadas en cualquier momento si así lo desean y multiples mas se pueden crear.

Idempotency

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.

Diagrama de integración

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

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:

  1. Creación de usuarios:

    1. https://docs.deuna.com/v2.0/reference/users-register

    2. Ejemplo de como crear un usuario:

      curl --location 'https://<base url deuna env>/users/register' \
--header 'x-api-key: <merchant-api-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "[email protected]",
    "first_name": "Esteban",
    "last_name": "Posada",
    "phone": "444-769-2491",
    "identity_document": "1722146485",
    "merchant_id": "944659cf-a0d6-441e-a238-9f308a4a6e8f"
}'

    3. Ejemplo de respuesta exitosa:

      {
    "token": "<user token (JWT token usado para autenticación)>",
    "user_id": "<user ID v4 UUID>"
}

  2. Operaciones adicionales sobre usuarios DEUNA:

    1. Eliminar un usuario: https://docs.deuna.com/v2.0/reference/delete-users-userid
    2. Obtener un usuario: https://docs.deuna.com/reference/get-users-me

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.

Pasos para el manejo de tarjetas

  1. Crear una tarjeta y asociarla a un usuario:

    1. https://docs.deuna.com/reference/post-users-user_id-cards

    2. Para probar crear pagos en el ambiente de STAGING de DEUNA debes usar las tarjetas de prueba de los procesadores de pago que tienes configuradas en DEUNA.

    3. Ejemplo de como crear una tarjeta:

      curl --location 'https://<base url deuna env>/users/<deuna-user-id>/cards' \
--header 'Authorization: Bearer <user-auth-token>' \
--header 'Content-Type: application/json' \
--data '{
    "expiry_month": "11",
    "expiry_year": "2025",
    "card_holder": "Esteban Posada",
    "card_holder_dni": "185396924",
    "card_number": "4111111111111111",
    "card_cvv": "123",
    "address1": "Vergara 548",
    "zip": "001100",
    "city": "Cuahutemoc",
    "state": "CDMX",
    "country": "MEX",
    "phone": "12345755",
    // Opcional y si no se manda, se respeta la configuracion global a nivel comercio
    // https://docs.deuna.com/docs/verificaci%C3%B3n-de-tarjetas
    "card_verification_config": {
        "invoke_card_verification": true or false
    }
}'

    4. Ejemplo de respuesta exitosa:

      {
    "data": {
        "id": "3d095a95-7da4-4e62-a57c-8c9c4d7dd9db",
        "user_id": "930fedbb-a07c-44db-8514-ecf73fdee1a7",
        "card_holder": "Esteban Posada",
        "card_holder_dni": "185396924",
        "company": "visa",
        "last_four": "1111",
        "first_six": "411111",
        "expiration_date": "11/25",
        "is_valid": true,
        "verified_by": "card_verifier",
        "verified_at": "0001-01-01T00:00:00Z",
        "created_at": "2023-07-06T15:48:13.796043849Z",
        "updated_at": "2023-07-06T15:48:13.796056921Z",
        "deleted_at": null
    }
}

      Algunas notas:

      • Como se puede ver en el ejemplo de la respuesta, los campos is_valid, verified_by, verify_at (UTC) son usados cuando el comercio tiene activada la funcionalidad de verificación de tarjetas que puedes conocer más acá: https://docs.deuna.com/docs/verificación-de-tarjetas
      • El campo “id” es el token creado por DEUNA para identificar futuras compras con este misma tarjeta

  2. Operaciones adicionales sobre tarjetas:

    1. Obtener la lista de tarjetas de un usuario: https://docs.deuna.com/reference/get-user-cards
    2. Eliminar una tarjeta existente: https://docs.deuna.com/reference/delete-users-user_id-cards-card_id
    3. Obtener una tarjeta específica: https://docs.deuna.com/reference/get-user_id-cards

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.

Como procesar un pago

  1. 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/order_token

    2. Ejemplo básico de como crear una orden:

      curl --location 'https://<base url deuna env>/merchants/orders' \
--header 'x-api-key: <merchant-api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "order": {
        "order_id": "<el id de la orden en tu comercio>",
        "currency": "MXN", // 3 caracteres bajo la ISO 3166-1 alpha-3
        "items_total_amount": 3000, // los montos representados en centavos
        "sub_total": 3000,
        "total_amount": 3000,
        "store_code": "all",
        "metadata": {
            ... key/value pair of extra info
        },
				"webhook_urls": {
            "notify_order": "<your endpoint to send you order status notifications>"
        }
    },
    "order_type": "DEUNA_NOW"
}'
      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 tokenizar 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": "DEUNA_NOW",
    "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": {
            ...
        },
        ...
    },
}

  2. Realiza el pago sobre la orden creada: con una orden ya creada, puedes crear el pago.

    1. https://docs.deuna.com/reference/purchase

    2. 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.

    3. Para probar crear pagos en el ambiente de STAGING de DEUNA debes usar las tarjetas de prueba de los procesadores de pago que tienes configuradas en DEUNA.

    4. DEUNA permite realizar un purchase usando una tarjeta previamente guardada 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:

        1. Enviar el token de la tarjeta en el campo “card_id” y el campos de “credit_card” lo puedes enviar vacío (”credit_card”: {}).

        2. 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”}

        3. 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
	    "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",
		}
	}'

        4. 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:

        1. Enviar el campo credit_card .

        2. Ejemplo básico de como crear un pago:

          curl --location 'https://api.stg.deuna.io/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",
		}
}'

        3. 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>"
                ...
            },
            ...
         },
     }
}

    5. 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)

    6. 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-order
        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/qué-es-un-webhook

Updated 12 months ago