Inicio

Guías

Referencia

Plugins

3D Secure

3D 2.0 Secure es una funcionalidad que permite realizar cargos seguros con tarjetas no presentes, ya que tu cliente deberá autenticar su identidad directamente en el sistema del banco al cual pertenece su tarjeta.  Lo cual permite agilizar aún más el recorrido del cliente y fortalecer la seguridad de las transacciones.

Los siguientes diagramas representan el flujo de un cargo realizado mediante 3D Secure en los escenarios Challenge (solicitar autenticarse al cliente) y Frictionless, en éstos se muestran la responsabilidad de cada uno de los actores involucrados.

Flujo Challenge

Indica que el servicio de autenticación no cuenta con la suficiente información para determinar que el cliente es el dueño de la tarjeta, por lo tanto, le solicita una autenticación mediante un código que le será enviado a algún medio físico o electrónico personal. Con esta característica se evita algún intento de fraude.

Pasos para realizar un flujo Challenge (solicita autenticarse al cliente):

  1. El cliente/cardholder envía sus datos desde la página del comercio.
  2. El comercio envía la información del cliente/cardholder con los datos de monto, número de orden y 3D secure a Openpay para realizar la generación de un nuevo cargo.
  3. Openpay genera un nuevo cargo con los datos recibidos por el comercio e inicia el flujo de 3D Secure solicitando un token al servicio de autenticación mediante los datos del cliente. Ver: Cargo 3D Secure con token.
  4. El servicio de autenticación devuelve el token  generado con la información proporcionada por el cliente.
  5. Openpay almacena la información devuelta por el servicio de autenticación y genera una URL de redirección donde se realizará la validación mediante challenge. Esta URL es devuelta al comercio.
  6. El comercio invoca la URL devuelta por Openpay para realizar el enrolamiento de 3D Secure. En este punto, no se envía información alguna. Ver sección de “Envío de URL de autenticación”. 
  7. Cuando se solicita el enrolamiento, Openpay obtiene los datos del cargo generado previamente, los datos almacenados en el paso 5 y los envía al servicio de autenticación para que sean evaluados.
  8. El servicio de autenticación retorna a Openpay la información de la URL a donde el cliente será redireccionado para realizar un challenge.
  9. Openpay toma los datos almacenados en el paso 5, la URL devuelta por el servicio de autenticación y solicita redireccionar al cliente a la página de challenge.
  10. El servicio de autenticación muestra pantalla de Challenge a cardholder donde se le solicitará un código que le fue enviado mediante email, SMS o desde su banca móvil.
  11. El cliente ingresa el código recibido mediante email, SMS o desde su banca móvil.
  12. Se envía al servicio de autenticación el código ingresado por el cliente para su validación a través de la pantalla que proporcionó.  
  13. El servicio de autenticación valida el código enviado por el cliente y genera la respuesta para Openpay.
  14. Una vez que el cargo fue aprobado/rechazado, Openpay redirecciona al cliente a la URL que se envía como parámetro en el campo redirect_url. Ver sección “Redireccionamiento a URL de respuesta”. Ver: Obtener un cargo con ID



Flujo Frictionless

Indica que el servicio de autenticación cuenta con la suficiente información para identificar que el cliente es el dueño de la tarjeta, por lo tanto, no necesita que este realice una autenticación.

Pasos para realizar el flujo Frictionless:

  1. El cliente/cardholder envía sus datos desde la página del comercio.
  2. El comercio envía la información del cliente/cardholder con los datos de monto, número de orden y 3D secure a Openpay para realizar la generación de un nuevo cargo. Ver: Cargo 3D Secure con token.
  3. Openpay genera un nuevo cargo con los datos recibidos por el comercio e inicia el flujo de 3D Secure solicitando un token al servicio de autenticación mediante los datos del cliente. 
  4. El servicio de autenticación devuelve el token generado con la información proporcionada por el cliente.
  5. Openpay almacena la información devuelta por el servicio de autenticación y genera una URL de redirección donde se realizará la validación mediante frictionless. Esta URL es devuelta al comercio.
  6. El comercio invoca la URL devuelta por Openpay para realizar el enrolamiento de 3D Secure. En este punto, no se envía información alguna. Ver sección de “Envío de URL de autenticación”. 
  7. Cuando se solicita el enrolamiento, Openpay obtiene los datos del cargo generado previamente, los datos almacenados en el paso 5 y los envía al servicio de autenticación para que sean evaluados.
  8. El servicio de autenticación retorna a Openpay que no es necesario que el cliente realice una autenticación de challenge y se completa el pago.
  9. Una vez que el cargo fue aprobado/rechazado, Openpay redirecciona al cliente a la URL que se envía como parámetro en el campo redirect_url. Ver sección “Redireccionamiento a URL de respuesta”. Ver: Obtener un cargo con ID

