Crear cuenta

1.- CREAR CUENTA EN OPENPAY

  1. Ir al sitio web de Openpay y crear cuenta.

Nota: Para hacer pruebas, crear la cuenta en ambiente Sandbox. Para la operación real, pide tu pase a Producción 

  1. Entrar al Dashboard con los datos de acceso creados.
  2. En barra superior, ir al icono de engrane y hacer click en la opción Credenciales de API

  1. Obtener ID (identificador del comercio), Llave privada y Llave pública (esta información se usará más adelante).

Nota:  Las credenciales de API son diferentes en cada ambiente. Debe guardar estos datos por separado y no confundirlos para que los ambientes de Sandbox y Producción funcionen correctamente.

 

VTEX | VTEX IO

VTEX | VTEX IO

VTEX IO es una plataforma de desarrollo creada por VTEX, enfocada en facilitar la creación y gestión de aplicaciones para el comercio electrónico. Permite a los desarrolladores construir, desplegar y escalar aplicaciones de manera eficiente, integrando diferentes servicios y microservicios.

Instalar aplicación de Openpay con VTEX IO CLI

La aplicación de Openpay(openpay-pixel-app) se utiliza como apoyo para métodos de pagos alternativos, nos proporciona un botón para mostrar e imprimir la referencia de pago una vez finalizado el pedido.

Nota: antes de instalar la aplicación, asegúrese de que esté en la cuenta y workspace deseado, puede verificarlo con el siguiente comando:

$ vtex whoami

Para más información acerca de VTEX IO CLI puede visitar su documentación aqui.

1. Para Instalar la aplicación de Openpay en nuestro comercio vtex debera escribir el siguiente comando:

$ vtex install opepay.openpay-pixel-app

2. Una vez instalada la aplicación diríjase a su panel de administración de vtex, a la sección de Apps > App Management

3. Para configurar nuestro comercio, ubicamos la aplicación de Openpay y damos click en Settings

4. Se nos mostrará la siguiente pantalla de configuración en la cual deberemos completar los campos requeridos, a continuación se nos explica cada uno de los campos.

 

Active Openpay App:  Activa la aplicación de openpay, proveyendo de sus funcionalidades extras.

Is Sandbox: Este campo se activa si deseamos habilitar el modo sandbox para hacer pruebas en nuestro comercio.

Country: Este campo hace referencia al país del comercio Openpay.

Sandbox Merchant Id: Este será el merchant Id de nuestra cuenta de sandbox.

Sandbox Public Key: Esta será la llave pública de nuestra cuenta de sandbox.

Merchant Id Production: Este será el Merchant Id de nuestra cuenta en producción.

Public key Production: Esta será la llave privada de nuestra cuenta en producción.

5. Una vez completado el formulario de configuración, haremos click en el botón Save, para guardar nuestras credenciales.

Cómo obtener el merchant id y la llave pública.

1. En nuestro dashboard Sandbox o producción de Openpay En barra superior, ir al icono de engrane y hacer click en la opción Credenciales de API.

2. Obtener ID (identificador del comercio), Llave privada y Llave pública.

PreAutorización y Captura

Credibanco gateway.

Es el servicio que se encarga de comunicarse con el api Rest de Credibanco. Este microservicio está hecho con la base de Microservicio Gateway que se debe usar para los gateways implementados por microservicios.

Flujo de comunicación con credibanco.

En el siguiente diagrama se muestra la comunicación del microservicio con openpay y la API de credibanco.

1. Preautorizar con 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 credibanco V2 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
  • https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/ charges/{ID_TRANSACTION}/capture

 

Producción

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

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 con Token

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

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

PropiedadDescripció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 para pre-autorización:

Header: Basic {llave privada vigente}

