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

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

📘

Documentación

Visita nuestra documentación del API: https://docs.orkestapay.com/reference/create-payment


3D Secure

Existen 2 modalidades para abordar el 3D Secure:

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

Sí el estatus de la respuesta tiene el valor de PAYMENT_ACTION_REQUIRED, entonces requiere que se ejecute el reto de 3D Secure.

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

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

📘

Documentación

Visita nuestra documentación del API: https://docs.orkestapay.com/reference/create-payment


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

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 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,
});

📘

CDN OrkestaPay

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


NOTA: El reto (challenge) de la implementación con 3DS, se llevará a cabo en una ventana emergente (ventana modal). Una vez se haya resuelto la verificación de 3D Secure, es necesario completar el pago (se aborda más adelante en el artículo).


Completar pago para 3DS con modal

Una vez que el challenge del 3DS con modal 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 '
{}
'

📘

Documentación

Visita nuestra documentación del API: https://docs.orkestapay.com/reference/complete-payment


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

📘

Documentación

Visita nuestra documentación del API: https://docs.orkestapay.com/reference/complete-payment


3D Secure 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"
}

📘

Documentación

Visita nuestra documentación del API: https://docs.orkestapay.com/reference/create-payment


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 about 1 month ago