API Openpay

Consideraciones para el API Openpay

Siempre que se quiera utilizar el API Openpay se deberá contar con la llave privada la cual debe estar vigente y viajar en el Header de la solicitud, este valor sirve para realizar Basic Authentication y así poder consumir el API.

Las llaves se pueden consultar desde Dashboard al ingresar en la parte superior derecha dando clic en el icono de engranaje,entrando a la opción “Mi cuenta” misma en la que encontrarás la sección Llaves de acceso o bien en la opción Credenciales de acceso para el API.

 

Endpoints API Openpay

Endpoints disponibles para la generación de cargos con 3Ds desde la API para los diferentes ambientes para comercio y cliente:

 

Método: POST

 

Sandbox

  • https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/charges

  • https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/ customers/{CUSTOMER_ID}/charges

Producción

  • https://api.openpay.co/v1/{MERCHANT_ID}/charges

  • https://api.openpay.co/v1/{MERCHANT_ID}/ customers/{CUSTOMER_ID}/charges

Códigos de respuesta API

 

Código HTTP

Descripción

200

Ok

400

Bad Request

401

Unauthorized

422

Unprocessable Entity

500

Internal Server Error

503

Service Unavailable

Crear transacción 3D Secure con Token

Para utilizar este servicio se debe tener un Token, el cual puede ser obtenido de las siguientes maneras:

  1. Token de cargo previo. – Si previamente se realizó un intento de cobro a la tarjeta siguiendo la guía de Pagos con tarjeta y el resultado fue un código de error 3005 (Rechazo por riesgo), se puede usar el mismo token creado para 3D Secure.

  2. Creación de nuevo Token. – Si no se cuenta con un token previo, se debe utilizar el servicio de creación de token para crear uno.

Una vez que tengas un token este deberá ser usado la propiedad source_id, descrito en la siguiente tabla que especifica los campos que se pueden enviar en la petición del API:

 

Propiedad

Descripción

method

string(requerido)

Debe contener el valor card para indicar que el cargo se hará de una tarjeta.

source_id

string (requerido, longitud = 45)

ID de la tarjeta guardada o el id del token creado de donde se retirarán los fondos.

amount

numeric (requerido)

Cantidad del cargo. Debe ser una cantidad mayor a cero, con hasta dos dígitos decimales.

currency

string (opcional)

Tipo de moneda del cargo. Se soportan los siguientes tipos de monedas: Pesos Colombianos (COP) y Dólares Americanos (USD)

 

description

string (requerido, longitud = 250)

Una descripción asociada al cargo.

order_id

string (opcional, longitud = 100)

Identificador único del cargo. Debe ser único entre todas las transacciones.

device_session_id

string (requerido, longitud = 32)

Identificador del dispositivo generado con la herramienta antifraudes

capture

boolean (opcional, default = true)

Indica si el cargo se hace o no inmediatamente, cuando el valor es false el cargo se maneja como una autorización (o preautorización) y solo se reserva el monto para ser confirmado o cancelado en una segunda llamada.

customer

Objeto (Opcional)

Información del cliente al que se le realiza el cargo. Ver objeto Customer.

Se puede ocupar los mismos parámetros usados en la creación de un cliente pero no se creará una cuenta al cliente.

Nota: Este parámetro solo se puede utilizar creando el cargo a nivel comercio

Si desea crear un cliente y llevar un historial de sus cargos consulte cómo crear un cliente y realice el cargo a nivel cliente.

payment_plan

objeto (opcional)

Datos del plan de meses sin intereses que se desea utilizar en el cargo. Ver Objeto PaymentPlan.

metadata

list(key, value) (opcional)

Listado de campos personalizados de antifraude, estos campos deben de apegarse a las reglas para creación de campos personalizados de antifraude

send_email

boolean (opcional)

Usado para cargos de tipo redirect. Indica si se desea enviar un email que direccione al formulario de pago de Openpay.

redirect_url

string (requerido)

Usado para cargos de tipo redirect. Indica la url a la que redireccionar despues de una transaccion exitosa en el fomulario de pago de openpay.