{
"source_id" : "kauf2lhqt1ttwzfqtzmz",
"method" : "card",
"amount" : 10, 
"iva": 1,
"currency":"COP",
"description" : "Test de pago con iva en credibanco",
"order_id" : "id-{{$timestamp}}",
"device_session_id" : "{{$timestamp}}",
"customer" : {
     "name" : "Aaron Hernandez",
     "phone_number" : "5526927856",
     "email" : "joseaaron.hernandez@openpay.mx"
},
"capture": false
}

El campo “capture” será la bandera que identifique al momento de crear el cargo si la transacción es una preautorización.

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.

Ejemplo de la respuesta (Pre-autorización):

{
   "id": "trvha4oojf43oolp4b1q",
   "authorization": "144338",
   "operation_type": "in",
   "transaction_type": "charge",
   "status": "in_progress",
   "conciliated": true,
   "iva": "1",
   "creation_date": "2024-07-24T13:43:31-06:00",
   "operation_date": "2024-07-24T13:43:39-06:00",
   "description": "test de pago con iva credibanco",
   "error_message": null,
   "order_id": "id-1721850211",
   "card": {
       "type": "credit",
       "brand": "visa",
       "address": null,
       "card_number": "455986XXXXXX6643",
       "holder_name": "Aaron Hernandez",
       "expiration_year": "28",
       "expiration_month": "07",
       "allows_charges": true,
       "allows_payouts": false,
       "bank_name": "BANCO DAVIVIENDA",
       "bank_code": "000"
   },
   "gateway_card_present": "CREDIBANCO",
   "amount": 10.00,
   "currency": "COP",
   "customer": {
       "name": "Aaron Hernandez",
       "last_name": null,
       "email": "joseaaron.hernandez@openpay.mx",
       "phone_number": "5526927856",
       "address": null,
       "creation_date": "2024-07-24T13:43:31-06:00",
       "external_id": null,
       "clabe": null
   },
   "method": "card"
}

Petición para la captura (confirmación) en API:

Para confirmar la transacción es necesario de 2 datos importantes:
  • Identificador del comercio (ID): mutdljy8gcsskp0ghx5t
  • Identificador de la transacción inicial (ID): tregvvvmifx4u5jigq9j
endpoint:  /v1/mutdljy8gcsskp0ghx5t/charges/tregvvvmifx4u5jigq9j/capture amount: 0000

2. Preautorizar Cobro Con Link

El  link de cobro se debe generar desde el API

POST: https://api.openpay.co/v1/myvogimhs93x3nbifdj5/checkouts

{
"amount": 200,
"iva": "0",
"origin": "DASHBOARD",
"description": "ocean mall",
"currency": "COP",
"expiration_date": "2025-07-31 18:31",
"order_id": "order_44444444",
"redirect_url": "",
"plan_id_public": "",
"capture": false,
"customer" : {
"name" : "Daniela",
"last_name" : "Caro",
"phone_number" : "4423456723",
"email" : "daniela.caro@test.co"
}
}

Al ingresar en link devuelto se mostrar la pantalla para seleccionar el método de pago.

En la cual se deberá seleccionar la opción Pago con tarjeta, después se mostrará la siguiente pantalla:

En la pantalla anterior se deberán de ingresar los datos requeridos para poder completar los pagos, al completar el pago se retorna la siguiente pantalla, mostrando que la transacción aún no se encuentra completada:

Al ingresar al dashboard a la opción de tarjetas -> Pagos la transacción se debe mostrar con estatus pendiente: como se muestra a continuación:

Este estatus indica que aún no se ha confirmado por parte del comercio.

2.2 Capturar Cobro Con Link

El comercio es quien debe confirmar la transacción desde su dashboard con el siguiente botón:

La transacción automáticamente al confirmar la transacción va a quedar aprobada

Tarjetas de prueba para realizar transacciones:

No. tarjeta

Mes

Año

CVV

Marca

Flujo

Ventana de Prueba

4559860096524495

05

24

480

VISA

Charge

SI


4916479186327004

02

