Activar 3DS - Direct API
En esta sección se describe cómo realizar la integración para utilizar 3D Secure 2 a través de Direct API. Es aconsejable que previamente se haya leído y/o implementado la guía para crear un cargo único.
Diagrama de secuencia
Cómo integrar una orden con 3DS2
Para integrar una orden con 3DS2 es necesario realizar los siguientes pasos:
1. Crear orden con modalidad 3DS2
Para autenticar tus pagos con 3DS2 en alguna de sus modalidades descriptas aquí, deberás incluir dos nuevos atributos al payload de la creación de una orden: three_ds_mode y return_url, donde:
| Parámetro | Descripción | Tipo | Requerido |
|---|---|---|---|
| three_ds_mode | Indica que queremos crear una orden por 3DS2 y su modalidad de uso. | string | Sí |
| return_url | Indica el callback de redirección al finalizar el flujo de 3DS2. | string | Sí |
-H "Accept: application/vnd.conekta-v2.1.0+json" \
-H "Content-type: application/json" \
-u key_YOUR_PRIVATE_API_KEY: \
-X POST -d '{
"currency": "MXN",
"three_ds_mode": "smart",
"return_url": "https://my-website.com",
"line_items": [{
"name": "Nombre del Producto o Servicio",
"unit_price": 2000,
"quantity": 1
}],
"customer_info": {
"customer_id": "cus_xxxxxxxxxxxx"
},
"metadata":{
"datos_extra": "1234"
},
"charges":[{
"payment_method": {
"type": "card",
"payment_source_id": "src_xxxxxxxxxxxx"
}
}]
}’https://api.conekta.io/orders
{
"livemode": true,
"amount": 2000,
"currency": "MXN",
"payment_status": "pending_payment",
"amount_refunded": 0,
"split_payment": false,
"customer_info": {
"email": "[email protected]",
"phone": "+5215555555555",
"name": "Test",
"corporate": false,
"customer_id": "cus_xxxxxxxxxxxx",
"object": "customer_info",
"customer_custom_reference": null
},
"fiscal_entity": null,
"next_action": {
"redirect_to_url": {
"url": "https://3ds-pay.conekta.com/88f347d6-a767-495f-a5ef-b44bfd888dd2",
"return_url": "https://www.my-website.com"
},
"type": "redirect_to_url"
},
"object": "order",
"id": "ord_xxxxxxxxxxxx",
"metadata": {},
"is_refundable": false,
"created_at": 1686579964,
"updated_at": 1686579964,
"line_items": {
"object": "list",
"has_more": false,
"total": 1,
"data": [
{
"name": "Nombre del Producto o Servicio",
"description": null,
"unit_price": 2000,
"quantity": 1,
"sku": null,
"tags": null,
"brand": null,
"type": null,
"object": "line_item",
"id": "line_item_2u2gCyvhfyytrUrhs",
"parent_id": "ord_2u2gCyvhfyytrUrhv",
"metadata": {},
"antifraud_info": {}
}
]
},
"shipping_lines": null,
"tax_lines": null,
"discount_lines": null,
"charges": {
"object": "list",
"has_more": false,
"total": 1,
"data": [
{
"id": "64872afc5f8aa7001b14625a",
"livemode": true,
"created_at": 1686579964,
"currency": "MXN",
"failure_code": null,
"failure_message": null,
"monthly_installments": null,
"device_fingerprint": null,
"channel": {
"segment": "Checkout",
"checkout_request_id": "88f347d6-a767-495f-a5ef-b44bfd888ce2",
"checkout_request_type": "HostedPayment",
"id": "channel_2u2gCyvhfyytrUri8"
},
"payment_method": {
"name": "Test User",
"exp_month": "12",
"exp_year": "28",
"auth_code": null,
"object": "card_payment",
"type": "credit",
"normalized_device_fingerprint": null,
"last4": "9999",
"brand": "mastercard",
"issuer": "test_card",
"account_type": "STANDARD",
"country": "MY",
"fraud_score": null,
"fraud_indicators": [],
"token_id": "tok_2u2fw6tvpWMsZvSzq"
},
"object": "charge",
"description": "Payment from order",
"is_refundable": false,
"reference_id": null,
"status": "pending_payment",
"amount": 2000,
"paid_at": null,
"customer_id": "cus_2u2fzGiwU9XQHAhkk",
"order_id": "ord_2u2gCyvhfyytrUrhv",
"customer_custom_reference": null,
"refunds": null
}
]
}
}
2. Presentar el flujo 3DS2
La respuesta de las creaciones de ordenes con 3DS2 incorporan el objeto next_action, que contiene los siguientes atributos que te guiarán para continuar el flujo:
| Atributo | Valor | Descripción |
|---|---|---|
| type | redirect_to_url | Indica que la siguiente acción que se debe realizar es invocar a la url establecida en el siguiente atributo. |
| redirecto_to_url.url | https://3ds-pay.conekta.com/{id} | Indica la url del componente de Conekta para autenticar el flujo por 3DS2. |
| redirecto_to_url.return_url | https://my-website.com | Indica la url a la que retornará el flujo de 3DS2 al finalizar, cuando la integración es redireccionada. |
En caso de utilizar la modalidad smart y Conekta no considere que el cargo represente un riesgo para el comercio, el pago continuará su curso habitual y no existirá el atributo next_action.
2.1 - Tipos de Integración
Una vez obtenida la respuesta de la creación de la orden, obtendrás la URL de nuestro componente de 3DS2 en el atributo next_action.redirecto_to_url.url, el cual podrás integrarlo de 2 formas:
2.1.1 - Integración Embebida [Recomendada]
En este tipo de integración deberás renderizar la url de redirección de manera embebida utilizando un iFrame, agregando el query-param source como se visualiza en el siguiente ejemplo:
<iframe id="iframe" src={`${url}?source=embbeded`}></iframe>
Importante:
Es aconsejable que la url de redirección se muestre en un modal con al menos 500px de ancho y 600px de alto.
- NOTA: Es altamente aconsejable que la URL utilizada para la redirección sea absoluta.
Cuando el flujo de autenticación finalice nuestro componente de 3DS2 emitirá un evento el cual podrás utilizar para validar si el flujo finalizó correctamente. Este evento lo puedes capturar de la siguiente forma:
const ENV_URL = 'https://3ds-pay.conekta.com';
window.addEventListener('message', (event) => {
if (event.origin === ENV_URL) {
const { checkout_id, order_id, payment_status, error } = event.data;
if(error || payment_status !== 'paid'){
console.log("Ha ocurrido un error");
} else {
console.log('data', event.data);
}
}
});
Nota: Es necesario que valides el origen del mensaje para identificar la respuesta.
2.1.2 - Integración Redireccionada
En este tipo de integración deberás renderizar la url de redirección en una nueva ventana/pestaña del navegador.
Cuando el flujo de autenticación finalice Conekta hará una redirección a la URL indicada en el atributo return_url de la creación del cargo incorporando el query-param payment_status con el resultado: aprobado o rechazado, devolviendo el control del flujo de pago al comercio.
3 - Consultar estado de la orden
En ambos tipos de integración (redireccionada o embebida) recomendamos que se realice una consulta al estado de la orden o se valide el mismo por notificación vÍa webhook.
Importante:
No te olvides de consultar al estado de la cargo o validar la notificación vÍa webhook.
Updated 5 days ago