Nota: Este parámetro solo se puede utilizar si se especifica el manejo de 3D Secure.

use_3d_secure

string (opcional)

Se debe especificar este parámetro en true para manejar 3D Secure.

iva

numeric (opcional)

Monto de iva . Debe ser una cantidad igual o mayor a cero.

Ejemplo de petición:

 

Header: Basic {llave privada vigente}

 

{

   “method”: “card”,

   “amount”: 832,

   “currency”: “COP”,

   “description”: “Prueba con 3DS”,

   “order_id”: “orden123456789”,

   “redirect_url”: “https://www.openpay.mx/index.html”,

   “device_session_id”: “device12234567s8”,

   “use_3d_secure”: “true”,

   “confirm”:“true”,

   “source_id”: “k81aoifelkna2efguzle”,

   “customer”: {

       “name”: “Alonso”,

       “last_name”: “Test”,

       “phone_number”: “8884444444”,

       “email”: “test2@openpay.mx”

   }

 

Envío de URL de autenticación

 

La respuesta a la petición de creación de cargo será un JSON con la información de la transacción a pagar por el usuario. Se debe poner especial atención en los siguientes parámetros: 

  • id – ID único de la transacción creada, debe ser almacenado ya que será por medio de este ID que se envíe la respuesta una vez que el usuario realice la autenticación 3D Secure. 

  • payment_method.url – URL a donde se debe redirigir al usuario para iniciar el proceso.

Ejemplo de la respuesta:

 

{

   “id”: “trjd5i68lurpekpg15hb”,

   “authorization”: “000000”,

   “operation_type”: “in”,

   “transaction_type”: “charge”,

   “status”: “charge_pending”,

   “conciliated”: true,

   “iva”: “0”,

   “creation_date”: “2024-04-01T17:50:32-06:00”,

   “operation_date”: “2024-04-01T17:50:32-06:00”,

   “description”: “Prueba con 3DS”,

   “error_message”: null,

   “order_id”: “orden123456789”,

   “card”: {

       “type”: “credit”,

       “brand”: “visa”,

       “address”: {

           “line1”: “Av 5 de Febrero”,

           “line2”: “Roble 207”,

           “line3”: “Col Carrillo”,

           “state”: “Colombia”,

           “city”: “Colombia”,

           “postal_code”: “76900”,

           “country_code”: “CO”

       },

       “card_number”: “400558XXXXXX1886”,

       “holder_name”: “Hectorito Alonso Test”,

       “expiration_year”: “27”,

       “expiration_month”: “01”,

       “allows_charges”: true,

       “allows_payouts”: false,

       “bank_name”: “BANXICO”,

       “bank_code”: “001”

   },

   “gateway_card_present”: “CREDIBANCO”,

   “payment_method”: {

       “type”: “redirect”,

       “url”: “https://dev-api.openpay.co/v1/m1c3xff4vje0ratdi93g/charges/trjd5i68lurpekpg15hb/redirect/”

   },

   “amount”: 832.00,

   “currency”: “COP”,

   “customer”: {

       “name”: “Alonso”,

       “last_name”: “Test”,

       “email”: “test2@openpay.mx”,

       “phone_number”: “8884444444”,

       “address”: null,

       “creation_date”: “2024-04-01T17:50:31-06:00”,

       “external_id”: null,

       “clabe”: null

   },

   “method”: “card”

}

 

La URL contenida en la propiedad payment_method.url inicia el proceso, cuando el servicio de autenticación no logra autenticar al cliente se realiza el flujo Challenge y le solicita ingresar un código en la siguiente pantalla.

 

 

 

Cuando el cliente es autenticado exitosamente se realiza el flujo Frictionless, es decir que este paso no se realiza.

Redireccionamiento a URL de respuesta

 

Una vez completa la autenticación del usuario en el sistema 3D Secure y recibida la respuesta en Openpay, se re-direccionará al usuario a la URL definida en el paso 2 (redirect_url) usando el ID de la transacción que se envió en el paso 5. Ejemplo: http://www.openpay.co/index.html?id=treqwygvw0hrjuvwbsf5

 

Notas:

  • Puedes simular diferentes resultados usando las tarjetas de Pruebas

  • Implementa las Notificaciones para conocer el estado de los pagos en tiempo real

Taquilla con 3D Secure

Formulario que permite la generación de una URL de pago que puede ser compartida con los clientes a través de  email, redes sociales o WhatsApp, permite especificar varios tipos de documentos de identificación del cliente.

Pago con Taquilla

El comercio ingresa a la URL que se le configuró el cual continente su id de comercio.

URL de taquilla para los diferentes ambientes:

Método: POST

  • Sandbox

https://sandbox-api.openpay.co/v1/{merchant_id}/open-checkout

  • Producción

https://api.openpay.co/v1/{merchant_id}/open-checkout

 

Al abrir la URL se muestra el formulario principal para ingresar los datos del pago. Una vez capturados seleccionamos “Continuar”.

 

 

 

El sistema muestra un mensaje de confirmación de los datos capturados, seleccionamos “Enviar”.

 

Se muestra la pantalla solicitud de Pago, seleccionamos la opción “Pago con tarjeta”.

 

 

El sistema muestra el formulario para capturar los datos de tarjeta, una vez ingresados seleccionamos “Realizar pago”.

 

 

El servicio de autenticación valida los datos de la operación y al no lograr autenticar al cliente se realiza el flujo Challenge, es decir se solicita el ingreso de un código. Lo ingresamos y seleccionamos “Submit”.

 

 

 

Nota: cuando el servicio de autenticación autentica exitosamente al cliente este paso no se realiza, es decir se vuelve un flujo Frictionless,  la transacción es enviada para su autorización.

 

Finalmente se valida que el código ingresado sea correcto y se manda procesar la transacción, en este caso la transacción fue aprobada exitosamente.

 

 

 

 

Recaudo con 3D Secure

Funcionalidad que permite el recaudo de facturas de manera fácil, rápida y segura mediante la generación de una URL que puede ser compartida con los clientes a través de  email, redes sociales o WhatsApp.

Permite la configuración personalizada de los pagos según las necesidades de los comercios:

  • Pago de facturas de productos y/o servicios

  • Anticipos o pagos parciales

  • Recaudo de cartera

  • Pago de membresías

 

Pago de factura

Una vez que el cliente inició sesión mediante la URL del proyecto podrá visualizar sus facturas pendientes.

 

En la pantalla principal selecciona la factura a pagar y la opción “Continuar”.

 

 

 

El sistema solicita el ingreso de un correo electrónico, posteriormente seleccionamos “Continuar”.

 

Seleccionamos el método de pago Tarjeta bancaria y Continuar.

 

El sistema muestra el formulario para capturar los datos de la tarjeta, una vez realizado seleccionamos “Pagar”.

 


El sistema de autenticación valida los datos de la operación y al no lograr autenticar al cliente se realiza el flujo
Challenge, es decir se solicita el ingreso de un código.

 

 

Nota: cuando el sistema de autenticación autentica exitosamente al cliente este paso no se realiza, es decir se vuelve un flujo Frictionless,  la transacción es enviada al Procesador para su autorización.

 

Finalmente se valida que el código ingresado sea correcto y se manda procesar la transacción, si todo fue correcto se muestra la confirmación del pago.

 

 

Tarjetas de prueba para realizar transacciones Frictionless y Challenge:

No. tarjeta

Mes

Año

CVV

Marca

Flujo

Resultado

4005580000050508

01

27

123

VISA

Challenge

ECI05 – Authentication successful

5204740000001002

01

27

123

MASTERCARD

Challenge

ECI02 –  Authentication successful

4005580000051886

01

27

123

VISA

Frictionless

ECI05 -Authentication successful

5204740000001234

01

27

123

MASTERCARD

Frictionless

ECI02 –  Authentication successful

4005580000051811

01

27

123

VISA

Error Challenge

ECI07 – Authentication failed

5204740000001010

01

27

123

MASTERCARD

Error Challenge

ECI00 – Authentication failed

4005580000051829

01

27

123

VISA

Error Frictionless

ECI07 – Authentication failed

5204740000001028

01

27

123

MASTERCARD

Error Frictionless

ECI00 – Authentication failed


Códigos de error servicio de autenticación 3D Secure

Posibles códigos de respuesta enviados por el servicio de autenticación 3DS al realizar la validación del cliente.

 

Código

Descripción

Marca de aceptación

05

Autenticación 3Ds exitosa

VISA / AMEX

06

No se pudo completar la autenticación

VISA / AMEX

07

No se pudo completar la autenticación / Banco emisor no participa en 3Ds

VISA / AMEX

02

Autenticación 3Ds exitosa

MC

01

No se pudo completar la autenticación

MC

00

No se pudo completar la autenticación / Banco emisor no participa en 3Ds

MC