25

994

VISA

Charge

SI


4111111111111110

08

24

123

VISA

Charge

NO

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

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



Tarjetas de prueba para realizar transacciones Frictionless y Challenge:

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


Link de Pago con 3D Secure

Link de Pago con 3D Secure

 

Permite realizar cobros a través de la generación de un link el cual puede ser compartido por medio de un email, redes sociales o bien por un mensaje de texto, de esta manera se logra que los comercios puedan recibir pagos con tarjetas de crédito, débito, puntos bancarios, transferencias interbancarias y/o efectivo en tiendas, todo esto sin la necesidad de que el comercio cuente con un sitio web o app para realizar estos cobros.

 

Esta funcionalidad puede ser usada desde el API Openpay o mediante el dashboard, a continuación se detallan ambos.

 

Link de pago desde Dashboard

Una vez se haya iniciado sesión en el dashboard se debe ingresar al menú: Link de pago/Cobrar con Link de pago.

 

Ingresar los campos requeridos y seleccionar “Generar”

 

El sistema muestra el siguiente mensaje de confirmación, seleccionar “Enviar”.

 

 

El sistema genera el link de pago y muestra diferentes opciones para su envío.

 

 

Link de pago desde API Openpay

Para generar el link de pago desde una petición HTTP el endpoint debe contener los datos y credenciales de acuerdo al ambiente desde donde se desea ejecutar (consideraciones para el API).

Endpoints del merchant disponibles:

 

Método: POST

  • https://sandbox-api.openpay.co/v1/{merchantId}/checkouts

Ejemplo de la petición:

{

   “amount”: 512,

   “currency”: “COP”,

   “description”: “Test Link pago Postman Col”,

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

   “redirect_store_payment”: “true”,

   “order_id”: “ord-111{{$timestamp}},

   “expiration_date”: “2024-10-29 12:50”,

   “send_email”: true,

   “customer”: {

       “name”: “Hector”,

       “last_name”: “Hernandez”,

       “phone_number”: “44883000000”,

       “email”: “hectoralonso.hernandez@openpay.mx”

   }

}

 

Ejemplo de la respuesta:

{

   “id”: “ckkwlhegrx0tw60uqbng”,

   “amount”: 512.00,

   “description”: “Test Link pago Postman Col”,

   “order_id”: “ord-1111712084384”,

   “currency”: “COP”,

   “iva”: “0”,

   “status”: “available”,

   “checkout_link”: “https://dev-api.openpay.co/ck/wA77zZM2Zkuv”,

   “creation_date”: “2024-04-02T13:59:45.122-0500”,

   “expiration_date”: “2024-10-29T13:50:00.000-0500”,

   “customer”: {

       “name”: “HECTOR”,

       “email”: “hectoralonso.hernandez@openpay.mx”,

       “last_name”: “HERNANDEZ”,

       “phone_number”: “44883000000”,

       “external_id”: null

   }

}

 

Nota: El campo checkout_link contiene la URL que dirige al cliente a la pantalla para seleccionar el medio de pago y realizar el pago generado.

 

Formulario de pago 

Ya sea que se haya generado el link de pago desde el dashboard o mediante el API openpay el campo checkout_link contiene el link que nos direcciona a la pantalla para seleccionar el método de pago con tarjeta.

 

En la pantalla Solicitud de pago seleccionamos “Pago con tarjeta”.

Se capturan los datos de la tarjeta y seleccionamos “Realizar pago”.

 

El sistema de autenticación realiza la validación de los datos de la tarjeta. De acuerdo a la información ingresada se puede presentar el flujo challenge o frictionless. En este caso es un Challenge.

 

 

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.

 

 

 

Para consultar información adicional de esta funcionalidad  ver detalle

 

Recaudo con 3D Secure

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.

 

 

Taquilla con 3D Secure

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.

 

 

 

 

API Openpay

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

 

3D Secure

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