Implementación de 3DS

Integración de 3DS 

Para realizar la integración de 3DS con el enfoque de Pago Directo, es decir, sin ser redireccionado al checkout de OrkestaPay, es necesario seguir los siguientes pasos:

1. Integración de Pago Directo

2. Integración de flujo con 3DS

3. Completar pago para 3DS global

Precondiciones

• Contar con una ruta de orquestamiento con un proveedor de 3DS configurado.

• Tener previamente inicializado el CDN de OrkestaPay en el frontend.

Integración de Pago Directo

Seguir la guía para la Integración de Pago, sin embargo en el paso número 4 en donde se registra el pago, hay que enviar el objeto redirection_url con las URL's de redireccionamiento para los escenarios de autenticación exitosa o cancelada del 3DS.

Sí el estatus de la respuesta tiene el valor de PAYMENT_ACTION_REQUIRED, entonces requiere que se ejecute el reto de 3D Secure, ya sea global o específico.

curl --request POST \
     --url https://api.sand.orkestapay.com/v1/payments \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'Idempotency-Key: adffaf7a3141474555d988fbb5e43e85' \
     --header 'Authorization: Bearer REPLACE_WITH_YOUR_ACCESS_TOKEN' \
     --data '
{
  "payment_source": {
     "type" : "CARD",
     "payment_method_id": "{{REPLACE_WITH_CARD_TOKEN}}",
     "settings": {
       "card": {
         "capture":true
       },
       "redirection_url": {
         "completed_redirect_url": "https://tu.dominio.com/status?result=COMPLETED",
         "canceled_redirect_url": "https://tu.dominio.com/status?result=CANCELED"
       }
     }
   },
   "device_session_id": "{{REPLACE_WITH_DEVICE_SESSION_ID}}",
   "order_id": "{{REPLACE_WITH_ORDER_ID}}"
}
'

NOTA: El tipo de 3DS dependerá de la configuración de procesador(es) de pago que tengas habilitado(s) en tu ruta de orquestamiento.

3D Secure global

Para validar que el tipo de 3D Secure es global, se verifica que en el objeto user_action_required tenga una propiedad type con el valor THREE_D_SECURE_AUTHENTICATION, adicional a esto, dentro del mismo objeto user_action_required vendrá otro objeto three_d_secure_authentication que contiene un ID en la propiedad merchant_provider_id, dicho ID, junto al order_id y al payment_id, serán usados para lanzar la modal que muestra el reto de 3D Secure global. 

A continuación se muestra un ejemplo de la respuesta de que el pago requiere validar el 3D Secure global:

{
    "payment_id": "pay_f30a6fb904bc46d5978c716895651705",
    "order_id": "ord_a850ee7aba994b05b6eca01a57d62cbf",
    "status": "PAYMENT_ACTION_REQUIRED",
    "payment_source": {
        "type": "CARD",
        "settings": {
            "card": {
                "capture": true
            },
            "redirection_url": {
                "completed_redirect_url": "https://tu.dominio.com/status?result=COMPLETED",
                "canceled_redirect_url": "https://tu.dominio.com/status?result=CANCELED"
            }
        },
        "payment_method_id": "pym_20e99063448344bc9e84a9cd9cd1b5d4"
    },
    "amount": {
        "currency": "MXN"
    },
    "user_action_required": {
        "type": "THREE_D_SECURE_AUTHENTICATION",
        "three_d_secure_authentication": {
            "merchant_provider_id": "mpv_b7609d98330e4606931ba267424d0e91"
        }
    }
}

Para levantar la modal, se ejecuta un método del CDN de OrkestaPay que devuelve una promesa. Dicha promesa será resuelta una vez que el proveedor de 3D Secure Global haya evaluado la transacción.

// Inicializar CDN
const merchant_id = '{YOUR_MERCHANT_ID}';
const public_key = '{YOUR_PUBLIC_KEY}';
const orkestapay = initOrkestaPay({ merchant_id, public_key });

// Modal 3DS
const results = await orkestaPay.startModal3DSecure({
  merchant_provider_id,
  payment_id,
  order_id,
});

NOTA: El reto (challenge) de la implementación con 3DS global, se llevará a cabo en una ventana emergente (ventana modal).

