Documentación

Implementación de 3DS

Suggest Edits

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.

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}}"
}
'

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.

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

Existen 2 modalidades para abordar el 3D Secure global:

  • Modal: El reto del 3DS se mostrará en una ventana modal, lo cual permitirá al usuaria a finalizar su proceso de compra dentro del checkout de la página del comercio.
  • Redireccionamiento: El reto se mostrará en una página externa (de Orkestapay) a la cual se deberá de redireccionar al usuario para que finalice el pago.

Para confirmar que el tipo de 3D Secure es global, se verifica que en la respuesta del servicio de /payments contenga el objeto user_action_required tenga una propiedad type con el valor THREE_D_SECURE_AUTHENTICATION.

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",
            "authentication_redirect_url": "https://checkout.dev.orkestapay.com/3ds/global?merchant_id=mch_9608f49086bf44ea8a02f0c3f5d35383&public_key=pk_test_bjc14uzla1m941dgy74psmeaujayc6rx&merchant_provider_id=mpv_100f2f97b2da4ee6bc8828504571a76c&payment_id=pay_7d0114f013924c0c8d23180922ad7a5f&order_id=ord_edfa827d57794f4487a97d99b9089b17&is_sandbox=false"
        }
    },
    "transactions": [
        {
            "type": "REGISTER",
            "transaction_id": "tds_1dcb08fcacbb4a888461539ecc49ec63",
            "status": "SUCCESS",
            "amount": 16100,
            "code": "APPROVED",
            "message": "Approved or completed successfully",
            "description": "ord_edfa827d57794f4487a97d99b9089b17",
            "provider": {
                "merchant_provider_id": "mpv_100f2f97b2da4ee6bc8828504571a76c",
                "name": "cyber_source",
                "code": "",
                "message": ""
            },
            "created_at": "1731010722448"
        }
    ],
    "device_session_id": "7e4e4bdd-6eaa-4470-979c-1fe8fe02b0d2",
    "created_at": "1731010721909",
    "updated_at": "1731010721909"
}

3D Secure global con modal

El objeto user_action_required de la respuesta antes mencionada, vendrá un 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.

Para abrir la ventana modal, es necesario ejecutar 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.

A continuación un ejemplo muy básico de la implementación desde el frontend de la aplicació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).


📘

CDN OrkestaPay

Para más información sobre el CDN de OrkestaPay, puedes revisar nuestra documentación de Inicialización.


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 global con redireccionamiento

En el objeto user_action_required que viene en la respuesta del servicio de /payments, vendrá un objeto three_d_secure_authentication que contiene un la URL a la cual hay que redireccionar al usuario authentication_redirect_url .

Una vez completado o cancelado el reto del 3DS, el usuario será redireccionado a las URL’s que indicaste durante la llamada al servicio de /payments .

IMPORTANTE

En la modalidad de redireccionamiento, no es necesario que hagas el llamado al servicio de completado.


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.

Updated 7 days ago