Una vez se haya resuelto la verificación de 3D Secure global, es necesario completar el pago (se aborda más adelante en el artículo).

Completar pago para 3DS global

Una vez que el challenge del 3DS global ha sido completado exitosamente, hay que llamar un servicio que permita completar el pago.

Petición hacia el servicio

Se deberá llamar al servicio de "completar pago" y como parte de la petición se deberá de enviar el encabezado Idempotency-Key y Authorization, ambas cabeceras son mencionadas en la guía de Integración de Pago.

curl --request POST \
     --url https://api.sand.orkestapay.com/v1/payments/{PAYMENT_ID}/complete \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'Idempotency-Key: adffaf7a3141474555d988fbb5e43e85' \
     --header 'Authorization: Bearer REPLACE_WITH_YOUR_ACCESS_TOKEN' \
     --data '
{}
'

Respuesta del servicio

Al completar un pago, se regresará la siguiente información.

{
    "type": "COMPLETE",
    "transaction_id": "ctx_68654481e4a04e30bee02bfecd4e8c72",
    "status": "COMPLETED",
    "amount": 1403.6,
    "code": "APPROVED",
    "message": "Transaction approved",
    "description": "mch_db68ab57e28a42b7bad618f1b364f958",
    "provider": {
        "name": "Stripe",
        "provider_transaction_id": "ctx_68654481e4a04e30bee02bfecd4e8c72",
        "code": "000",
        "message": "Transaction approved"
    },
    "authorization_code": "pi_3PDdFPGYqhDa3Ul63cpDZVZ2",
    "created_at": "1715046917129"
}

3D Secure específico

Para validar que el tipo de 3D Secure es específico, se verifica que en el objeto user_action_required tenga una propiedad type con el valor THREE_D_SECURE_AUTHENTICATION, adicional a esto, dentro del mismo objeto user_action_required vendrá otro objeto three_d_secure_specific que contiene una URL en la propiedad three_ds_redirect_url, en este caso, se debe redireccionar a dicha URL para realizar el reto de 3D Secure específico, una vez superado/fallado el reto, éste redireccionará a la URL correspondiente definidas al momento de registrar el pago. 

A continuación se muestra un ejemplo de la respuesta de que el pago requiere validar el 3D Secure específico:

{
    "payment_id": "pay_7fee268029bd402cbcbd6215d48c2cdb",
    "order_id": "ord_80b6a1701f7c402fab89a466a852c952",
    "status": "PAYMENT_ACTION_REQUIRED",
    "payment_source": {
        "type": "CARD",
        "settings": {
            "card": {
                "capture": true
            },
            "redirection_url": {
                "completed_redirect_url": "https://sven.biz",
                "canceled_redirect_url": "http://stuart.org"
            }
        },
        "payment_method_id": "pym_d82f63059792493dac024464858c2fa4"
    },
    "amount": {
        "currency": "MXN"
    },
    "user_action_required": {
        "type": "THREE_D_SECURE_SPECIFIC",
        "three_d_secure_specific": {
            "three_ds_redirect_url": "https://api.dev.orkestapay.com/public/v1/redirect/tds_6661c1d7d61a41cd80fbc383e25e7c32"
        }
    },
    "transactions": [
        {
            "type": "REGISTER",
            "transaction_id": "ctx_815509c8bb2449eba9301593094cb1ad",
            "status": "SUCCESS",
            "amount": 995.00,
            "code": "APPROVED",
            "message": "Approved or completed successfully",
            "description": "ord_80b6a1701f7c402fab89a466a852c952",
            "provider": {
                "merchant_provider_id": "mpv_b6de55faf5734859a3ef7842fb99e5cf",
                "name": "openpay",
                "provider_transaction_id": "trnsmosizgcxpuex2ihv",
                "code": "000",
                "message": ""
            },
            "authorization_code": "trnsmosizgcxpuex2ihv",
            "created_at": "1715118387984"
        }
    ],
    "created_at": "1715118384684",
    "updated_at": "1715118384684"
}

NOTA: El reto (challenge) de la implementación con 3DS específico, se llevará a cabo en una URL propia del procesador de pago, a la cual se le deberá de redireccionar al usuario.

Una vez se haya completado/fallado el reto del proveedor de 3D Secure específico, se recomienda consultar el pago realizado mediante su payment_id para confirmar su estatus.