Se detallan en esta documentación todos los servicios disponibles para realizar transacciones utilizando los servicios API de GreenPay. Todos los datos que se exponen en los ejemplos son ficticios y deben ser reemplazados por los verdaderos credenciales que solamente el equipo de GreenPay podrá facilitarle.
\nManeje todos los datos con suma discresión.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"21714358","collectionId":"1354f36d-52f7-4101-ac75-2b771487f8c6","publishedId":"2sA3QmFFks","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"3ca7dd"},"publishDate":"2024-05-20T15:49:11.000Z"},"item":[{"name":"Checkout","item":[{"name":"Create Payment Order","event":[{"listen":"test","script":{"id":"16120070-3592-4fca-a13e-a185d9151250","exec":["var jsonData = JSON.parse(responseBody);","postman.setEnvironmentVariable(\"liszt-token\", jsonData.token);","postman.setEnvironmentVariable(\"GP_SESSION\", jsonData.session);","","if(typeof jsonData.token!== \"undefined\"){"," postman.setEnvironmentVariable(\"GP_TOKEN\", jsonData.token);","};","","pm.test(\"Status code is 200\", function () {"," pm.response.to.have.status(200);","});"],"type":"text/javascript","packages":{}}},{"listen":"prerequest","script":{"id":"b3626b9b-41e9-42a0-9e4b-5eba81b249b3","exec":["var moment = require('moment');","","pm.environment.set('currentdate', moment().format((\"YYYY-MM-DD\")));"],"type":"text/javascript","packages":{}}}],"id":"584ed2fe-5056-469a-a1c4-3510b0de2c03","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"secret\": \"{{Secret provisto por GreenPay}}\",\n \"merchantId\": \"{{Merchant ID provisto por GreenPay}}\",\n \"terminal\": \"\",\n \"amount\": 262.11,\n \"currency\": \"USD\",\n \"description\": \"Compra producto 886\",\n \"orderReference\": \"compra-{{currentdate}}-USD-752\",\n \"callback\": \"http://localchost:3000\",\n \"additional\": {\n \"customer\": {\n \"name\": \"John Doe\",\n \"email\": \"johndoe@greenpay.me\",\n \"identification\": \"12345\",\n \"billingAddress\": {\n \"country\": \"CR\",\n \"province\": \"Nombre de la provincia\",\n \"city\": \"Ciudad\",\n \"street1\": \"Dirección Calle 1\",\n \"street2\": \"Dirección Calle 2\",\n \"zip\": \"10801\"\n },\n \"shippingAddress\": {\n \"country\": \"CR\",\n \"province\": \"Nombre de la provincia\",\n \"city\": \"Ciudad\",\n \"street1\": \"Dirección Calle 1\",\n \"street2\": \"Dirección Calle 2\",\n \"zip\": \"10801\"\n }\n },\n \"products\": [\n {\n \"description\": \"Compra de prueba-USD en {{ambiente}}\",\n \"skuId\": \"612\",\n \"quantity\": 1,\n \"price\": 737,\n \"type\": \"TD\"\n }\n ]\n }\n}"},"url":"https://checkoutv2.greenpaysbx.me/createOrder","description":"Una orden de pago se utiliza para indicar al API que se efectuará una transacción con los datos proporcionados.
\nAl crear la orden, se retorna un objeto JSON con los valores token y session, necesarios para invocar el servicio de pago.Estos valores tienen una vigencia de 30 minutos.
\n> Recomendación: Realiza este proceso desde el backend del comercio para proteger las credenciales y detalles de la orden.
\nMétodo: POST
\nBody: JSON
\n{\n \"secret\": \"\",\n \"merchantId\": \"\",\n \"terminal\": \"\",\n \"amount\": 0,\n \"currency\": \"\",\n \"description\": \"\",\n \"orderReference\": \"\",\n \"callback\": \"\",\n \"additional\": {\n \"customer\": {\n \"name\": \"\",\n \"email\": \"\",\n \"identification\": \"\",\n \"billingAddress\": {\n \"country\": \"\",\n \"province\": \"\",\n \"city\": \"\",\n \"street1\": \"\",\n \"street2\": \"\",\n \"zip\": \"\"\n },\n \"shippingAddress\": {\n \"country\": \"\",\n \"province\": \"\",\n \"city\": \"\",\n \"street1\": \"\",\n \"street2\": \"\",\n \"zip\": \"\"\n }\n },\n \"products\": [\n {\n \"description\": \"\",\n \"skuId\": \"\",\n \"quantity\": 0,\n \"price\": 0,\n \"type\": \"\"\n }\n ]\n }\n}\n\nOrden creada exitosamente.
\n{\n \"statusCode\": 200,\n \"message\": \"SUCCESS\",\n \"session\": \"fb3af538-3398-4251-8fcd-3d236fcc6e88\",\n \"token\": \"a944c95c-5380-40fc-b5b7-e9138254bdfa\"\n}\n\nsession: Se utilizará en procesos de pagos posteriores.
token: Se enviará en los headers en procesos de pago posteriores.
Orden no creada por error de validación.
\n{\n \"message\": \"Event object failed validation\",\n \"status\": 400\n}\n\nTodos los campos son requeridos, excepto callback que es opcional.
\nEl campo callback es obligatorio si la integración es por checkoutform.
Si el token y session expiran (30 minutos), se debe crear una nueva orden.
\nSe recomienda enviar todos los datos disponibles para mayor trazabilidad.
\nEste endpoint permite autorizar un monto de una orden de pago y debitar el monto directamente a la tarjeta. Para utilizar este servicio, primero debes crear una orden de pago. Los valores de session y token generados al crear la orden son requeridos para el correcto funcionamiento de este endpoint.
\nRealiza una solicitud al endpoint correspondiente para crear una orden de pago.
\nObtendrás dos valores importantes:
\nsession: Identificador de la sesión de la orden de pago (UUID).
token: Token de seguridad para la sesión (UUID).
Guarda los valores de session y token, ya que serán requeridos para la autorización.
Método: POST
\nDescripción: Autoriza un monto de una orden de pago.
\nRequiere conexión segura: Sí, bajo TLS 1.2.
\nCifrado de datos: Los datos de la tarjeta deben enviarse en formato JSON, codificados en base64.
\n⚠️ ¡Importante!
\nEl header session-token es obligatorio y debe ser enviado en cada solicitud a este endpoint.
El valor de session-token corresponde exactamente al token obtenido al crear la orden de pago.
Si no se incluye este header, la autorización será rechazada.
\nEjemplo de session-token (UUID): ad79b9b0-917d-11ef-8a48-19ee98944b83
\n{\n \"session\": \"ad79b9b0-917d-11ef-8a48-19ee98944b83\",\n \"ed\": \"eyJjYXJkIjp7ImNhcmRIb2xkZXIiOiJKb2huIERvZSIsImV4cGlyYXRpb25EYXRlIjp7Im1vbnRoIjoiMTIiLCJ5ZWFyIjoiMzEifSwiY2FyZE51bWJlciI6IjQwMDU1Mjk5OTkwMDEyMyIsImN2YyI6IjE5NiJ9LCJhZGRpdGlvbmFsIjp7ImNoYW5uZWxEYXRhIjp7ImNoYW5uZWwiOiIwMSIsInNvdXJjZSI6IkFQSV9DQVJEIn19fSwia291bnRTZXNzaW9uIjoiNTgyMThkMjJhMzRmNDJjZGEwNDE3ODliM2FiYzlkNTAifQ==\"\n}\n\nsession: UUID obtenido al crear la orden de pago.
ed: Datos de la tarjeta cifrados en base64 (ver estructura y ejemplo abajo).
ℹ️ Nota sobre kountSession:
Antes de enviar el campo kountSession, debes consultar si la integración que vas a utilizar requiere o no este campo y si tienes la aprobación de GreenPay para el uso de esta funcionalidad.
\nEl campo kountSession es obligatorio únicamente si tu integración y GreenPay lo requieren y han aprobado su uso.
La recolección de este dato se realiza del lado del frontend, utilizando el SDK de Kount o el Data Collector correspondiente.
\nConsulta la documentación específica de integración de Kount para más detalles sobre cómo obtener este valor en el navegador del usuario.
\nℹ️ Nota sobre plan y quota:
Para realizar plagos con planes se deben enviar estos dos valores, estos valores los debe obtener mediante un endpoint que GreenPay Facilita, la documentacion del endpoint la puede encontrar en la Merchant/Plans en la documentacion de postman
\nEstos datos los tiene que solicitar mediante interfaz gráfica en su frontend, para revisar una integración por código puede revisar el siguiente ejemplo en NodeJS
Checkout V2 API
Sino utiliza pagos con Cuota y plan porfavor omitir estos campos.
\nSu terminal debe estar configurada para aceptar pagos con planes
\n{\n \"card\": {\n \"cardHolder\": \"John Doe\",\n \"expirationDate\": { \"month\": \"12\", \"year\": \"31\" },\n \"cardNumber\": \"4005529999000123\",\n \"cvc\": \"196\"\n },\n \"additional\": {\n \"channelData\": { \"channel\": \"01\", \"source\": \"API_CARD\" }\n },\n \"kountSession\": \"58218d22a34f42cda041789b3abc9d50\",\n // solo aplica para planes \n // campos requeridos para pagos con planes\n \"plan\": \"06ae4d6a-a55d-41b8-894e-be9b75c4f063\",\n \"quota\": 6, // DEBE ser número entero, NO string\n}\n\neyJjYXJkIjp7ImNhcmRIb2xkZXIiOiJKb2huIERvZSIsImV4cGlyYXRpb25EYXRlIjp7Im1vbnRoIjoiMTIiLCJ5ZWFyIjoiMzEifSwiY2FyZE51bWJlciI6IjQwMDU1Mjk5OTkwMDEyMyIsImN2YyI6IjE5NiJ9LCJhZGRpdGlvbmFsIjp7ImNoYW5uZWxEYXRhIjp7ImNoYW5uZWwiOiIwMSIsInNvdXJjZSI6IkFQSV9DQVJEIn19fSwia291bnRTZXNzaW9uIjoiNTgyMThkMjJhMzRmNDJjZGEwNDE3ODliM2FiYzlkNTAifQ==
\nDependiendo del resultado de la solicitud, la API puede devolver una respuesta exitosa o fallida.
\nA continuación se describen ambos escenarios:
\nEl HTTP code (código de estado HTTP) es un número que indica el resultado de una solicitud HTTP:
\nUn código 200 significa que la solicitud fue exitosa.
\nCualquier código diferente a 200 (por ejemplo, 400, 401, 404, 500, etc.) indica que la solicitud falló por algún motivo.
\nCuando la autorización es exitosa, la API responde con un código HTTP 200 y un objeto JSON como el siguiente:
\n{\n \"status\": 200,\n \"orderId\": \"compra-2024-10-23-USD-265\",\n \"authorization\": \"445000\",\n \"amount\": 302,\n \"currency\": \"USD\",\n \"token\": \"0c86cae0-917b-11ef-8500-27f1ad691f71\",\n \"internalRef\": 10819032514292,\n \"transactionId\": \"beb386d4-0595-49b1-a7a9-e23876cf0b97\",\n \"errors\": [],\n \"last4\": \"1815\",\n \"brand\": \"Mastercard\",\n \"quota\": 0\n}\n\nauthorization: Referencia de autorización de la transacción.
\ntransactionId: Identificador único de la transacción en GreenPay.
\nerrors: Siempre es un arreglo vacío en respuestas exitosas.
\nquota: El campo quota es para transacciones a plazos, se establece por defecto en 0 en la respuesta exitosa. Omitir este campo si no hace uso de transacciones a plazos.
\nCuando la autorización falla, la API responde con un código HTTP distinto de 200 y un objeto JSON como el siguiente:
\n{\n \"message\": \"terminal not found\",\n \"status\": \"fail\"\n}\n\nmessage: Descripción del motivo de la falla.
\nstatus: Siempre será \"fail\" en caso de error.
\n⚡ ¿Cómo funciona el Webhook?La URL del webhook debe ser configurada previamente desde el dashboard de GreenPay.
\nPara este endpoint de autorizaciones, la respuesta será enviada a la URL raíz del webhook que hayas configurado para tu comercio.
\nEjemplo: Si tu webhook es https://miwebhook.com, se enviará una petición HTTP tipo POST a esa URL con un objeto como los siguientes ejemplos.
El campo status en la respuesta del webhook indica el resultado de la transacción:
\n🟢 status: 200 en el campo status de la respuesta del webhook indica una transacción exitosa.
{\n \"status\": 200,\n \"orderId\": \"compra-2024-10-23-USD-431\",\n \"authorization\": \"831000\",\n \"amount\": 14,\n \"currency\": \"USD\",\n \"token\": \"ad79b9b0-917d-11ef-8a48-19ee98944b83\",\n \"internalRef\": 18155385770690,\n \"transactionId\": \"76b784bb-9e0c-4091-8c5c-48b2b00e7cb6\",\n \"errors\": [],\n \"last4\": \"1815\",\n \"brand\": \"Mastercard\",\n \"quota\": 0\n}\n\nEl campo status con valor 200 indica una transacción exitosa en la respuesta del webhook.
\nEl campo quota es para transacciones a plazos, se establece por defecto en 0 en la respuesta exitosa. Omitir este campo si no hace uso de transacciones a plazos.
\n🔴 status diferente de 200 en el campo status de la respuesta del webhook indica una transacción fallida.
\n{\n \"status\": 500,\n \"orderId\": \"compra-2024-10-23-USD-617\",\n \"authorization\": null,\n \"amount\": 53,\n \"currency\": \"USD\",\n \"token\": null,\n \"internalRef\": 8139382378302,\n \"transactionId\": \"2d3af6f7-e610-4854-82ee-fb576da23cec\",\n \"errors\": [\n \"All other response codes received\"\n ],\n \"last4\": \"1815\",\n \"brand\": \"Mastercard\"\n}\n\nMétodos necesarios para procesar transacciones on demand utilizando los servicios de GreenPay
\nUna orden de pago se crea para indicar al API de pago que se efectuará una transacción por el motivo de los datos indicados en la orden. Para esto se debe tener las siguientes consideraciones:
\nEn sandbox: https://checkoutv2.greenpaysbx.me/createOrder
En producción: https://checkoutv2.greenpay.me/createOrder
Una orden de pago genera una respuesta en formato JSON que contiene un valor session, token, statusCode y message
\nEl valor session y el token tendrá una vigencia de 30 minutos a partir de la creación de la orden de pago. Una vez cumplido ese plazo no tendrán validez, si se quiere continuar con el proceso se debe crear otra orden.
\nSe recomienda que este proceso se realice desde el backend del comercio, para proteger los datos de las credenciales y detalles de la orden de pago.
\nPara realizar la creación de una orden de Pago GreenPay cuenta con ejemplos tanto en NodeJS como en Postman
\nNodeJS
\n\nEste ejemplo contiene la creación de la orden y el pago por API
\n","_postman_id":"b9d8c67b-e358-4e63-9df3-08c9bf4d7d9b"},{"name":"Preauthorization","item":[{"name":"Preauthorization request","event":[{"listen":"test","script":{"id":"1098dc37-cea8-455e-ac19-9cede81676f7","exec":["var jsonData = JSON.parse(responseBody);","postman.setEnvironmentVariable(\"confirm-authorization-token\", jsonData.jwt);","","if(typeof jsonData.jwt!== \"undefined\"){"," postman.setEnvironmentVariable(\"confirm-authorization-token\", jsonData.jwt);","};","","pm.test(\"Status code is 200\", function () {"," pm.response.to.have.status(200);","});"],"type":"text/javascript","packages":{}}}],"id":"cd6c1a07-c4fe-4f34-bbce-fd55eb9c6dd1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"session-token","value":"{{ID de token obtenido al momento de crear la orden de pago o tokenizacion}}"}],"body":{"mode":"raw","raw":"{\n \"session\": \"{{ID de sesión obtenido al momento de crear la orden de pago o tokenizacion}}\",\n \"ed\":\"eyJjYXJkIjp7ImNhcmRIb2xkZXIiOiJKb2huIERvZSIsImV4cGlyYXRpb25EYXRlIjp7Im1vbnRoIjoiMTIiLCJ5ZWFyIjoiMzEifSwiY2FyZE51bWJlciI6IjQwMDU1Mjk5OTkwMDAxMjMiLCJjdmMiOiIxOTYifSwiYWRkaXRpb25hbCI6eyJjaGFubmVsRGF0YSI6eyJjaGFubmVsIjoiMDEiLCJzb3VyY2UiOiJBUElfQ0FSRCJ9fSwia291bnRTZXNzaW9uIjoiNTgyMThkMjJhMzRmNDJjZGEwNDE3ODliM2FiYzlkNTAifQ==\"\n}","options":{"raw":{"language":"json"}}},"url":"https://checkoutv2.greenpaysbx.me/preauthorize","description":"Este endpoint permite crear una preautorización sobre una orden de pago. La preautorización retiene el monto en la tarjeta, pero no lo debita. Es ideal para escenarios donde se requiere garantizar fondos antes de realizar el cobro final.
\nRealiza una solicitud al endpoint correspondiente para crear una orden de pago.
\nsession: Identificador de la sesión de la orden de pago (UUID).token: Token de seguridad para la sesión (UUID).Guarda los valores de session y token, ya que serán requeridos para la preautorización.
\n⚠️ ¡Importante!
\nEl header session-token es obligatorio y debe ser enviado en cada solicitud a este endpoint.
El valor de session-token corresponde exactamente al token obtenido al crear la orden de pago.
Si no se incluye este header, la preautorización será rechazada.
\nEjemplo de session-token (UUID):ad79b9b0-917d-11ef-8a48-19ee98944b83
\n{\n \"session\": \"ad79b9b0-917d-11ef-8a48-19ee98944b83\",\n \"ed\": \"eyJjYXJkIjp7ImNhcmRIb2xkZXIiOiJBbmdlbCBHb256YWxleiIsImV4cGlyYXRpb25EYXRlIjp7Im1vbnRoIjoiMDMiLCJ5ZWFyIjoiMjUifSwiY2FyZE51bWJlciI6IjU1OTcyNzAwMDAwMDE4MTUiLCJjdmMiOiIxOTYifSwiYWRkaXRpb25hbCI6eyJjaGFubmVsRGF0YSI6eyJjaGFubmVsIjoiMDEiLCJzb3VyY2UiOiJBUElfQ0FSRCJ9fSwia291bnRTZXNzaW9uIjoiNTgyMThkMjJhMzRmNDJjZGEwNDE3ODliM2FiYzlkNTAifQ==\"\n}\n\nsession: UUID obtenido al crear la orden de pago (requerido).ed: Datos de la tarjeta cifrados en base64 (requerido, ver estructura y ejemplo abajo).ℹ️ Nota sobre kountSession:
Antes de enviar el campo kountSession, debes consultar si la integración que vas a utilizar requiere o no este campo y si tienes la aprobación de GreenPay para el uso de esta funcionalidad.
\nEl campo kountSession es obligatorio únicamente si tu integración y GreenPay lo requieren y han aprobado su uso.
\nLa recolección de este dato se realiza del lado del frontend, utilizando el SDK de Kount o el Data Collector correspondiente.
\nConsulta la documentación específica de integración de Kount para más detalles sobre cómo obtener este valor en el navegador del usuario.
\n{\n \"card\": {\n \"cardHolder\": \"Angel Gonzalez\",\n \"expirationDate\": { \"month\": \"03\", \"year\": \"25\" },\n \"cardNumber\": \"5597270000001815\",\n \"cvc\": \"196\"\n },\n \"additional\": {\n \"channelData\": { \"channel\": \"01\", \"source\": \"API_CARD\" }\n },\n \"kountSession\": \"58218d22a34f42cda041789b3abc9d50\"\n}\n\neyJjYXJkIjp7ImNhcmRIb2xkZXIiOiJBbmdlbCBHb256YWxleiIsImV4cGlyYXRpb25EYXRlIjp7Im1vbnRoIjoiMDMiLCJ5ZWFyIjoiMjUifSwiY2FyZE51bWJlciI6IjU1OTcyNzAwMDAwMDE4MTUiLCJjdmMiOiIxOTYifSwiYWRkaXRpb25hbCI6eyJjaGFubmVsRGF0YSI6eyJjaGFubmVsIjoiMDEiLCJzb3VyY2UiOiJBUElfQ0FSRCJ9fSwia291bnRTZXNzaW9uIjoiNTgyMThkMjJhMzRmNDJjZGEwNDE3ODliM2FiYzlkNTAifQ==
\nDependiendo del resultado de la solicitud, la API puede devolver una respuesta exitosa o fallida.
\nA continuación se describen ambos escenarios:
\nEl HTTP code (código de estado HTTP) es un número que indica el resultado de una solicitud HTTP:
\nCuando la preautorización es exitosa, la API responde con un código HTTP 200 y un objeto JSON como el siguiente:
\n{\n \"statusCode\": 200,\n \"jwt\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0cmFuc2FjdGlvbl9pZCI6IjhlMzJiNzYwLTA0Y2ItNDk3Ny05NzFmLWI5YjJmYjcwZDExMCIsImlhdCI6MTcxNjMwOTA4MywiZXhwIjoxNzE2MzEyNjgzfQ.qd39KMvng-ja31aCWQM8afVKZZVOEHW5uOagIQT5lno\"\n}\n\nEste campo jwt debe ser utilizado posteriormente en el endpoint de confirmación de preautorización para completar el proceso de cobro.
Cuando la preautorización falla, la API responde con un código HTTP distinto de 200 y un objeto JSON como el siguiente:
\n{\n \"message\": \"Error: Transaccion fraudulenta\",\n \"status\": \"fail\"\n}\n\n⚡ ¿Cómo funciona el Webhook?
\nLa URL del webhook debe ser configurada previamente desde el dashboard de GreenPay.
\nPara este endpoint de preautorizaciones, la respuesta será enviada a la URL raíz del webhook que hayas configurado para tu comercio, agregando el path /preauthorize.
\nEjemplo:Si tu webhook es https://mywebhook.com/, la respuesta de la preautorización por API llegará a la url https://mywebhook.com/preauthorize.
\nGreenPay agregará el path /preauthorize, esa url debe existir en tu backend.El campo status en la respuesta del webhook indica el resultado de la transacción:
\n🟢 status: 200 en el campo status de la respuesta del webhook indica una transacción exitosa.
\n{\n \"status\": 200,\n \"orderId\": \"compra-2024-10-24-USD-352\",\n \"authorization\": \"831000\",\n \"amount\": 318,\n \"currency\": \"USD\",\n \"token\": \"1f702dc0-9227-11ef-8a48-19ee98944b83\",\n \"internalRef\": 10725057520759,\n \"transactionId\": \"5f4914e0-6b3d-4369-982a-ed423b1bf9f4\",\n \"errors\": [],\n \"last4\": \"1815\",\n \"quota\": 0,\n \"brand\": \"Mastercard\"\n}\n\nstatus con valor 200 indica una transacción exitosa en la respuesta del webhook.quota es para transacciones a plazos, se establece por defecto en 0 en la respuesta exitosa. Omitir este campo si no hace uso de transacciones a plazos.🔴 status diferente de 200 en el campo status de la respuesta del webhook indica una transacción fallida.
\n{\n \"status\": 500,\n \"orderId\": \"compra-2024-10-24-USD-353\",\n \"authorization\": null,\n \"amount\": 53,\n \"currency\": \"USD\",\n \"token\": null,\n \"internalRef\": 8139382378302,\n \"transactionId\": \"2d3af6f7-e610-4854-82ee-fb576da23cec\",\n \"errors\": [\n \"All other response codes received\"\n ],\n \"last4\": \"1815\",\n \"brand\": \"Mastercard\"\n}\n\nstatus es diferente de 200, la transacción es considerada fallida en la respuesta del webhook.Este endpoint es el último paso del flujo de pre-autorización de transacciones.
\nPermite confirmar una preautorización previamente realizada, debitando el monto retenido en la tarjeta.
\nDebes haber realizado previamente una preautorización exitosa utilizando el endpoint de preautorización.
\nGuarda el JWT obtenido, ya que será requerido como Bearer Token en el header de la solicitud de confirmación.
\nMétodo: POST
\nAmbiente de desarrollo: https://checkoutv2.greenpaysbx.me/confirm-pre-authorization
\nAmbiente productivo: https://checkoutv2.greenpay.me/confirm-pre-authorization
\nDescripción: Confirma una preautorización y debita el monto previamente retenido.
\nRequiere conexión segura: Sí, bajo TLS 1.2.
\n⚠️ ¡Importante!
\nEl header de autenticación Bearer Token es obligatorio y debe ser enviado en cada solicitud a este endpoint.
\nEl valor del Bearer Token corresponde exactamente al JWT obtenido al realizar la preautorización.
\nSi no se incluye este header, la confirmación será rechazada.
\nEjemplo de header Authorization:
\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
\nNo se requiere body en la solicitud. Toda la información necesaria se transmite en el JWT enviado en el header.
\nDependiendo del resultado de la solicitud, la API puede devolver una respuesta exitosa o fallida. A continuación se describen ambos escenarios:
\nEl HTTP code (código de estado HTTP) es un número que indica el resultado de una solicitud HTTP:
\nUn código 200 significa que la solicitud fue exitosa.
\nCualquier código diferente a 200 (por ejemplo, 400, 401, 404, 500, etc.) indica que la solicitud falló por algún motivo.
\nCuando la confirmación de preautorización es exitosa, la API responde con un código HTTP 200 y un objeto JSON como el siguiente:
\n{\n \"statusCode\": 200,\n \"status\": 200,\n \"internalRef\": 57730533711,\n \"orderId\": \"compra-2024-05-21-CRC-672\",\n \"amount\": 12000,\n \"currency\": \"CRC\",\n \"token\": \"caae44d0-1791-11ef-9c9e-e3ed7042d9a8\",\n \"transactionId\": \"d6e2ff9d-4ed2-4ed3-bab5-227953616199\",\n \"webhook_url\": \"https://webhook.site/2fcc16c9-7c4f-4ac9-88d1-52d930ece6ec\",\n \"authorization\": \"831000\"\n}\n\nstatusCode: Código HTTP de la respuesta (200 para éxito).
\nstatus: Código de estado de la transacción (200 para éxito).
\ninternalRef: Referencia interna de la transacción.
\norderId: Identificador de la orden de pago.
\namount: Monto debitado.
\ncurrency: Moneda de la transacción.
\ntoken: Token de la transacción.
\ntransactionId: Identificador único de la transacción.
\nwebhook_url: URL a la que se notificó el resultado.
\nauthorization: Código de autorización de la transacción.
\nCuando la confirmación de preautorización falla, la API responde con un código HTTP distinto de 200 y un objeto JSON como el siguiente:
\n{\n \"message\": \"No se ha enviado el token de autenticación\",\n \"status\": \"fail\"\n}\n\nmessage: Descripción del motivo de la falla.
\nstatus: Siempre será \"fail\" en caso de error.
\n⚡ ¿Cómo funciona el Webhook?
\nLa URL del webhook debe ser configurada previamente desde el dashboard de GreenPay.
\nPara este endpoint de confirmación de preautorización, la respuesta será enviada a la URL raíz del webhook que hayas configurado para tu comercio, agregando el path /confirm-preauthorize.
\nEjemplo:Si tu webhook es https://mywebhook.com/, la respuesta de la confirmación de preautorización por API llegará a la url https://mywebhook.com/confirm-preauthorize.
\nGreenPay agregará el path /confirm-preauthorize, esa url debe existir en tu backend.
\nEl campo status en la respuesta del webhook indica el resultado de la transacción:
\n🟢 status: 200 en el campo status de la respuesta del webhook indica una transacción exitosa.
\n{\n \"status\": 200,\n \"internalRef\": 13585077813588,\n \"orderId\": \"compra-2024-10-25-USD-288\",\n \"amount\": 613,\n \"currency\": \"USD\",\n \"token\": \"63947480-92ee-11ef-bd8e-177728d45168\",\n \"transactionId\": \"6af91302-7993-4189-8fff-eaf55b47a4d4\",\n \"webhook_url\": \"https://webhook.site/e8786529-8cbe-4463-8558-5c0aa3bd0963\",\n \"authorization\": \"831000\"\n}\n\nEste servicio permite pre-autorizar un monto de una orden de pago, bloqueandolo en la cuenta del cliente para luego ser confirmado y debitado. Para utilizar el servicio de preautorización, es necesario crear una orden de pago antes de consumir este endpoint. Los valores de session y token generados al momento de crear la orden de pago son requeridos para el correcto funcionamiento de este servicio.
\nEl valor de \"ed\" corresponde a los datos de la tarjeta, estos datos deben enviarse en un objeto JSON y aplicar un hash con base64, el siguiente es un ejemplo de la estructura del objeto JSON:
\n// Card data\nconst cardData = {\n card: {\n cardHolder: \"John Doe\",\n expirationDate: {\n month: \"12\",\n year: \"31\",\n },\n cardNumber: \"4005529999000123\",\n cvc: \"196\",\n },\n additional: { channelData: { channel: \"01\", source: \"API_CARD\" } },\n kountSession: \"58218d22a34f42cda041789b3abc9d50\", // KOUNT SESSION ID FROM KOUNT SDK\n};\n\nDatos obligatorios:
\ncard.cardHolder: String. Nombre del dueño de la tarjeta. De 5 a 50 caracteres.
card.expirationDate.month: String. Número que indica el mes de vencimiento de la tarjeta, este parámetro debe tener cifras entre 1 y 12.
card.expirationDate.year: String. Número que indica el año de vencimiento de la tarjeta, este parámetro debe tener cifras de 2 dígitos, los últimos 2 dígitos del año en que vence la tarjeta.
card.cardNumber:String. Corresponde al número de la tarjeta
card.cvc : String. Código de seguridad de la tarjeta.
additional: Object. Debe ser la misma estructura del ejemplo, requerido por GreenPay
kountSession: String. Es el valor params.MercSessId que se obtienen del Data Collector.
Por razones de seguridad, tanto para GreenPay como para proteger las transacciones de su comercio, se requiere que la información de la tarjeta o el token se envíe de forma segura, utilizando conexión segura bajo TLS 1.2. Y cómo un método extra de seguridad, la información de la tarjeta se debe enviar codificada en base64.
\nEn greeenpay/checkout-v2-nodejs podrá encontrar ejemplos de integración desarrollados en NodeJS.
\n","_postman_id":"56975330-aa3e-478a-8d5c-af5884a4097c"},{"name":"Revert","item":[{"name":"Revert Transaction","id":"9c37b771-0aec-4d43-8def-ef684708c4e0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"authorization\": \"{{Código de autorización de la transacción a revertir}}\",\n \"merchantId\": \"{{Merchant ID provisto por GreenPay}}\",\n \"transactionId\": \"{{ID de la transacción a revertir}}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://checkoutv2.greenpaysbx.me/revert","description":"Este endpoint permite revertir (anular) una transacción preautorizada.
\nLa posibilidad de realizar la reversión depende de la entidad bancaria emisora de la tarjeta: algunas entidades permiten la reversión inmediata, mientras que otras pueden rechazarla.
\nDebes haber realizado previamente una transacción exitosa (preautorización) utilizando los endpoints correspondientes.
\nObtendrás los siguientes datos necesarios para la reversión:
\nauthorization: Código de autorización generado al realizar el pago.
\nmerchantId: ID del comercio asignado por GreenPay.
\ntransactionId: Identificador único de la transacción.
\nLa reversión solo será exitosa si la entidad bancaria emisora lo permite. Si la entidad no admite reversión, la operación será rechazada.
\nMétodo: POST
\nAmbiente de desarrollo: https://checkoutv2.greenpaysbx.me/revert
\nAmbiente productivo: https://checkoutv2.greenpay.me/revert
\nDescripción: Revierte una transacción previamente autorizada o preautorizada.
\nRequiere conexión segura: Sí, bajo TLS 1.2.
\nEl cuerpo de la solicitud debe ser un objeto JSON con la siguiente estructura:
\n{\n \"authorization\": \"831000\",\n \"merchantId\": \"6e792b4c-1f95-4895-9434-d6d4aa38d491\",\n \"transactionId\": \"74f80564-d3f6-4738-bab2-d1d7fc91837f\"\n}\n\nDependiendo del resultado de la solicitud, la API puede devolver una respuesta exitosa o fallida.
\nA continuación se describen ambos escenarios:
\nEl HTTP code (código de estado HTTP) es un número que indica el resultado de una solicitud HTTP:
\nUn código 200 significa que la solicitud fue exitosa.
\nCualquier código diferente a 200 (por ejemplo, 400, 401, 404, 500, etc.) indica que la solicitud falló por algún motivo.
\nCuando la reversión es exitosa, la API responde con un código HTTP 200 y un objeto JSON como el siguiente:
\n{\n \"status\": 200,\n \"errors\": [],\n \"transactionId\": \"ff87e0ed-a796-4997-8dc4-3669d1201087\",\n \"authorization\": \"831000\"\n}\n\nstatus: Código de estado de la transacción (200 para éxito).
\nerrors: Siempre es un arreglo vacío en respuestas exitosas.
\ntransactionId: Identificador único de la transacción revertida.
\nauthorization: Código de autorización de la transacción revertida.
\nCuando la reversión falla, la API responde con un código HTTP distinto de 200 y un objeto JSON como el siguiente:
\n{\n \"message\": \"Error: the transaction cannot be reversed\",\n \"status\": \"fail\"\n}\n\nmessage: Descripción del motivo de la falla.
\nstatus: Siempre será \"fail\" en caso de error.
\n⚡ ¿Cómo funciona el Webhook?
\nLa URL del webhook debe ser configurada previamente desde el dashboard de GreenPay.
\nPara este endpoint de reversión, la respuesta será enviada a la URL raíz del webhook que hayas configurado para tu comercio, agregando el path /revert.
Ejemplo:Si tu webhook es https://mywebhook.com/, la respuesta de la reversión por API llegará a la url https://mywebhook.com/revert.
GreenPay agregará el path /revert, esa url debe existir en tu backend.
Nota: Actualmente, solo las respuestas exitosas de reversión llegan al webhook.
\n🟢 status: 200 en el campo status de la respuesta del webhook indica una reversión exitosa.
\n{\n \"status\": 200,\n \"errors\": [],\n \"transactionId\": \"ff87e0ed-a796-4997-8dc4-3669d1201087\",\n \"authorization\": \"831000\"\n}\n\nEl método de reversión de transacciones le permite, como su nombre lo indica, reversar una transacción que ya fue procesada por GreenPay, para realizar una reversión, es necesario que la transacción aún no haya sido liquidada por la entidad bancaria, de lo contrario esta opción ya no va a estar disponible.
\n","_postman_id":"66a783a7-47ca-4bb4-99e9-f0bc676e9531"},{"name":"Tokenization","item":[{"name":"Create a Tokenization Order","id":"b0f04c12-e080-459b-bab7-3e2f6d5f40d2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"secret\": \"{{Secret provisto por GreenPay}}\",\n \"merchantId\": \"{{Merchant ID provisto por GreenPay}}\",\n \"requestId\": \"204\"\n}","options":{"raw":{"language":"json"}}},"url":"https://checkoutv2.greenpaysbx.me/tokenizeOrder","description":"Este endpoint recopila la información necesaria para ejecutar una orden de tokenización de tarjeta en GreenPay, permitiendo que la tarjeta sea utilizada posteriormente en transacciones de forma segura.
\nEste paso es necesario para tokenizar una tarjeta, ya sea utilizando la API directamente o mediante el formulario de tokenización (tokenizeForm) provisto por GreenPay
\n.Al ejecutar este request se genera un ID de sesión que será requerido en el siguiente paso del flujo.
\nMétodo: POST
\nProducción: https://checkoutv2.greenpay.me/tokenizeOrder
\nDescripción: Crea una orden de tokenización y retorna los identificadores necesarios para continuar el proceso.
\nRequiere conexión segura: Sí, bajo TLS 1.2.
\nUna orden de tokenización genera una respuesta en formato JSON que contiene los campos statusCode, session y token.
\nLos valores de session y token tendrán una vigencia de 30 minutos desde su creación. Pasado ese plazo, será necesario crear una nueva orden.
\nSe recomienda que este proceso se realice en el backend del comercio para proteger los datos sensibles.
\nEste paso es obligatorio tanto si vas a tokenizar la tarjeta por API como si vas a utilizar el formulario de tokenización (tokenizeForm).
\nEl cuerpo de la solicitud debe ser un objeto JSON con la siguiente estructura:
\n{\n \"secret\": \"secret provisto por GreenPay 2.0\",\n \"merchantId\": \"merchant provisto por GreenPay 2.0\",\n \"requestId\": \"número entero para identificar la orden\",\n \"callback\": \"https://tudominio.com/callback\" // Opcional\n}\n\nDependiendo del resultado de la solicitud, la API puede devolver una respuesta exitosa o fallida. A continuación se describen ambos escenarios:
\nEl HTTP code (código de estado HTTP) es un número que indica el resultado de una solicitud HTTP:
\nUn código 200 significa que la solicitud fue exitosa.
\nCualquier código diferente a 200 (por ejemplo, 400, 401, 404, 500, etc.) indica que la solicitud falló por algún motivo.
\nCuando la orden de tokenización es exitosa, la API responde con un código HTTP 200 y un objeto JSON como el siguiente:
\n{\n \"statusCode\": 200,\n \"session\": \"251da6a5-9cc1-4a8c-9b75-2fddc3627ae4\",\n \"token\": \"84336c9a-32d3-4616-84f4-e78b344af60a\"\n}\n\nstatusCode: Código HTTP de la respuesta (200 para éxito).
\nsession: Identificador de sesión generado para la orden de tokenización.
\ntoken: Token generado para la orden de tokenización.
\nCuando la orden de tokenización falla, la API responde con un código HTTP distinto de 200 y un objeto JSON como el siguiente:
\n{\n \"message\": \"Error al tokenizar la Información!\",\n \"status\": \"fail\"\n}\n\nmessage: Descripción del motivo de la falla.
\nstatus: Siempre será \"fail\" en caso de error.
\nEste endpoint permite tokenizar una tarjeta de crédito o débito para su uso seguro en futuras transacciones.
\nAntes de utilizar este servicio, primero debes crear una orden de tokenización.
\nEl valor de session generado al crear la orden es requerido para el correcto funcionamiento de este endpoint.
\nRealiza una solicitud al endpoint correspondiente para crear una orden de tokenización.
\nObtendrás el valor importante:
\nsession: Identificador de la sesión de la orden de tokenización (UUID).
Guarda el valor de session, ya que será requerido para la tokenización.
Método: POST
\nSandbox: https://checkoutv2.greenpaysbx.me/tokenizeCard
Producción: https://checkoutv2.greenpay.me/tokenizeCard
Requiere conexión segura: Sí, bajo TLS 1.2.
\nCifrado de datos: Los datos de la tarjeta deben enviarse en formato JSON, codificados en base64.
\n⚠️ ¡Importante!
\nEl header session-token es obligatorio y debe ser enviado en cada solicitud a este endpoint.El valor de session-token corresponde exactamente al session obtenido al crear la orden de tokenización.Si no se incluye este header, la tokenización será rechazada.
\nEjemplo de session-token (UUID):b1249250-e620-11ee-a8be-d1e162aad25c
\n{\n \"session\": \"b1249250-e620-11ee-a8be-d1e162aad25c\",\n \"ed\": \"eyJjYXJkIjp7ImNhcmRIb2xkZXIiOiJKb2huIERvZSIsImV4cGlyYXRpb25EYXRlIjp7Im1vbnRoIjoiMTIiLCJ5ZWFyIjoiMzEifSwiY2FyZE51bWJlciI6IjU1OTcyNzAwMDAwMDE4MTUiLCJjdmMiOiIxOTYifX0=\"\n}\n\nsession: UUID obtenido al crear la orden de tokenización (requerido).
ed: Datos de la tarjeta cifrados en base64 (requerido, ver estructura y ejemplo abajo).
{\n \"card\": {\n \"cardHolder\": \"John Doe\",\n \"expirationDate\": { \"month\": \"12\", \"year\": \"31\" },\n \"cardNumber\": \"5597270000001815\",\n \"cvc\": \"196\"\n }\n}\n\neyJjYXJkIjp7ImNhcmRIb2xkZXIiOiJKb2huIERvZSIsImV4cGlyYXRpb25EYXRlIjp7Im1vbnRoIjoiMTIiLCJ5ZWFyIjoiMzEifSwiY2FyZE51bWJlciI6IjU1OTcyNzAwMDAwMDE4MTUiLCJjdmMiOiIxOTYifX0=
\n¿Cómo cifrar los datos de la tarjeta?Por seguridad, la información de la tarjeta debe enviarse codificada en base64 y a través de una conexión segura (TLS 1.2).
\nEjemplo en JavaScript:
\nconst cardData = {\n card: {\n cardHolder: \"John Doe\",\n expirationDate: {\n month: \"12\",\n year: \"31\"\n },\n cardNumber: \"5597270000001815\",\n cvc: \"196\"\n }\n};\nconst base64 = Buffer.from(JSON.stringify(cardData)).toString(\"base64\");\nconsole.log(base64);\n\nEl valor resultante (base64) se debe enviar en el campo ed del cuerpo de la petición.
\nHTTP 200
\n{\n \"statusCode\": 200,\n \"result\": {\n \"cardHolder\": \"John Doe\",\n \"brand\": \"Visa\",\n \"bin\": \"455676\",\n \"last4\": \"6446\",\n \"khash\": \"455676SNB18A5F1T3QWC\",\n \"token\": \"b1249250-e620-11ee-a8be-d1e162aad25c\",\n \"cardMasked\": \"455676******6446\"\n }\n}\n\n> El campo result.token es el valor que debe guardarse en su base de datos para identificar la tarjeta de forma segura.
> Para realizar pagos futuros con esta tarjeta, deberá utilizar este token en el endpoint correspondiente a pagos con token, siguiendo el flujo y la documentación específica para pagos con token.
\nHTTP diferente de 200
\n{\n \"message\": \"Encabezado invalido: Session-Token es requerido\",\n \"status\": \"fail\"\n}\n\n⚡ ¿Cómo funciona el Webhook?
\nLa URL del webhook debe ser configurada previamente desde el dashboard de GreenPay.
\nPara este endpoint de tokenización de tarjeta, la respuesta será enviada a la URL raíz del webhook que hayas configurado para tu comercio, agregando el path /tokenizeCard.
\nEjemplo:Si tu webhook es https://mywebhook.com/, la respuesta de la tokenización por API llegará a la url https://mywebhook.com/tokenizeCard.
\nGreenPay agregará el path /tokenizeCard, esa url debe existir en tu backend.Nota: Actualmente, solo las respuestas exitosas de tokenización llegan al webhook.
\n🟢 statusCode: 200 en el campo statusCode de la respuesta del webhook indica una tokenización exitosa.
\n{\n \"statusCode\": 200,\n \"result\": {\n \"cardHolder\": \"John Doe\",\n \"brand\": \"Visa\",\n \"bin\": \"455676\",\n \"last4\": \"6446\",\n \"khash\": \"455676SNB18A5F1T3QWC\",\n \"token\": \"b1249250-e620-11ee-a8be-d1e162aad25c\",\n \"cardMasked\": \"455676******6446\"\n }\n}\n\nLos siguientes métodos son utilizados para la tokenización de tarjetas y su posterior uso en las compras que se realizan utilizando el ecosistema de GreenPay. Estos métodos permiten crear un token de una tarjeta utilizando algoritmos de cifrado, permitiendo guardar la información de las tarjetas de forma segura, para luego utilizarse para realizar transacciones usando únicamente el ID del token.
\nEn greenpay/tokenization-v2 puede encontrar un ejemplo desarrollado con NodeJs.
\nPara utilizar este servicio es necesario crear una orden de tokenización y luego ejecutarla con los datos de la tarjeta hasheados según se muestra en los ejemplos siguientes:
\n","_postman_id":"05069ad2-33c9-44e0-927a-356368b274e7"},{"name":"3DS","item":[{"name":"PA SETUP","event":[{"listen":"test","script":{"id":"aead09e8-1a83-440c-95ef-791e25ca15e4","exec":["var jsonData = JSON.parse(responseBody);","postman.setEnvironmentVariable(\"referenceId\", jsonData.result.referenceId);","postman.setEnvironmentVariable(\"transactionId\", jsonData.result.transaction.id);"],"type":"text/javascript","packages":{}}}],"id":"22830e44-251b-422d-ba36-cd9ab44a5848","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"session-token","value":"{{ID de token obtenido al momento de crear la orden de pago o tokenizacion}}"}],"body":{"mode":"raw","raw":"{\n \"cardData\": {\n \"session\": \"{{ID de sesión obtenido al momento de crear la orden de pago o tokenizacion}}\",\n \"ed\": \"{{Información de la tarjeta codificada en base64}}\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://checkoutv2.greenpaysbx.me/3ds/setup","description":"> Descripción: Este endpoint permite realizar el Setup o Configuración Inicial de la Autenticación del Pago utilizando los servicios de Cybersource 3DS.
\nEl Setup 3DS retorna un objeto JSON con la información devuelta por Cybersource para ejecutar el proceso de recolección de información del tarjeta habiente y su dispositivo; y también devuelve la información de la transacción creada en GreenPay para su posterior procesamiento.
\nRealiza una solicitud al endpoint correspondiente para crear una orden de pago.Valores que obtendrás:
\nsession: Identificador de la sesión de la orden de pago (UUID)token: Token de seguridad para la sesión (UUID)Guarda los valores de session y token, ya que serán requeridos para el setup 3DS.
El header session-token es obligatorio y debe ser enviado en cada solicitud a este endpoint.
Ejemplo de session-token (UUID):
\n79b9b0-917d-11ef-8a48-19ee98944b83\n\n{\n \"cardData\": {\n \"session\": \"\",\n \"ed\": \"\"\n }\n}\n\n{\n \"card\": {\n \"cardHolder\": \"John Doe\",\n \"expirationDate\": {\n \"month\": \"12\",\n \"year\": \"31\"\n },\n \"cardNumber\": \"5597270000001815\",\n \"cvc\": \"196\"\n },\n \"additional\": { \n \"channelData\": { \n \"channel\": \"01\", \n \"source\": \"API_CARD\" \n } \n }\n}\n\nEl HTTP code (código de estado HTTP) es un número que indica el resultado de una solicitud HTTP:
\n{\n \"statusCode\": 200,\n \"result\": {\n \"id\": \"7497614919326700604807\",\n \"status\": \"COMPLETED\",\n \"jwt\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI0N2Q5MDIxYy01MjFkLTRhMzMtODU4Ny0wMjBiMWU1MzFlMGQiLCJpYXQiOjE3NDk3NjE0OTIsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTc0OTc2NTA5MiwiT3JnVW5pdElkIjoiNjYwYzBhOGRkYmYzZGUwMTZkNDc4ZWIxIiwiUmVmZXJlbmNlSWQiOiJiOGViNjdlNy1iNTVhLTQyNzgtOGIwYi0yYjlkZDc1MDZlZjAifQ.E6WmdgsAErA58FGya7ezOqwvo8M6ipCBkGZHfXtww7s\",\n \"referenceId\": \"b8eb67e7-b55a-4278-8b0b-2b9dd7506ef0\",\n \"deviceDataCollectionUrl\": \"https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect\",\n \"code\": \"aa6b2d21-3775-4d40-a59b-714873b3afe1\",\n \"transaction\": {\n \"id\": \"aa6b2d21-3775-4d40-a59b-714873b3afe1\",\n \"status\": \"CYBS_PA_SETUP\",\n \"description\": \"Demo Payment 97592\",\n \"authorization\": \"\",\n \"webhook_url\": \"https://webhook.site/940cf625-447e-4da3-8eac-be7c2470ee0f\",\n \"customer\": {\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"identification\": \"123456789\",\n \"billingAddress\": {\n \"country\": \"US\",\n \"province\": \"California\",\n \"city\": \"Los Angeles\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"zip\": \"90001\"\n },\n \"shippingAddress\": {\n \"country\": \"US\",\n \"province\": \"California\",\n \"city\": \"Los Angeles\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"zip\": \"90001\"\n }\n },\n \"entity_response\": \"\",\n \"card\": {\n \"bin\": \"445653\",\n \"brand\": \"Visa\",\n \"last4\": \"1096\"\n },\n \"quota\": 0\n }\n }\n}\n\n> IMPORTANTE:
\nSiempre validar result.transaction.status === 'CYBS_PA_SETUP'
> Si el setup es exitoso, el estado a validar es result.transaction.status === 'CYBS_PA_SETUP'
> Si el setup es exitoso, se debe recolectar los datos del navegador tal como pide 3DS
\n> Para ejecutar el enrollment se debe esperar la respuesta de recolección de datos
\n> Tener en consideración que el HTTP status puede ser 200 pero siempre validar el result.transaction.status como se menciona
{\n \"result\": {\n \"error\": {\n \"status\": 400,\n \"reason\": \"undefined - undefined\",\n \"message\": \"Error al realizar la operación\"\n },\n \"statusCode\": 400,\n \"status\": \"fail\",\n \"orderId\": \"Prueba\",\n \"token\": \"20d74179-b30b-474a-827c-de361a6d3260\",\n \"transactionId\": \"1c738200-c322-4f22-864c-8af39aeedebb\",\n \"amount\": 2000,\n \"currency\": \"CRC\",\n \"transaction\": {\n \"id\": \"1c738200-c322-4f22-864c-8af39aeedebb\",\n \"currency\": \"CRC\",\n \"amount\": 2000,\n \"reference_number\": \"prueba\",\n \"merchant_id\": \"d079b971-26ec-4833-80bb-7f2de5d63f56\",\n \"terminal\": \"bb37db9f-26f0-4e4f-9d74-c70f9be4ef9f\",\n \"internal_ref\": 6207483762900,\n \"quota\": 0,\n \"status\": \"FAILED\",\n \"created_at\": \"2025-06-19T13:54:07.880Z\",\n \"updated_at\": \"2025-06-19T13:54:07.880Z\",\n \"merchant_name\": \"3DS prueba\",\n \"statusCode\": 201,\n \"entity_response\": {},\n \"orderReference\": \"Test\"\n },\n \"quota\": 0,\n \"cause\": {\n \"origin\": \"AFPASETUP3DS\"\n }\n }\n}\n\n> IMPORTANTE:
\nValidar siempre result.transaction.status === 'FAILED' significa error
> Para obtener el string de error recomendamos:
\n let errorMessage = result?.error?.message ?? result.error\n\n> Tener en consideración que el HTTP status puede ser 200 pero siempre validar el result.transaction.status como se menciona
{\n \"message\": \"Event object failed validation\",\n \"status\": 400\n}\n\n> En este caso:
\n> Cuando es este caso, tener en cuenta que la estructura de error cambia y el mensaje de error viene en message
> En este caso el HTTP code es 400 y es el único caso
\n> Validar que esté mandando bien las keys del objeto
\nDespués de recibir una respuesta exitosa del setup 3DS, es obligatorio crear un iFrame para la recolección de datos del dispositivo del usuario. Esta recolección debe completarse antes de continuar con el proceso de enrollment.
\nconst createiFrameSetup3DS = async (data: Setup3dsResponseInterface) => {\n // Crear el iframe para la recolección de datos del navegador\n const iframe = document.createElement('iframe')\n iframe.width = '10'\n iframe.height = '10'\n iframe.id = 'cardinal_collection_iframe'\n iframe.name = 'collectionIframe'\n iframe.style.display = 'none'\n document.body.appendChild(iframe)\n // Crear el formulario para enviar los datos\n const form = document.createElement('form')\n form.method = 'POST'\n form.id = 'cardinal_collection_form'\n form.target = 'collectionIframe'\n form.action = data?.result?.deviceDataCollectionUrl\n // Crear el input con el JWT\n const input = document.createElement('input')\n input.id = 'cardinal_collection_form_input'\n input.type = 'hidden'\n input.name = 'JWT'\n input.value = data?.result?.jwt\n form.appendChild(input)\n document.body.appendChild(form)\n // Enviar el formulario para la recolección de datos del navegador\n const cardinalCollectionForm = document.querySelector('#cardinal_collection_form')\n if (cardinalCollectionForm) {\n (cardinalCollectionForm as HTMLFormElement).submit()\n }\n}\n\nuseEffect(() => {\n const handleMessage = async (event: MessageEvent) => {\n if (event.origin === process.env.NEXT_PUBLIC_CARDINAL_COMMERCE_URL) {\n console.log('event recollection', event)\n // Continuar con el proceso después de la recolección exitosa\n await handleContinueAfterRecollection()\n }\n }\n window.addEventListener('message', handleMessage, { once: true })\n return () => {\n window.removeEventListener('message', handleMessage)\n }\n}, [setup3dsData, handleContinueAfterRecollection])\n\nPara validar correctamente el origen del evento de recolección de datos, debes configurar la variable de entorno NEXT_PUBLIC_CARDINAL_COMMERCE_URL con los siguientes valores:
\nPara Pruebas (Staging):
\nNEXT_PUBLIC_CARDINAL_COMMERCE_URL=https://centinelapistag.cardinalcommerce.com\n\nPara Producción:
\nNEXT_PUBLIC_CARDINAL_COMMERCE_URL=https://centinelapi.cardinalcommerce.com\n\nPara ver un ejemplo completo de implementación del Setup 3DS con NextJS, incluyendo la creación de iFrames, manejo de eventos y flujo completo, puedes consultar el repositorio oficial:
\n\nEste repositorio contiene:
\n> Descripción:
\nEste endpoint permite realizar el procesamiento de verificación de la información del tarjeta habiente y su dispositivo, para autenticar dicha información o en su debido caso, solicitar un código de autorización enviado por el emisor de la tarjeta.
\nEl Enrollment 3DS retorna un objeto JSON que permite mostrar un cuadro de diálogo para ingresar el código de autorización enviado por el emisor de la tarjeta o la información de la autenticidad de la transacción.
\nEjecutar correctamente el PA SETUP
\nEjecutar correctamente el script de recolección de información recibido en la respuesta del PA SETUP
\nCodificar datos en formato base64
\nRealiza una solicitud al endpoint de Setup 3DS para obtener la configuración inicial.Valores que obtendrás:
\nreferenceId: Identificador de referencia del setup
code: Código de transacción del setup
deviceDataCollectionUrl: URL para recolección de datos del navegador
El header session-token es obligatorio y debe ser enviado en cada solicitud a este endpoint.
\nEjemplo de session-token (UUID):
\nad79b9b0-917d-11ef-8a48-19ee98944b83\n\n{\n \"cardData\": {\n \"session\": \"\",\n \"ed\": \"\"\n },\n \"referenceId\": \"\",\n \"transactionId\": \"\",\n \"redirectURL\": \"\"\n}\n\n{\n \"card\": {\n \"cardHolder\": \"John Doe\",\n \"expirationDate\": {\n \"month\": \"12\",\n \"year\": \"31\"\n },\n \"cardNumber\": \"4456530000001096\",\n \"cvc\": \"196\"\n },\n \"additional\": { \n \"channelData\": { \n \"channel\": \"01\", \n \"source\": \"API_CARD\" \n } \n },\n // solo aplica para planes \n // campos requeridos para pagos con planes\n \"plan\": \"06ae4d6a-a55d-41b8-894e-be9b75c4f063\",\n \"quota\": 6, // DEBE ser número entero, NO string\n}\n\nℹ️ Nota sobre plan y quota:
Para realizar pagos con planes se deben enviar estos dos valores, estos valores los debe obtener mediante un endpoint que GreenPay Facilita, la documentacion del endpoint la puede encontrar en la Merchant/Plans en la documentacion de postman
\nEstos datos los tiene que solicitar mediante interfaz gráfica en su frontend, para revisar una integración por código puede revisar el siguiente ejemplo en NextJS
3DS
Sino utiliza pagos con Cuota y plan porfavor omitir estos campos.
\nSu terminal debe estar configurada para aceptar pagos con planes
\nEl HTTP code (código de estado HTTP) es un número que indica el resultado de una solicitud HTTP:
\n200 = Solicitud exitosa
\n400, 401, 404, 500, etc. = Solicitud fallida
\n{\n \"statusCode\": 200,\n \"result\": {\n \"id\": \"7497628457976252404806\",\n \"code\": \"90ee7b41-150e-44d8-83a2-bd19f2b67e77\",\n \"status\": \"AUTHENTICATION_SUCCESSFUL\",\n \"authenticationTransactionId\": \"qXw5s4DPNHxCUBSVmNY0\",\n \"acsTransactionId\": \"4447c975-d203-433f-89b2-70efba2334ef\",\n \"paresStatus\": \"Y\",\n \"threeDSServerTransactionId\": \"b5df9086-ebb1-4ceb-b87a-1f755fd5e1be\",\n \"veresEnrolled\": \"Y\",\n \"directoryServerTransactionId\": \"45e5737f-5d79-4cc4-ba31-11af6fb5735f\",\n \"error\": {},\n \"consumerAuthenticationInformation\": {\n \"acsTransactionId\": \"4447c975-d203-433f-89b2-70efba2334ef\",\n \"authenticationTransactionId\": \"qXw5s4DPNHxCUBSVmNY0\",\n \"cavv\": \"AJkBBkhgQQAAAE4gSEJydQAAAAA=\",\n \"ecommerceIndicator\": \"vbv\",\n \"eci\": \"05\",\n \"eciRaw\": \"05\",\n \"paresStatus\": \"Y\",\n \"specificationVersion\": \"2.2.0\",\n \"threeDSServerTransactionId\": \"b5df9086-ebb1-4ceb-b87a-1f755fd5e1be\",\n \"veresEnrolled\": \"Y\",\n \"xid\": \"AJkBBkhgQQAAAE4gSEJydQAAAAA=\",\n \"directoryServerTransactionId\": \"45e5737f-5d79-4cc4-ba31-11af6fb5735f\",\n \"acsOperatorID\": \"MerchantACS\",\n \"acsReferenceNumber\": \"CardinalACS\"\n },\n \"transaction\": {\n \"id\": \"90ee7b41-150e-44d8-83a2-bd19f2b67e77\",\n \"status\": \"SUCCESSFUL\",\n \"description\": \"Demo Payment 25447\",\n \"authorization\": \"831000\",\n \"webhook_url\": \"https://webhook.site/940cf625-447e-4da3-8eac-be7c2470ee0f\",\n \"customer\": {\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"identification\": \"123456789\",\n \"billingAddress\": {\n \"country\": \"US\",\n \"province\": \"California\",\n \"city\": \"Los Angeles\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"zip\": \"90001\"\n },\n \"shippingAddress\": {\n \"country\": \"US\",\n \"province\": \"California\",\n \"city\": \"Los Angeles\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"zip\": \"90001\"\n }\n },\n \"entity_response\": {\n \"_links\": {\n \"self\": {\n \"href\": \"/pts/v2/payments/7497628463896304604805\",\n \"method\": \"GET\"\n }\n },\n \"id\": \"7497628463896304604805\",\n \"submitTimeUtc\": \"2025-06-12T21:14:06Z\",\n \"status\": \"AUTHORIZED\",\n \"reconciliationId\": \"7497628463896304604805\",\n \"clientReferenceInformation\": {\n \"code\": \"90ee7b41-150e-44d8-83a2-bd19f2b67e77\"\n },\n \"processorInformation\": {\n \"approvalCode\": \"831000\",\n \"transactionId\": \"016153570198200\",\n \"networkTransactionId\": \"016153570198200\",\n \"responseCode\": \"00\",\n \"responseDetails\": \"ABC\",\n \"avs\": {\n \"code\": \"Y\",\n \"codeRaw\": \"Y\"\n },\n \"cardVerification\": {\n \"resultCode\": \"M\",\n \"resultCodeRaw\": \"M\"\n },\n \"merchantAdvice\": {\n \"code\": \"01\",\n \"codeRaw\": \"M001\"\n },\n \"consumerAuthenticationResponse\": {\n \"code\": \"2\",\n \"codeRaw\": \"2\"\n },\n \"systemTraceAuditNumber\": \"583908\",\n \"retrievalReferenceNumber\": \"516321583908\"\n },\n \"paymentAccountInformation\": {\n \"card\": {\n \"type\": \"001\"\n }\n },\n \"paymentInformation\": {\n \"card\": {\n \"type\": \"001\"\n },\n \"tokenizedCard\": {\n \"type\": \"001\"\n }\n },\n \"orderInformation\": {\n \"amountDetails\": {\n \"totalAmount\": \"212.00\",\n \"authorizedAmount\": \"212.00\",\n \"currency\": \"USD\"\n }\n }\n },\n \"orderReference\": \"compra-demo-payment-1-20250612-8825\",\n \"card\": {\n \"bin\": \"445653\",\n \"brand\": \"Visa\",\n \"last4\": \"1005\"\n },\n \"quota\": 0\n }\n }\n}\n\n> IMPORTANTE: Siempre validar result.transaction.status === 'SUCCESSFUL'
> Si el enrollment es exitoso sin fricción, el estado a validar es result.transaction.status === 'SUCCESSFUL'
> En este caso, la transacción está completa y no requiere validación adicional
\n{\n \"statusCode\": 200,\n \"result\": {\n \"id\": \"7497614952716702204807\",\n \"code\": \"aa6b2d21-3775-4d40-a59b-714873b3afe1\",\n \"status\": \"PENDING_AUTHENTICATION\",\n \"authenticationTransactionId\": \"36qIQUyJWCTEYnrVCvl0\",\n \"jwt\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI0OGE5MTMxYy1iN2M3LTQwMGEtYmIyYS1jN2U2ZTkzYmRlMzAiLCJpYXQiOjE3NDk3NjE0OTUsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTc0OTc2NTA5NSwiT3JnVW5pdElkIjoiNjYwYzBhOGRkYmYzZGUwMTZkNDc4ZWIxIiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovLzBtZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTWVyY2hhbnRBQ1NXZWIvY3JlcS5qc3AiLCJQYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNaTR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WVc1elNVUWlPaUkwWkRSa01UVTNPQzFtT1RneUxUUmtaVEF0WWpsaU9DMHpPVE5oTUdVNFpETTJaR01pTENKaFkzTlVjbUZ1YzBsRUlqb2lORFptWWpRMVlqa3ROR1l6TkMwMFpXUmhMV0ZtTURNdE1UZGhNamhtWlRVeE5XUTBJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2WlNJNklqQXlJbjAiLCJUcmFuc2FjdGlvbklkIjoiMzZxSVFVeUpXQ1RFWW5yVkN2bDAifSwiT2JqZWN0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0dXJuVXJsIjoiaHR0cHM6Ly9jaGVja291dHYyLmdyZWVucGF5c2J4Lm1lLzNkcy9yZWRpcmVjdCJ9.ugtYZ83sb4huZ9zo7HrSL3xVrj802aZ6iIOKWDPxtGs\",\n \"acsTransactionId\": \"46fb45b9-4f34-4eda-af03-17a28fe515d4\",\n \"acsUrl\": \"https://0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp\",\n \"challengeRequired\": \"N\",\n \"pareq\": \"eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI0ZDRkMTU3OC1mOTgyLTRkZTAtYjliOC0zOTNhMGU4ZDM2ZGMiLCJhY3NUcmFuc0lEIjoiNDZmYjQ1YjktNGYzNC00ZWRhLWFmMDMtMTdhMjhmZTUxNWQ0IiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0\",\n \"paresStatus\": \"C\",\n \"stepUpUrl\": \"https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp\",\n \"threeDSServerTransactionId\": \"4d4d1578-f982-4de0-b9b8-393a0e8d36dc\",\n \"veresEnrolled\": \"Y\",\n \"directoryServerTransactionId\": \"9b4c63ac-59ba-4b29-b13c-0b0fd3149c59\",\n \"error\": {\n \"code\": \"CONSUMER_AUTHENTICATION_REQUIRED\",\n \"message\": \"The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction.\"\n },\n \"consumerAuthenticationInformation\": {\n \"accessToken\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI0OGE5MTMxYy1iN2M3LTQwMGEtYmIyYS1jN2U2ZTkzYmRlMzAiLCJpYXQiOjE3NDk3NjE0OTUsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTc0OTc2NTA5NSwiT3JnVW5pdElkIjoiNjYwYzBhOGRkYmYzZGUwMTZkNDc4ZWIxIiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovLzBtZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTWVyY2hhbnRBQ1NXZWIvY3JlcS5qc3AiLCJQYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNaTR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WVc1elNVUWlPaUkwWkRSa01UVTNPQzFtT1RneUxUUmtaVEF0WWpsaU9DMHpPVE5oTUdVNFpETTJaR01pTENKaFkzTlVjbUZ1YzBsRUlqb2lORFptWWpRMVlqa3ROR1l6TkMwMFpXUmhMV0ZtTURNdE1UZGhNamhtWlRVeE5XUTBJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2WlNJNklqQXlJbjAiLCJUcmFuc2FjdGlvbklkIjoiMzZxSVFVeUpXQ1RFWW5yVkN2bDAifSwiT2JqZWN0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0dXJuVXJsIjoiaHR0cHM6Ly9jaGVja291dHYyLmdyZWVucGF5c2J4Lm1lLzNkcy9yZWRpcmVjdCJ9.ugtYZ83sb4huZ9zo7HrSL3xVrj802aZ6iIOKWDPxtGs\",\n \"acsTransactionId\": \"46fb45b9-4f34-4eda-af03-17a28fe515d4\",\n \"acsUrl\": \"https://0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp\",\n \"authenticationTransactionId\": \"36qIQUyJWCTEYnrVCvl0\",\n \"challengeRequired\": \"N\",\n \"pareq\": \"eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI0ZDRkMTU3OC1mOTgyLTRkZTAtYjliOC0zOTNhMGU4ZDM2ZGMiLCJhY3NUcmFuc0lEIjoiNDZmYjQ1YjktNGYzNC00ZWRhLWFmMDMtMTdhMjhmZTUxNWQ0IiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0\",\n \"paresStatus\": \"C\",\n \"specificationVersion\": \"2.2.0\",\n \"stepUpUrl\": \"https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp\",\n \"threeDSServerTransactionId\": \"4d4d1578-f982-4de0-b9b8-393a0e8d36dc\",\n \"veresEnrolled\": \"Y\",\n \"directoryServerTransactionId\": \"9b4c63ac-59ba-4b29-b13c-0b0fd3149c59\",\n \"acsOperatorID\": \"MerchantACS\",\n \"acsReferenceNumber\": \"CardinalACS\"\n },\n \"transaction\": {\n \"id\": \"aa6b2d21-3775-4d40-a59b-714873b3afe1\",\n \"status\": \"CYBS_PA_ENROLLMENT\",\n \"description\": \"Demo Payment 97592\",\n \"authorization\": \"\",\n \"webhook_url\": \"https://webhook.site/940cf625-447e-4da3-8eac-be7c2470ee0f\",\n \"customer\": {\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"identification\": \"123456789\",\n \"billingAddress\": {\n \"country\": \"US\",\n \"province\": \"California\",\n \"city\": \"Los Angeles\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"zip\": \"90001\"\n },\n \"shippingAddress\": {\n \"country\": \"US\",\n \"province\": \"California\",\n \"city\": \"Los Angeles\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"zip\": \"90001\"\n }\n },\n \"entity_response\": \"\",\n \"orderReference\": \"compra-demo-payment-1-20250612-4738\",\n \"card\": {\n \"bin\": \"445653\",\n \"brand\": \"Visa\",\n \"last4\": \"1096\"\n },\n \"quota\": 0\n }\n }\n}\n\n> IMPORTANTE:
\nSiempre validar result.transaction.status === 'CYBS_PA_ENROLLMENT'
> Si el enrollment requiere fricción, el estado a validar es result.transaction.status === 'CYBS_PA_ENROLLMENT'
> En este caso, se debe crear un iframe con los datos de la respuesta para que el usuario complete el challenge
\n> Se debe esperar la respuesta del orquestador de GreenPay en un evento específico para poder realizar el validate
\n{\n \"result\": {\n \"error\": {\n \"status\": 400,\n \"reason\": \"AFPAENROLLMENT3DS\",\n \"message\": \"Error to authorize Transaction veresEnrolled or paresStatus, please try again later.\"\n },\n \"statusCode\": 400,\n \"status\": \"fail\",\n \"orderId\": \"compra-demo-payment-1-20250612-7040\",\n \"token\": \"872d2033-ec0e-4c38-a119-a2920e55e8ca\",\n \"transactionId\": \"ffd8076a-6863-42aa-85eb-74a4b7e5b4c0\",\n \"amount\": 590,\n \"currency\": \"USD\",\n \"transaction\": {\n \"terminal\": \"e044afee-8861-4b9d-946b-1643656c82a5\",\n \"currency\": \"USD\",\n \"entity_response\": {},\n \"created_at\": \"2025-06-12T21:21:58.405Z\",\n \"reference_number\": \"compra-demo-payment-1-20250612-7040\",\n \"status\": \"FAILED\",\n \"merchant_name\": \"Comercio Pruebas 3DS\",\n \"source\": \"API_CARD\",\n \"cybersource_threeds_pa_setup\": {\n \"id\": \"7497633213356406204805\",\n \"code\": \"ffd8076a-6863-42aa-85eb-74a4b7e5b4c0\",\n \"deviceDataCollectionUrl\": \"https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect\",\n \"jwt\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI0MzE5ZjVlZS02ZTA3LTQwZGEtYjc0My02ODBhMmViZmE3NmQiLCJpYXQiOjE3NDk3NjMzMjEsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTc0OTc2NjkyMSwiT3JnVW5pdElkIjoiNjYwYzBhOGRkYmYzZGUwMTZkNDc4ZWIxIiwiUmVmZXJlbmNlSWQiOiI3MTAyYjgyNS00OGUwLTRjMjItYTExNS0wYzZlOWViOTIwYTMifQ.5q0S90C8bUKmPheGQoj6H23Q4lusaFooq6CZCNvT3CI\",\n \"referenceId\": \"7102b825-48e0-4c22-a115-0c6e9eb920a3\",\n \"status\": \"COMPLETED\"\n },\n \"updated_at\": \"2025-06-12T21:22:03.776Z\",\n \"redirectURL\": \"\",\n \"quota\": 0,\n \"webhook_url\": \"https://webhook.site/940cf625-447e-4da3-8eac-be7c2470ee0f\",\n \"internal_ref\": 16504873736157,\n \"amount\": 590,\n \"merchant_id\": \"004a16ef-1be2-4ada-91ef-6222a7c1930e\",\n \"customer\": {\n \"name\": \"John Doe\",\n \"shippingAddress\": {\n \"zip\": \"90001\",\n \"country\": \"US\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"province\": \"California\",\n \"city\": \"Los Angeles\"\n },\n \"identification\": \"123456789\",\n \"billingAddress\": {\n \"zip\": \"90001\",\n \"country\": \"US\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"province\": \"California\",\n \"city\": \"Los Angeles\"\n },\n \"email\": \"john.doe@example.com\"\n },\n \"authorizer\": \"cybersource\",\n \"id\": \"ffd8076a-6863-42aa-85eb-74a4b7e5b4c0\",\n \"description\": \"Demo Payment 12432\",\n \"authorization\": \"\",\n \"card\": {\n \"last4\": \"1815\",\n \"cardnumber\": \"559727******1815\",\n \"brand\": \"Mastercard\",\n \"khash\": \"559727ZKF70RXEIDPU2B\",\n \"bin\": \"559727\"\n },\n \"orderReference\": \"compra-demo-payment-1-20250612-7040\"\n },\n \"quota\": 0,\n \"last4\": \"1815\",\n \"brand\": \"Mastercard\",\n \"bin\": \"559727\",\n \"cause\": {\n \"origin\": \"AFPAENROLLMENT3DS\"\n }\n }\n}\n\n> IMPORTANTE:
\nSiempre validar result.transaction.status === 'FAILED'
> Para obtener el mensaje de error: errorMessage = result?.error?.message ?? result.error
> Tener en consideración que el HTTP status puede ser 200 pero siempre validar el result.transaction.status
{\n \"message\": \"Event object failed validation\",\n \"status\": 400\n}\n\n> IMPORTANTE: Cuando es este caso, tener en cuenta que la estructura de error cambia
\n> El mensaje de error viene en message
\n> En este caso el HTTP code es 400 y es el único caso
\nCuando el enrollment requiere fricción (result.transaction.status === 'CYBS_PA_ENROLLMENT'), se debe crear un iframe para que el usuario complete el challenge de autenticación.
const getWindowSize3DSChallenge = async (data: string | '') => {\n const decodedData = atob(data)\n const parsedData = JSON.parse(decodedData) as {\n challengeWindowSize: string\n }\n return parsedData?.challengeWindowSize\n}\n\nconst windowsSize = {\n '01': { width: '250px', height: '400px' },\n '02': { width: '390px', height: '400px' },\n '03': { width: '500px', height: '600px' },\n '04': { width: '600px', height: '400px' },\n '05': { width: '100%', height: '100%' }\n}\n\nconst createiFrame3DSEnrollment = async (data: Enrollment3DsResponseInterface) => {\n console.log('createiFrame3DSEnrollment', data)\n // Obtener el tamaño de la ventana del challenge\n const challengeWindowSize = await getWindowSize3DSChallenge(data?.result?.pareq)\n const ws = windowsSize[challengeWindowSize as keyof typeof windowsSize]\n // Crear el contenedor del iframe\n const div = document.createElement('div')\n div.className = 'div-iframe'\n // Crear el iframe\n const iframe = document.createElement('iframe')\n iframe.width = ws.width\n iframe.height = ws.height\n iframe.id = 'step_up_iframe'\n iframe.name = 'stepUpIframe'\n div.appendChild(iframe)\n document.body.appendChild(div)\n // Crear el formulario\n const form = document.createElement('form')\n form.method = 'POST'\n form.id = 'step_up_form'\n form.target = 'stepUpIframe'\n form.action = data?.result?.stepUpUrl || ''\n // Crear el input JWT\n const input = document.createElement('input')\n input.id = 'JWT'\n input.type = 'hidden'\n input.name = 'JWT'\n input.value = data?.result?.jwt || ''\n // Crear el input MD\n const input2 = document.createElement('input')\n input2.id = 'MD'\n input2.type = 'hidden'\n input2.name = 'MD'\n input2.value = data?.result?.code || ''\n form.appendChild(input)\n form.appendChild(input2)\n document.body.appendChild(form)\n}\n\n// Enviar el formulario para iniciar el challenge\nconst script = document.createElement('script')\nscript.type = 'text/javascript'\ndocument.head.appendChild(script)\nconst stepUpForm = document.getElementById('step_up_form') as HTMLFormElement\nif (stepUpForm) {\n stepUpForm.submit()\n}\n\nuseEffect(() => {\n const handleMessage = async (event: MessageEvent) => {\n // Verificar que el mensaje proviene del dominio de GP\n if (event.origin !== process.env.NEXT_PUBLIC_ORCHESTRATOR_URL) {\n return\n }\n console.log('handleMessage', event)\n // Comprobar el contenido del mensaje para cerrar el iframe\n if (event.data === 'closeIframe') {\n const iframe = document.getElementById('step_up_iframe')\n const divIframe = document.querySelector('.div-iframe') as HTMLDivElement\n if (iframe) {\n iframe.style.display = 'none'\n divIframe.style.display = 'none'\n // Continuar con la validación\n handleValidate3DS()\n }\n }\n }\n window.addEventListener('message', handleMessage, { once: true })\n return () => {\n window.removeEventListener('message', handleMessage)\n }\n}, [enrollment3dsData, handleValidate3DS])\n\nconst cleanupIframesAndForms = () => {\n const divIframe = document.querySelector('.div-iframe') as HTMLDivElement\n if (divIframe) {\n divIframe.remove()\n }\n const stepUpForm = document.getElementById('step_up_form')\n if (stepUpForm) {\n stepUpForm.remove()\n }\n const cardinalCollectionIframe = document.getElementById('cardinal_collection_iframe')\n if (cardinalCollectionIframe) {\n cardinalCollectionIframe.remove()\n }\n const cardinalCollectionForm = document.getElementById('cardinal_collection_form')\n if (cardinalCollectionForm) {\n cardinalCollectionForm.remove()\n }\n}\n\n# Staging\nNEXT_PUBLIC_ORCHESTRATOR_URL=https://checkoutv2.greenpaysbx.me\n# Production\nNEXT_PUBLIC_ORCHESTRATOR_URL=https://checkoutv2.greenpay.com\n\n# Staging\nNEXT_PUBLIC_CARDINAL_COMMERCE_URL=https://centinelapistag.cardinalcommerce.com\n# Production\nNEXT_PUBLIC_CARDINAL_COMMERCE_URL=https://centinelapi.cardinalcommerce.com\n\nconst handleContinueAfterRecollection = useCallback(async () => {\n try {\n setIsLoading(true)\n // Transformar datos de la tarjeta para 3DS\n const encryptedData = await paymentService.transformCardDataFor3DS(\n cardFormData as CardFormData,\n orderResponseData as OrderResponse\n )\n // Realizar el enrollment 3DS\n const enrollmentResponse = await paymentService.processEnrollment3DS(\n encryptedData,\n orderResponseData?.token as string,\n setup3dsData as Setup3dsResponseInterface\n )\n // Validar si la transacción fue exitosa y no hay fricción\n if (enrollmentResponse?.result?.transaction?.status === 'SUCCESSFUL') {\n if (cardFormData?.card.isFavorite) {\n await handleTokenizeCard(cardFormData)\n }\n return onSubmit(cardFormData!)\n }\n // Validar si hay error en el enrollment 3DS\n if (enrollmentResponse.result?.transaction.status === 'FAILED') {\n throw new Error(enrollmentResponse?.result?.error?.message ?? '')\n }\n // Validar si hay fricción en el enrollment 3DS\n if (\n enrollmentResponse?.result?.transaction.status === 'CYBS_PA_ENROLLMENT' &&\n enrollmentResponse?.result?.stepUpUrl\n ) {\n await createiFrame3DSEnrollment(enrollmentResponse)\n const script = document.createElement('script')\n script.type = 'text/javascript'\n document.head.appendChild(script)\n const stepUpForm = document.getElementById('step_up_form') as HTMLFormElement\n if (stepUpForm) {\n stepUpForm.submit()\n }\n return setEnrollment3dsData(enrollmentResponse)\n }\n } catch (error: any) {\n console.error('Error al procesar el pago:', error)\n setError(\n 'Ocurrió un error al procesar el pago. Por favor, intente nuevamente. ' +\n error?.message\n )\n } finally {\n setIsLoading(false)\n }\n}, [\n cardFormData,\n orderResponseData,\n setup3dsData,\n handleTokenizeCard,\n onSubmit,\n createiFrame3DSEnrollment\n])\n\nPara ver una implementación completa del flujo 3DS con enrollment, visita el repositorio de ejemplo:Repositorio: https://bitbucket.org/greeenpay/3ds-tokenization-nextjs/src/main/Este repositorio contiene una implementación completa en Next.js que demuestra:
\nSetup 3DS
\nRecolección de datos del navegador
\nEnrollment 3DS con y sin fricción
\nManejo de iframes para challenges
\nValidación 3DS
\nTokenización de tarjetas
\n> Descripción: Este endpoint permite realizar la validación respectiva del código de autorización enviado por el emisor de la tarjeta, ingresado por el tarjeta habiente en el proceso anterior (PA ENROLLMENT).
\nEste endpoint solo aplica para transacciones donde el enrrolment requiere verificacion(challenge o desafio)
\nEl Validate 3DS retorna un objeto JSON con el resultado de la validación del código de autorización enviado por el banco emisor de la tarjeta.
\nresult.transaction.status para determinar el resultado real de la transacciónRealiza una solicitud al endpoint de Enrollment 3DS para obtener la configuración inicial.Valores que obtendrás:
\nEl header session-token es obligatorio y debe ser enviado en cada solicitud a este endpoint.
\nEjemplo de session-token (UUID):
\nad79b9b0-917d-11ef-8a48-19ee98944b83\n\n{\n \"cardData\": {\n \"session\": \"\",\n \"ed\": \"\"\n },\n \"authenticationTransactionId\": \"\",\n \"transactionId\": \"\"\n}\n\n{\n \"card\": {\n \"cardHolder\": \"John Doe\",\n \"expirationDate\": {\n \"month\": \"12\",\n \"year\": \"31\"\n },\n \"cardNumber\": \"5597270000001815\",\n \"cvc\": \"196\"\n },\n \"additional\": { \n \"channelData\": { \n \"channel\": \"01\", \n \"source\": \"API_CARD\" \n } \n }\n}\n\nCRÍTICO: Siempre validar result.transaction.status para determinar el resultado real:
El HTTP status puede ser 200, pero la transacción puede haber fallado. Siempre verificar el status de la transacción.
\nPara obtener el mensaje de error, usar:
\nconst errorMessage = result?.error?.message ?? result.error
{\n \"result\": {\n \"statusCode\": 200,\n \"status\": \"success\",\n \"orderId\": \"compra-demo-payment-1-20250612-7040\",\n \"token\": \"872d2033-ec0e-4c38-a119-a2920e55e8ca\",\n \"transactionId\": \"ffd8076a-6863-42aa-85eb-74a4b7e5b4c0\",\n \"amount\": 590,\n \"currency\": \"USD\",\n \"transaction\": {\n \"terminal\": \"e044afee-8861-4b9d-946b-1643656c82a5\",\n \"currency\": \"USD\",\n \"entity_response\": {},\n \"created_at\": \"2025-06-12T21:21:58.405Z\",\n \"reference_number\": \"compra-demo-payment-1-20250612-7040\",\n \"status\": \"SUCCESSFUL\",\n \"merchant_name\": \"Comercio Pruebas 3DS\",\n \"source\": \"API_CARD\",\n \"cybersource_threeds_pa_setup\": {\n \"id\": \"7497633213356406204805\",\n \"code\": \"ffd8076a-6863-42aa-85eb-74a4b7e5b4c0\",\n \"deviceDataCollectionUrl\": \"https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect\",\n \"jwt\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"referenceId\": \"7102b825-48e0-4c22-a115-0c6e9eb920a3\",\n \"status\": \"COMPLETED\"\n },\n \"updated_at\": \"2025-06-12T21:22:03.776Z\",\n \"redirectURL\": \"\",\n \"quota\": 0,\n \"webhook_url\": \"https://webhook.site/940cf625-447e-4da3-8eac-be7c2470ee0f\",\n \"internal_ref\": 16504873736157,\n \"amount\": 590,\n \"merchant_id\": \"004a16ef-1be2-4ada-91ef-6222a7c1930e\",\n \"customer\": {\n \"name\": \"John Doe\",\n \"shippingAddress\": {\n \"zip\": \"90001\",\n \"country\": \"US\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"province\": \"California\",\n \"city\": \"Los Angeles\"\n },\n \"identification\": \"123456789\",\n \"billingAddress\": {\n \"zip\": \"90001\",\n \"country\": \"US\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"province\": \"California\",\n \"city\": \"Los Angeles\"\n },\n \"email\": \"john.doe@example.com\"\n },\n \"authorizer\": \"cybersource\",\n \"id\": \"ffd8076a-6863-42aa-85eb-74a4b7e5b4c0\",\n \"description\": \"Demo Payment 12432\",\n \"authorization\": \"831000\",\n \"card\": {\n \"last4\": \"1815\",\n \"cardnumber\": \"559727******1815\",\n \"brand\": \"Mastercard\",\n \"khash\": \"559727ZKF70RXEIDPU2B\",\n \"bin\": \"559727\"\n },\n \"orderReference\": \"compra-demo-payment-1-20250612-7040\"\n },\n \"quota\": 0,\n \"last4\": \"1815\",\n \"brand\": \"Mastercard\",\n \"bin\": \"559727\"\n }\n}\n\n{\n \"result\": {\n \"error\": {\n \"status\": 400,\n \"reason\": \"AFPAENROLLMENT3DS\",\n \"message\": \"Error to authorize Transaction veresEnrolled or paresStatus, please try again later.\"\n },\n \"statusCode\": 400,\n \"status\": \"fail\",\n \"orderId\": \"compra-demo-payment-1-20250612-7040\",\n \"token\": \"872d2033-ec0e-4c38-a119-a2920e55e8ca\",\n \"transactionId\": \"ffd8076a-6863-42aa-85eb-74a4b7e5b4c0\",\n \"amount\": 590,\n \"currency\": \"USD\",\n \"transaction\": {\n \"terminal\": \"e044afee-8861-4b9d-946b-1643656c82a5\",\n \"currency\": \"USD\",\n \"entity_response\": {},\n \"created_at\": \"2025-06-12T21:21:58.405Z\",\n \"reference_number\": \"compra-demo-payment-1-20250612-7040\",\n \"status\": \"FAILED\",\n \"merchant_name\": \"Comercio Pruebas 3DS\",\n \"source\": \"API_CARD\",\n \"cybersource_threeds_pa_setup\": {\n \"id\": \"7497633213356406204805\",\n \"code\": \"ffd8076a-6863-42aa-85eb-74a4b7e5b4c0\",\n \"deviceDataCollectionUrl\": \"https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect\",\n \"jwt\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"referenceId\": \"7102b825-48e0-4c22-a115-0c6e9eb920a3\",\n \"status\": \"COMPLETED\"\n },\n \"updated_at\": \"2025-06-12T21:22:03.776Z\",\n \"redirectURL\": \"\",\n \"quota\": 0,\n \"webhook_url\": \"https://webhook.site/940cf625-447e-4da3-8eac-be7c2470ee0f\",\n \"internal_ref\": 16504873736157,\n \"amount\": 590,\n \"merchant_id\": \"004a16ef-1be2-4ada-91ef-6222a7c1930e\",\n \"customer\": {\n \"name\": \"John Doe\",\n \"shippingAddress\": {\n \"zip\": \"90001\",\n \"country\": \"US\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"province\": \"California\",\n \"city\": \"Los Angeles\"\n },\n \"identification\": \"123456789\",\n \"billingAddress\": {\n \"zip\": \"90001\",\n \"country\": \"US\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"province\": \"California\",\n \"city\": \"Los Angeles\"\n },\n \"email\": \"john.doe@example.com\"\n },\n \"authorizer\": \"cybersource\",\n \"id\": \"ffd8076a-6863-42aa-85eb-74a4b7e5b4c0\",\n \"description\": \"Demo Payment 12432\",\n \"authorization\": \"\",\n \"card\": {\n \"last4\": \"1815\",\n \"cardnumber\": \"559727******1815\",\n \"brand\": \"Mastercard\",\n \"khash\": \"559727ZKF70RXEIDPU2B\",\n \"bin\": \"559727\"\n },\n \"orderReference\": \"compra-demo-payment-1-20250612-7040\"\n },\n \"quota\": 0,\n \"last4\": \"1815\",\n \"brand\": \"Mastercard\",\n \"bin\": \"559727\",\n \"cause\": {\n \"origin\": \"AFPAENROLLMENT3DS\"\n }\n }\n}\n\n{\n \"message\": \"Event object failed validation\",\n \"status\": 400\n}\n\nEste error ocurre cuando:
\n// Forma recomendada para obtener el mensaje de error\nconst errorMessage = result?.error?.message ?? result.error;\n\n# URL del endpoint de Validate 3DS\nVALIDATE_3DS_URL=https://api.greenpay.com/v2/3ds/validate\n# Token de sesión (obtenido al crear la orden)\nSESSION_TOKEN=ad79b9b0-917d-11ef-8a48-19ee98944b83\n\n// En 3ds-tokenization-nextjs/src/services/paymentService.ts\nasync processValidate3DS({\n encryptedData,\n sessionToken,\n setup3dsResponse,\n enrollment3dsResponse\n}: {\n encryptedData: CardEncryptedRequestData\n sessionToken: string\n setup3dsResponse: Setup3dsResponseInterface\n enrollment3dsResponse: Enrollment3DsResponseInterface\n}): Promise<Validate3DSResponseInterface> {\n try {\n const validateData = {\n cardDataa: {\n session: encryptedData.session,\n ed: encryptedData.ed\n },\n authenticationTransactionId:\n enrollment3dsResponse?.result.authenticationTransactionId,\n transactionId: setup3dsResponse.result?.transaction?.id,\n additional: {\n channelData: {\n channel: '01',\n source: 'API_CARD'\n }\n }\n }\n // Mostrar el JSON que se va a enviar\n console.log('JSON a enviar:', JSON.stringify(validateData, null, 2))\n const { data: response } = await axios({\n method: 'post',\n url: process.env.NEXT_PUBLIC_VALIDATE_ENDPOINT_V2,\n headers: {,\n 'session-token': sessionToken\n },\n data: validateData\n })\n console.log('Respuesta validate 3DS:', response)\n return response\n } catch (error) {\n mapHttpError(error)\n throw error\n }\n}\n\nPara ver una implementación completa del flujo 3DS, incluyendo Validate, visita: https://bitbucket.org/greeenpay/3ds-tokenization-nextjs/src/main/ Este repositorio incluye ejemplos completos de:
\nLos siguientes métodos son utilizados para 3DS y liquidación de transacciones con 3DS
\nPuede revisar el ejemplo de código creado con NodeJS y Javascript en nuestro repositorio de código Ejemplo 3DS API
\n","_postman_id":"6432edfb-65a7-4cdd-93ea-4168864b1ae8"},{"name":"Token Payment","item":[{"name":"checkout payment with token","id":"66fd379f-f4ee-4c63-a7f3-7f0ce5900ac9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"secret\": \"{{Secret provisto por GreenPay}}\",\n \"merchantId\": \"{{Merchant ID provisto por GreenPay}}\",\n \"terminal\": \"\",\n \"amount\": 176,\n \"currency\": \"CRC\",\n \"description\": \"Compra producto 912\",\n \"orderReference\": \"compra-token-19-CRC-626\",\n \"token\": \"8a655ae0-34c3-11ef-91b4-6b798695d25d\",\n \"additional\": {\n \"customer\": {\n \"email\": \"agonzalez@greenpay.me\",\n \"name\": \"Angel Gonzalez\",\n \"billingAddress\": {\n \"country\": \"CR\",\n \"province\": \"Alajuela\",\n \"city\": \"Alajuela\"\n }\n }\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://checkoutv2.greenpaysbx.me/tokenPayment","description":"Este endpoint permite realizar un pago/autorización utilizando un token de tarjeta generado previamente mediante el proceso de tokenización.
\nAntes de poder realizar un pago con token, es necesario haber tokenizado la tarjeta del cliente utilizando el endpoint de tokenización.
\nObtendrás el valor importante:
\ntoken: Token de la tarjeta generado por GreenPay.
\nGuarda el valor de token, ya que será requerido para realizar el pago con token.
\nMétodo: POST
\nProducción: https://checkoutv2.greenpay.me/tokenPayment
\nRequiere conexión segura: Sí, bajo TLS 1.2.
\n{\n \"merchantId\": \"6e792b4c-1f95-4895-9434-d6d4aa38d491\",\n \"terminal\": \"b1249250-e620-11ee-a8be-d1e162aad25c\",\n \"amount\": 10.26,\n \"currency\": \"USD\",\n \"description\": \"Pago de orden 12345\",\n \"orderReference\": \"orden-12345\",\n \"token\": \"ecd78460-9318-11ef-8a48-19ee98944b83\",\n \"additional\": {\n \"customer\": {\n \"name\": \"John Doe\",\n \"email\": \"john.doe@email.com\",\n \"billingAddress\": {\n \"country\": \"CR\",\n \"province\": \"San Jose\",\n \"city\": \"San Jose\",\n \"street1\": \"Calle 1\",\n \"street2\": \"Apt 2\",\n \"zip\": \"10101\"\n },\n \"shippingAddress\": {\n \"country\": \"CR\",\n \"city\": \"San Jose\",\n \"street1\": \"Calle 1\",\n \"street2\": \"Apt 2\",\n \"zip\": \"10101\"\n }\n },\n \"products\": [\n {\n \"description\": \"Producto 1\",\n \"skuId\": \"SKU123\",\n \"quantity\": 1,\n \"price\": 10.26,\n \"type\": \"servicio\"\n }\n ]\n }\n}\n\nEl campo products dentro de additional es opcional.
Si se incluye la key products, todos los campos de cada producto son obligatorios.
Ejemplo de uso de productos:
\n\"products\": [\n {\n \"description\": \"Producto 1\",\n \"skuId\": \"SKU123\",\n \"quantity\": 1,\n \"price\": 10.26,\n \"type\": \"servicio\"\n }\n]\n\nHTTP 200
\n{\n \"status\": 200,\n \"orderId\": \"compra-token-19-CRC-185\",\n \"authorization\": \"831000\",\n \"amount\": 480,\n \"currency\": \"USD\",\n \"token\": \"ecd78460-9318-11ef-8a48-19ee98944b83\",\n \"internalRef\": 12713163835292,\n \"transactionId\": \"8b666759-555e-48dd-bfbf-2ef4123f37f9\",\n \"errors\": [],\n \"last4\": \"1815\",\n \"brand\": \"Mastercard\"\n}\n\n> El campo authorization es el código de autorización bancaria de la transacción.
HTTP diferente de 200
\n{\n \"status\": 500,\n \"orderId\": \"compra-token-19-CRC-776\",\n \"authorization\": null,\n \"amount\": 43,\n \"currency\": \"CRC\",\n \"token\": null,\n \"internalRef\": 9431670795786,\n \"transactionId\": \"41d7a4ed-1030-495e-ae35-ac32e667a4fa\",\n \"errors\": [\n \"Fondos insuficientes\"\n ]\n}\n\n⚡ ¿Cómo funciona el Webhook?
\nLa URL del webhook debe ser configurada previamente desde el dashboard de GreenPay.
\nPara este endpoint de pago con token, la respuesta será enviada a la URL raíz del webhook que hayas configurado para tu comercio, agregando el path /tokenPayment.
\nEjemplo: Si tu webhook es https://mywebhook.com/, la respuesta del pago con token por API llegará a la url https://mywebhook.com/tokenPayment.
\nGreenPay agregará el path /tokenPayment, esa url debe existir en tu backend.
\n🟢 status: 200 en el campo status de la respuesta del webhook indica un pago exitoso.
\n{\n \"status\": 200,\n \"orderId\": \"compra-token-19-CRC-185\",\n \"authorization\": \"831000\",\n \"amount\": 480,\n \"currency\": \"USD\",\n \"token\": \"ecd78460-9318-11ef-8a48-19ee98944b83\",\n \"internalRef\": 12713163835292,\n \"transactionId\": \"8b666759-555e-48dd-bfbf-2ef4123f37f9\",\n \"errors\": [],\n \"last4\": \"1815\",\n \"brand\": \"Mastercard\"\n}\n\n🔴 status: 400 en el campo status de la respuesta del webhook indica un pago fallido.
\n{\n \"status\": 400,\n \"orderId\": \"compra-token-19-556\",\n \"authorization\": null,\n \"amount\": 394,\n \"currency\": \"CRC\",\n \"token\": \"aecef530-2b67-11f0-88c5-f347f8450491\",\n \"internalRef\": 3227081501494,\n \"transactionId\": \"4d874109-79a1-4930-9e59-93ddb9ce233a\",\n \"errors\": [\n \"token no encontrado\"\n ],\n \"last4\": null,\n \"brand\": null\n}\n\nEl campo status con valor diferente de 200 indica un pago fallido en la respuesta del webhook.
\n","urlObject":{"path":["tokenPayment"],"host":["https://checkoutv2.greenpaysbx.me"],"query":[],"variable":[]}},"response":[{"id":"ffdbb681-80d6-46ed-bfd4-c71f493f76b4","name":"Transaccion Exitosa","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"secret\": \"{{Secret provisto por GreenPay}}\",\n \"merchantId\": \"{{Merchant ID provisto por GreenPay}}\",\n \"terminal\": \"\",\n \"amount\": 359,\n \"currency\": \"CRC\",\n \"description\": \"Compra producto 315\",\n \"orderReference\": \"compra-token-Sept-18-CRC-433\",\n \"token\":\"8a655ae0-34c3-11ef-91b4-6b798695d25d\",\n \"additional\": {\n \"customer\": {\n \"name\": \"Jairo Bonilla\",\n \"email\": \"agonzalez@greenpay.com\",\n \"billingAddress\": {\n \"country\": \"CR\",\n \"province\": \"Nombre de la provincia\",\n \"city\": \"Ciudad\",\n \"street1\": \"Dirección Calle 1\",\n \"street2\": \"Dirección Calle 2\",\n \"zip\": \"código postal\"\n },\n \"shippingAddress\": {\n \"country\": \"CR\",\n \"province\": \"Nombre de la provincia\",\n \"city\": \"Ciudad\",\n \"street1\": \"Dirección Calle 1\",\n \"street2\": \"Dirección Calle 2\",\n \"zip\": \"código postal\"\n }\n },\n \"products\": [{\n \"description\": \"Descripción de producto\",\n \"skuId\": \"Identificador único en el comercio\",\n \"quantity\": 1,\n \"price\": 289,\n \"type\": \"Tipo de producto\"\n }]\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://checkoutv2.greenpaysbx.me/tokenPayment"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": 200,\n \"orderId\": \"compra-token-19-CRC-409\",\n \"authorization\": \"172012\",\n \"amount\": 116,\n \"currency\": \"CRC\",\n \"token\": \"8a655ae0-34c3-11ef-91b4-6b798695d25d\",\n \"internalRef\": 3924210174186,\n \"transactionId\": \"5ebc599a-d3ef-413b-98a9-1548388a5501\",\n \"errors\": [],\n \"last4\": \"9358\",\n \"brand\": \"Visa\",\n \"quota\": 0\n}"},{"id":"7f4a69d0-8803-4814-b11c-ba5495be30cc","name":"Transaccion Exitosa solo campos requeridos","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"secret\": \"{{Secret provisto por GreenPay}}\",\n \"merchantId\": \"{{Merchant ID provisto por GreenPay}}\",\n \"terminal\": \"\",\n \"amount\": 557,\n \"currency\": \"CRC\",\n \"description\": \"Compra producto 417\",\n \"orderReference\": \"compra-token-Sept-18-CRC-724\",\n \"token\":\"8a655ae0-34c3-11ef-91b4-6b798695d25d\",\n \"additional\": {\n \"customer\": {\n \"name\": \"Jairo Bonilla\",\n \"email\": \"agonzalez@greenpay.com\",\n \"billingAddress\": {\n \"country\": \"CR\",\n \"province\": \"Nombre de la provincia\",\n \"city\": \"Ciudad\",\n \"street1\": \"Dirección Calle 1\",\n \"street2\": \"Dirección Calle 2\",\n \"zip\": \"código postal\"\n },\n \"shippingAddress\": {\n \"country\": \"CR\",\n \"province\": \"Nombre de la provincia\",\n \"city\": \"Ciudad\",\n \"street1\": \"Dirección Calle 1\",\n \"street2\": \"Dirección Calle 2\",\n \"zip\": \"código postal\"\n }\n },\n \"products\": [{\n \"description\": \"Descripción de producto\",\n \"skuId\": \"Identificador único en el comercio\",\n \"quantity\": 1,\n \"price\": 449,\n \"type\": \"Tipo de producto\"\n }]\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://checkoutv2.greenpaysbx.me/tokenPayment"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": 200,\n \"orderId\": \"compra-token-19-CRC-409\",\n \"authorization\": \"172012\",\n \"amount\": 116,\n \"currency\": \"CRC\",\n \"token\": \"8a655ae0-34c3-11ef-91b4-6b798695d25d\",\n \"internalRef\": 3924210174186,\n \"transactionId\": \"5ebc599a-d3ef-413b-98a9-1548388a5501\",\n \"errors\": [],\n \"last4\": \"9358\",\n \"brand\": \"Visa\",\n \"quota\": 0\n}"},{"id":"b1796b28-ae93-4c26-aaa9-12ae0f8581f9","name":"Transaccion Fallida","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"secret\": \"{{Secret provisto por GreenPay}}\",\n \"merchantId\": \"{{Merchant ID provisto por GreenPay}}\",\n \"terminal\": \"\",\n \"amount\": 100,\n \"currency\": \"CRC\",\n \"description\": \"Compra producto 214\",\n \"orderReference\": \"compra-token-19-CRC-657\",\n \"token\": \"8a655ae0-34c3-11ef-91b4-6b798695d25d\",\n \"additional\": {\n \"customer\": {\n \"email\": \"agonzalez@greenpay.me\",\n \"name\": \"Angel Gonzalez\",\n \"billingAddress\": {\n \"country\": \"CR\",\n \"province\": \"Alajuela\",\n \"city\": \"Alajuela\"\n }\n }\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://checkoutv2.greenpaysbx.me/tokenPayment"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"Error: invalid currency\",\n \"status\": \"fail\"\n}"}],"_postman_id":"66fd379f-f4ee-4c63-a7f3-7f0ce5900ac9"}],"id":"0f4463c1-894a-4f80-9bfe-9bbb131e7e23","_postman_id":"0f4463c1-894a-4f80-9bfe-9bbb131e7e23","description":""},{"name":"CheckoutForm","item":[],"id":"9f1caf05-d27f-45a4-aab1-968379e31c67","description":"En este apartado encontrará información acerca del checkoutform V2 y las respuestas del callback del checkoutform con 3DS y sin 3DS.
\nRealiza una solicitud al endpoint correspondiente para crear una orden de pago.
\nObtendrás dos valores importantes:
\nsession: Identificador de la sesión de la orden de pago (UUID).
token: Token de seguridad para la sesión (UUID).
Una vez creada la orden de pago y obtenido el session, el siguiente paso es redireccionar al usuario al Checkout Form de GreenPay.
\nEsto le permitirá ingresar los datos de su tarjeta de forma segura y completar el pago.
\nPara realizar la redirección, debes tomar el valor de session y agregarlo al final de la URL del Checkout Form, como se muestra a continuación.URLs del Checkout Form:
\nSandbox: https://checkoutform.greenpaysbx.me/v2/{session}
Producción: https://checkout-form.greenpay.me/v2/{session}
Donde {session} es el identificador de la sesión devuelto por GreenPay V2 al generar la orden de pago.
\nEl checkoutform puede responder con los datos de la respuesta de la transacción por medio de un callback que se envia al crear la orden de pago.
\nAl crear la orden debe agregar el campo callback en el objeto de la petición.
El checkoutform esta disponible para funcionar con 3DS ó sin 3DS, las respuestas del callback en cada caso son diferentes, a continuación se mostrará ejemplos de cada uno.
El callback responderá a la url que agrego como callback y agregará la respuesta en base64 de la siguiente manera:
http://localhost:3000/eyJzdGF0dXMiOjIwMCwib3JkZXJJZCI6ImNvbXByYS0yMDI0LTEwLTI4LVVTRC05MjgiLCJhdXRob3JpemF0aW9uIjoiODMxMDAwIiwiYW1vdW50IjozMSwiY3VycmVuY3kiOiJVU0QiLCJ0b2tlbiI6ImY0NjUyOGMwLTk1NGYtMTFlZi04NTAwLTI3ZjFhZDY5MWY3MSIsImludGVybmFsUmVmIjo2NTg3NDA4MTY0MjY0LCJ0cmFuc2FjdGlvbklkIjoiMTc1OGFmNzQtMzAyYy00NjAyLThmNDAtNjljMzBkZmYzOWNjIiwiZXJyb3JzIjpbXSwibGFzdDQiOiIxODE1IiwiYnJhbmQiOiJNYXN0ZXJjYXJkIiwic3RhdHVzQ29kZSI6MjAwfQ==\n\nSi esta usando el servicio de checkoutform V2 de GreenPay la respuesta del callback tiene la siguiente estructura.
\nj
\n{\n \"status\":200,\n \"orderId\":\"compra-2024-10-28-USD-928\",\n \"authorization\":\"831000\",\n \"amount\":31,\n \"currency\":\"USD\",\n \"token\":\"f46528c0-954f-11ef-8500-27f1ad691f71\",\n \"internalRef\":6587408164264,\n \"transactionId\":\"1758af74-302c-4602-8f40-69c30dff39cc\",\n \"errors\":[],\n \"last4\":\"1815\",\n \"brand\":\"Mastercard\",\n \"statusCode\":200,\n \"quota\":0\n}\n\n> Nota Importante: Si el status es 200, la transacción fue exitosa.
El campo quota es para transacciones a plazos, se establece por defecto en 0 en la respuesta. omitir este campo sino hace uso de transacciones a plazos.
{\n \"status\":400,\n \"errors\":[\n \"Error response here\"\n ]\n}\n\n> Nota Importante: Si el status es diferente de 200, la transacción fue fallida.
Debe tener en cuenta si utiliza el servicio de checkoutform con 3DS o no, porque las respuestas del callback son diferentes.
\n{\n \"id\":\"7364531994186889604805\",\n \"code\":\"1ef2ab78-da43-4dcf-a3fd-889cdfa2b117\",\n \"status\":\"AUTHENTICATION_SUCCESSFUL\",\n \"acsTransactionId\":\"57d34b40-39d9-48da-9eb8-9c883c18e977\",\n \"threeDSServerTransactionId\":\"e6404bc1-7ebe-4180-98d9-064f3659b8f4\",\n \"directoryServerTransactionId\":\"02eb689f-1405-4ffc-aee0-06f6db9347bf\",\n \"paresStatus\":\"Y\",\n \"consumerAuthenticationInformation\":{\n \"acsTransactionId\":\"57d34b40-39d9-48da-9eb8-9c883c18e977\",\n \"authenticationResult\":\"0\",\n \"authenticationStatusMsg\":\"Success\",\n \"cavv\":\"AAIBBYNoEwAAACcKhAJkdQAAAAA=\",\n \"indicator\":\"vbv\",\n \"eci\":\"05\",\n \"eciRaw\":\"05\",\n \"paresStatus\":\"Y\",\n \"specificationVersion\":\"2.2.0\",\n \"threeDSServerTransactionId\":\"e6404bc1-7ebe-4180-98d9-064f3659b8f4\",\n \"xid\":\"AAIBBYNoEwAAACcKhAJkdQAAAAA=\",\n \"directoryServerTransactionId\":\"02eb689f-1405-4ffc-aee0-06f6db9347bf\"\n },\n \"error\":{\n },\n \"transaction\":{\n \"id\":\"1ef2ab78-da43-4dcf-a3fd-889cdfa2b117\",\n \"status\":\"SUCCESSFUL\",\n \"description\":\"API-V2-USD\",\n \"authorization\":\"831000\",\n \"webhook_url\":\"https://webhook.site/c30917eb-812e-4305-bc5c-085b998f57aa\",\n \"customer\":{\n \"name\":\"Angel Gonzalez\",\n \"email\":\"agonzalez@greenpay.me\",\n \"identification\":\"124444\",\n \"billingAddress\":{\n \"country\":\"CR\",\n \"province\":\"Nombre de la provincia\",\n \"city\":\"Ciudad\",\n \"street1\":\"Direccin Calle 1\",\n \"street2\":\"Direccin Calle 2\",\n \"zip\":\"10801\"\n },\n \"shippingAddress\":{\n \"country\":\"CR\",\n \"province\":\"Nombre de la provincia\",\n \"city\":\"Ciudad\",\n \"street1\":\"Direccin Calle 1\",\n \"street2\":\"Direccin Calle 2\",\n \"zip\":\"10801\"\n }\n },\n \"entity_response\":{\n \"_links\":{\n \"self\":{\n \"href\":\"/pts/v2/payments/7364532025976890104805\",\n \"method\":\"GET\"\n }\n },\n \"id\":\"7364532025976890104805\",\n \"submitTimeUtc\":\"2025-01-09T20:06:42Z\",\n \"status\":\"AUTHORIZED\",\n \"reconciliationId\":\"7364532025976890104805\",\n \"clientReferenceInformation\":{\n \"code\":\"1ef2ab78-da43-4dcf-a3fd-889cdfa2b117\"\n },\n \"processorInformation\":{\n \"approvalCode\":\"831000\",\n \"transactionId\":\"016153570198200\",\n \"networkTransactionId\":\"016153570198200\",\n \"responseCode\":\"00\",\n \"responseDetails\":\"ABC\",\n \"avs\":{\n \"code\":\"Y\",\n \"codeRaw\":\"Y\"\n },\n \"merchantAdvice\":{\n \"code\":\"01\",\n \"codeRaw\":\"M001\"\n },\n \"consumerAuthenticationResponse\":{\n \"code\":\"2\",\n \"codeRaw\":\"2\"\n },\n \"systemTraceAuditNumber\":\"122267\",\n \"retrievalReferenceNumber\":\"500920122267\"\n },\n \"paymentAccountInformation\":{\n \"card\":{\n \"type\":\"001\"\n }\n },\n \"paymentInformation\":{\n \"card\":{\n \"type\":\"001\"\n },\n \"tokenizedCard\":{\n \"type\":\"001\"\n }\n },\n \"orderInformation\":{\n \"amountDetails\":{\n \"totalAmount\":\"10.00\",\n \"authorizedAmount\":\"10.00\",\n \"currency\":\"CRC\"\n }\n }\n },\n \"orderReference\":\"API-V2-CRC-2429\"\n }\n}\n\n> Nota Importante: transaction.status debe tener el valor SUCCESSFUL para que la transacción 3DS se considere exitosa.
Cualquier otro estado significa que la transacción no fue exitosa.
\n> Mensaje de Error: El mensaje de error se puede obtener de la respuesta con la siguiente lógica: error?.message ?? error.
{\n \"id\":\"7364573344956430904805\",\n \"status\":\"COMPLETED\",\n \"jwt\":\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI0OThiMzVkMS0zNjliLTQxODEtYWY2OC0wY2NmNWM3ZGRkMzciLCJpYXQiOjE3MzY0NTczMzQsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTczNjQ2MDkzNCwiT3JnVW5pdElkIjoiNjYwYzBhOGRkYmYzZGUwMTZkNDc4ZWIxIiwiUmVmZXJlbmNlSWQiOiJmODljMWMyZS03OWExLTQ2MjYtOTkwZC05NmNkNTYyZDFkNTIifQ.j61dk5sG_6I10VnzXb8bdjR8-LPVfcW8zNa5eREDlMs\",\n \"referenceId\":\"f89c1c2e-79a1-4626-990d-96cd562d1d52\",\n \"deviceDataCollectionUrl\":\"https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect\",\n \"code\":\"efbb1068-f1d6-48e9-b00f-f94cee4c2ceb\",\n \"transaction\":{\n \"id\":\"efbb1068-f1d6-48e9-b00f-f94cee4c2ceb\",\n \"status\":\"CYBS_PA_SETUP\",\n \"description\":\"API-V2-USD\",\n \"authorization\":\"\",\n \"webhook_url\":\"https://webhook.site/c30917eb-812e-4305-bc5c-085b998f57aa\",\n \"customer\":{\n \"name\":\"Angel Gonzalez\",\n \"email\":\"agonzalez@greenpay.me\",\n \"identification\":\"124444\",\n \"billingAddress\":{\n \"country\":\"CR\",\n \"province\":\"Nombre de la provincia\",\n \"city\":\"Ciudad\",\n \"street1\":\"Direccin Calle 1\",\n \"street2\":\"Direccin Calle 2\",\n \"zip\":\"10801\"\n },\n \"shippingAddress\":{\n \"country\":\"CR\",\n \"province\":\"Nombre de la provincia\",\n \"city\":\"Ciudad\",\n \"street1\":\"Direccin Calle 1\",\n \"street2\":\"Direccin Calle 2\",\n \"zip\":\"10801\"\n }\n },\n \"entity_response\":\"\"\n }\n}\n\n> Nota Importante: transaction.status debe tener el valor SUCCESSFUL para que la transacción 3DS se considere exitosa.
Cualquier otro estado significa que la transacción no fue exitosa.
\n> Mensaje de Error: El mensaje de error se puede obtener de la respuesta con la siguiente lógica: error?.message ?? error.
Si su webhook configurado es el siguiente https://mywebhook.com/ la respuesta del checkoutform sin 3DS llegará a la url https://mywebhook.com/. Esa url debe existir en su backend.
\n{\n \"status\": 200,\n \"orderId\": \"API-V2-CRC-8977\",\n \"authorization\": \"831000\",\n \"amount\": 10,\n \"currency\": \"USD\",\n \"token\": \"5ec57b60-d228-11ef-94e2-9dd36b69fec6\",\n \"internalRef\": 20363874316090,\n \"transactionId\": \"a22275c7-e327-4282-8c2e-727a60465eb2\",\n \"errors\": [],\n \"last4\": \"1815\",\n \"brand\": \"Mastercard\",\n \"quota\": 0\n}\n\n> Nota Importante: Si el status es 200, la transacción fue exitosa.
{\n \"status\": 500,\n \"orderId\": \"compra-2024-10-28-USD-842\",\n \"authorization\": null,\n \"amount\": 37,\n \"currency\": \"USD\",\n \"token\": null,\n \"internalRef\": 239443691564,\n \"transactionId\": \"e6afefac-5aed-4deb-96af-784241addc38\",\n \"errors\": [\n \"invalid PAN\"\n ],\n \"last4\": \"1811\",\n \"brand\": \"Mastercard\"\n}\n\n> Nota Importante: Si el status es diferente de 200, la transacción fue fallida.
\nSi su webhook configurado es el siguiente https://mywebhook.com/ la respuesta del checkoutform con 3DS llegará a la url https://mywebhook.com.
Esa url debe existir en su backend.
\n{\n \"id\":\"7369694598966319804807\",\n \"code\":\"f1795abb-4a24-47ad-839f-4a3c807dff6b\",\n \"status\":\"AUTHENTICATION_SUCCESSFUL\",\n \"authenticationTransactionId\":\"mtrggLeSN0o3V7cXKmk0\",\n \"acsTransactionId\":\"dab61d0b-258e-4b82-9ea3-853319541a90\",\n \"paresStatus\":\"Y\",\n \"threeDSServerTransactionId\":\"22737198-70ef-4332-b83e-a30351d896b4\",\n \"veresEnrolled\":\"Y\",\n \"directoryServerTransactionId\":\"7d501368-4ce6-4837-9d7f-87fe8f7191be\",\n \"error\":{\n },\n \"consumerAuthenticationInformation\":{\n \"acsTransactionId\":\"dab61d0b-258e-4b82-9ea3-853319541a90\",\n \"authenticationTransactionId\":\"mtrggLeSN0o3V7cXKmk0\",\n \"cavv\":\"AJkBBkhgQQAAAE4gSEJydQAAAAA=\",\n \"ecommerceIndicator\":\"vbv\",\n \"eci\":\"05\",\n \"eciRaw\":\"05\",\n \"paresStatus\":\"Y\",\n \"specificationVersion\":\"2.2.0\",\n \"threeDSServerTransactionId\":\"22737198-70ef-4332-b83e-a30351d896b4\",\n \"veresEnrolled\":\"Y\",\n \"xid\":\"AJkBBkhgQQAAAE4gSEJydQAAAAA=\",\n \"directoryServerTransactionId\":\"7d501368-4ce6-4837-9d7f-87fe8f7191be\",\n \"acsOperatorID\":\"MerchantACS\",\n \"acsReferenceNumber\":\"Cardinal ACS\"\n },\n \"transaction\":{\n \"id\":\"f1795abb-4a24-47ad-839f-4a3c807dff6b\",\n \"status\":\"SUCCESSFUL\",\n \"description\":\"API-V2-USD\",\n \"authorization\":\"831000\",\n \"webhook_url\":\"https://webhook.site/519b5827-82b9-49f6-9e78-1785d2c4d4da\",\n \"customer\":{\n \"name\":\"Angel Gonzalez\",\n \"email\":\"agonzalez@greenpay.me\",\n \"identification\":\"124444\",\n \"billingAddress\":{\n \"country\":\"CR\",\n \"province\":\"Nombre de la provincia\",\n \"city\":\"Ciudad\",\n \"street1\":\"Direccin Calle 1\",\n \"street2\":\"Direccin Calle 2\",\n \"zip\":\"10801\"\n },\n \"shippingAddress\":{\n \"country\":\"CR\",\n \"province\":\"Nombre de la provincia\",\n \"city\":\"Ciudad\",\n \"street1\":\"Direccin Calle 1\",\n \"street2\":\"Direccin Calle 2\",\n \"zip\":\"10801\"\n }\n },\n \"entity_response\":{\n \"_links\":{\n \"self\":{\n \"href\":\"/pts/v2/payments/7369694629396427104805\",\n \"method\":\"GET\"\n }\n },\n \"id\":\"7369694629396427104805\",\n \"submitTimeUtc\":\"2025-01-15T19:31:03Z\",\n \"status\":\"AUTHORIZED\",\n \"reconciliationId\":\"7369694629396427104805\",\n \"clientReferenceInformation\":{\n \"code\":\"f1795abb-4a24-47ad-839f-4a3c807dff6b\"\n },\n \"processorInformation\":{\n \"approvalCode\":\"831000\",\n \"transactionId\":\"016153570198200\",\n \"networkTransactionId\":\"016153570198200\",\n \"responseCode\":\"00\",\n \"responseDetails\":\"ABC\",\n \"avs\":{\n \"code\":\"Y\",\n \"codeRaw\":\"Y\"\n },\n \"merchantAdvice\":{\n \"code\":\"01\",\n \"codeRaw\":\"M001\"\n },\n \"consumerAuthenticationResponse\":{\n \"code\":\"2\",\n \"codeRaw\":\"2\"\n },\n \"systemTraceAuditNumber\":\"801618\",\n \"retrievalReferenceNumber\":\"501519801618\"\n },\n \"paymentAccountInformation\":{\n \"card\":{\n \"type\":\"001\"\n }\n },\n \"paymentInformation\":{\n \"card\":{\n \"type\":\"001\"\n },\n \"tokenizedCard\":{\n \"type\":\"001\"\n }\n },\n \"orderInformation\":{\n \"amountDetails\":{\n \"totalAmount\":\"10.00\",\n \"authorizedAmount\":\"10.00\",\n \"currency\":\"CRC\"\n }\n }\n },\n \"orderReference\":\"API-V2-CRC-7750\"\n }\n}\n\n> Nota Importante: transaction.status debe tener el valor SUCCESSFUL para que la transacción 3DS se considere exitosa.
Cualquier otro estado significa que la transacción no fue exitosa.
\n> Mensaje de Error: El mensaje de error se puede obtener de la respuesta con la siguiente lógica: error?.message ?? error.
{\n \"id\": \"7369699260036523404805\",\n \"code\": \"46550695-8654-4334-9e89-62fc58971936\",\n \"status\": \"AUTHENTICATION_SUCCESSFUL\",\n \"authenticationTransactionId\": \"oDm1ptLsYro9vmcbyZF0\",\n \"veresEnrolled\": \"U\",\n \"error\": {},\n \"consumerAuthenticationInformation\": {\n \"authenticationTransactionId\": \"oDm1ptLsYro9vmcbyZF0\",\n \"ecommerceIndicator\": \"internet\",\n \"proofXml\": \"<AuthProof><Time>2025 Jan 15 19:38:46</Time><DSUrl>https://1centineltest.cardinalcommerce.com/maps/txns.asp</DSUrl><VEReqProof><Message id=\\\"na\\\"><VEReq><version>1.0.2</version><pan>XXXXXXXXXXXX1815</pan><Merchant><acqBIN></acqBIN><merID></merID></Merchant><Browser><accept></accept><userAgent></userAgent></Browser></VEReq></Message></VEReqProof><VEResProof><Message id=\\\"na\\\"><VERes><version>1.0.2</version><CH><enrolled>U</enrolled><acctID></acctID></CH><url></url><protocol>ThreeDSecure</protocol></VERes></Message></VEResProof></AuthProof>\",\n \"ucafCollectionIndicator\": \"0\",\n \"veresEnrolled\": \"U\"\n },\n \"transaction\": {\n \"id\": \"46550695-8654-4334-9e89-62fc58971936\",\n \"status\": \"FAILED\",\n \"description\": \"API-V2-USD\",\n \"authorization\": \"\",\n \"webhook_url\": \"https://webhook.site/519b5827-82b9-49f6-9e78-1785d2c4d4da\",\n \"customer\": {\n \"name\": \"Angel Gonzalez\",\n \"email\": \"agonzalez@greenpay.me\",\n \"identification\": \"124444\",\n \"billingAddress\": {\n \"country\": \"CR\",\n \"province\": \"Nombre de la provincia\",\n \"city\": \"Ciudad\",\n \"street1\": \"Dirección Calle 1\",\n \"street2\": \"Dirección Calle 2\",\n \"zip\": \"10801\"\n },\n \"shippingAddress\": {\n \"country\": \"CR\",\n \"province\": \"Nombre de la provincia\",\n \"city\": \"Ciudad\",\n \"street1\": \"Dirección Calle 1\",\n \"street2\": \"Dirección Calle 2\",\n \"zip\": \"10801\"\n }\n },\n \"entity_response\": {},\n \"orderReference\": \"API-V2-CRC-1788\"\n }\n}\n\n> Nota Importante: transaction.status debe tener el valor SUCCESSFUL para que la transacción 3DS se considere exitosa. Cualquier otro estado significa que la transacción no fue exitosa.
> Mensaje de Error: El mensaje de error se puede obtener de la respuesta con la siguiente lógica: error?.message ?? error.
Este formulario permite tokenizar una tarjeta de crédito o débito de forma segura a través de una interfaz web proporcionada por GreenPay.
\nAntes de utilizar el formulario, es necesario crear una orden de tokenización mediante el endpoint correspondiente.
\nObtendrás los valores importantes:
\nsession: Identificador de la sesión de la orden de tokenización (UUID).
\ntoken: Token de seguridad de la orden de tokenización.
\nGuarda estos valores, ya que serán requeridos para redireccionar al formulario y completar el proceso de tokenización.
\nEl formulario de tokenización está disponible en:
\nSandbox: https://tokenization.greenpaysbx.me/
Producción: https://tokenization.greenpay.me/
Es necesario contar con una sesión y token de una orden de tokenización que no haya excedido los 30 minutos de vigencia.
\nEl formulario de tokenización de GreenPay solo está disponible para aplicaciones web.
\nEs fundamental redireccionar al usuario a la URL del formulario de GreenPay utilizando el identificador de sesión obtenido al crear la orden de tokenización.
\nEste paso es obligatorio para que el usuario pueda ingresar los datos de su tarjeta de forma segura.
\nhttps://tokenization.greenpaysbx.me/{session}
https://tokenization.greenpay.me/{session}
Donde {session} es el identificador de sesión obtenido al crear la orden de tokenización.
\n> Asegúrate de redireccionar exactamente a la URL proporcionada por GreenPay, incluyendo el valor de la sesión.
\nEs imprescindible que al crear la orden de tokenización, definas el parámetro callback con la URL a la que deseas recibir la respuesta del formulario.
\nGreenPay enviará la respuesta de la tokenización a esta URL una vez que el usuario complete el formulario.
\nEl parámetro callback debe ser una URL válida y accesible desde el navegador del usuario.
\nLa respuesta será enviada a esta URL, codificada en base64 como parte del path.
\nEjemplo de callback recibido
\nhttp://localhost/eyJzdGF0dXNDb2RlIjoyMDAsInJlc3VsdCI6eyJjYXJkSG9sZGVyIjoiQW5nZWwgR29uemFsZXoiLCJicmFuZCI6Ik1hc3RlcmNhcmQiLCJiaW4iOiI1NTk3MjciLCJsYXN0NCI6IjE4MTEiLCJraGFzaCI6IjU1OTcyNzY0T0lGTEVUVVlLUlREIiwidG9rZW4iOiI4MDNhYThiMC05NThkLTExZWYtOGE0OC0xOWVlOTg5NDRiODMiLCJjYXJkTWFza2VkIjoiNTU5NzI3KioqKioqMTgxMSJ9fQ==\n\nAl decodificar el base64, se obtiene un JSON como el siguiente:
\n{\n \"statusCode\": 200,\n \"result\": {\n \"cardHolder\": \"Angel Gonzalez\",\n \"brand\": \"Visa\",\n \"bin\": \"445653\",\n \"last4\": \"1096\",\n \"khash\": \"4456534XQYXTFNC7M08D\",\n \"token\": \"c02fe570-9588-11ef-bd8e-177728d45168\",\n \"cardMasked\": \"445653******1096\"\n }\n}\n\n> El campo result.token es el valor que debe guardarse en su base de datos para identificar la tarjeta de forma segura y realizar pagos futuros con token.
\n⚡ ¿Cómo funciona el Webhook?
\nLa URL del webhook debe ser configurada previamente desde el dashboard de GreenPay.
\nPara este endpoint de tokenización de tarjeta, la respuesta será enviada a la URL raíz del webhook que hayas configurado para tu comercio, agregando el path /tokenizeCard.
Ejemplo:
\nSi tu webhook es https://mywebhook.com/, la respuesta de la tokenización por API llegará a la url https://mywebhook.com/tokenizeCard.
GreenPay agregará el path /tokenizeCard, esa url debe existir en tu backend.
🟢 statusCode: 200 en el campo statusCode de la respuesta del webhook indica una tokenización exitosa.
\n{\n \"statusCode\": 200,\n \"result\": {\n \"cardHolder\": \"John Doe\",\n \"brand\": \"Visa\",\n \"bin\": \"455676\",\n \"last4\": \"6446\",\n \"khash\": \"455676SNB18A5F1T3QWC\",\n \"token\": \"b1249250-e620-11ee-a8be-d1e162aad25c\",\n \"cardMasked\": \"455676******6446\"\n }\n}\n\nstatusCode con valor 200 indica una tokenización exitosa en la respuesta del webhook.🔴 status: 400 en el campo status de la respuesta del webhook indica una tokenización fallida.
\n{\n \"status\": 400,\n \"orderId\": \"compra-token-19-556\",\n \"authorization\": null,\n \"amount\": 394,\n \"currency\": \"CRC\",\n \"token\": \"aecef530-2b67-11f0-88c5-f347f8450491\",\n \"internalRef\": 3227081501494,\n \"transactionId\": \"4d874109-79a1-4930-9e59-93ddb9ce233a\",\n \"errors\": [\n \"token no encontrado\"\n ],\n \"last4\": null,\n \"brand\": null\n}\n\nEn este apartado encontrará información sobre cómo obtener los datos del Data Collector, un componente requerido exclusivamente para integraciones que procesan transacciones con el servicio de antifraude de Greenpay.
\n⚠️ ¡Importante!
\nEste paso solo es necesario si tu integración requiere y tiene habilitado el análisis de fraude.
\nEl Data Collector es una herramienta que utiliza Greenpay para recolectar información del dispositivo y la sesión del usuario durante una transacción. Estos datos son analizados para detectar y prevenir posibles comportamientos de fraude, añadiendo una capa de seguridad a sus pagos.La recolección de estos datos se realiza en el frontend de su aplicación (página web).
\nLa integración consta de dos pasos principales:
\nAñada el siguiente script en el o de su página de pago.
\n<script src=\"https://static.greenpay.me/collector/1.0.1/GDataCollector.min.js\"></script>\n\nUna vez incluido el script, debe inicializar el Data Collector para que comience a recolectar la información.
\nEl resultado de este proceso es un identificador de sesión (MercSessId) que deberá ser enviado en las transacciones.
El método GDataCollector.init() recibe tres parámetros:
'sand' para Sandbox (pruebas) o 'prod' para Producción.<script>\n // Elemento donde se mostrará el ID de sesión (opcional, para depuración)\n let sessionIdDiv = document.getElementById(\"kountSession\");\n function kountSession(params) {\n // 1. Obtenemos el ID de sesión de Kount\n const kountSessionId = params.MercSessId;\n console.log(kountSessionId);\n // 2. Mostramos el ID de sesión (opcional)\n sessionIdDiv.innerHTML = `KOUNT SESSION ${kountSessionId}`;\n // 3. Aquí debes almacenar kountSessionId para usarlo en el pago.\n // Puedes guardarlo en una variable global, un campo de formulario oculto, etc.\n }\n // Inicializamos el Data Collector\n GDataCollector.init(\"sand\", null, function (collector) {\n collector.setupCallback({\n // Se dispara cuando la recolección ha finalizado\n \"collect-end\": kountSession,\n // Se dispara cuando la recolección ha comenzado\n \"collect-begin\": function () {\n console.log(\"La recolección de datos ha comenzado.\");\n },\n });\n // Inicia el proceso de recolección\n collector.collectData();\n });\n</script>\n\nEl valor que necesita es el que se recibe en params.MercSessId dentro de la función kountSession.
Este valor es el que se conoce como kountSession en la documentación de los endpoints de pago.
Una vez que ha obtenido el kountSessionId, debe incluirlo en el cuerpo (body) de las solicitudes de pago a los endpoints de Autorización y Preautorización.
\nComo se detalla en la documentación de autorización y preautorización, el objeto que se envía cifrado en base64 en el campo ed debe contener el campo kountSession.
{\n \"card\": {\n \"cardHolder\": \"John Doe\",\n \"expirationDate\": { \"month\": \"12\", \"year\": \"31\" },\n \"cardNumber\": \"4005529999000123\",\n \"cvc\": \"196\"\n },\n \"additional\": {\n \"channelData\": { \"channel\": \"01\", \"source\": \"API_CARD\" }\n },\n \"kountSession\": \"AQUI_VA_EL_ID_DE_SESION_OBTENIDO\"\n}\n\nAl enviar este objeto en la solicitud de pago, Greenpay podrá realizar el análisis de fraude correspondiente a la transacción.
\nA continuación se muestra un ejemplo HTML completo y funcional para obtener el ID de sesión del Data Collector.
\n<html lang=\"en\">\n <head>\n <meta charset=\"UTF-8\" />\n <meta http-equiv=\"X-UA-Compatible\" content=\"IE=edge\" />\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n <title>Ejemplo Data Collector</title>\n </head>\n <body>\n <h1 class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml'>Data Collector</h1>\n <div class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' id=\"kountSession\"></div>\n <script src=\"https://static.greenpay.me/collector/1.0.1/GDataCollector.min.js\"></script>\n <script>\n let sessionIdDiv = document.getElementById(\"kountSession\");\n function kountSession(params) {\n console.log(params.MercSessId);\n sessionIdDiv.innerHTML = `KOUNT SESSION: ${params.MercSessId}`;\n // Almacena este valor para enviarlo en tu solicitud de pago.\n }\n GDataCollector.init(\"sand\", null, function (collector) {\n collector.setupCallback({\n \"collect-end\": kountSession,\n \"collect-begin\": function () {\n console.log(\"Iniciando recolección de datos...\");\n },\n });\n collector.collectData();\n });\n </script>\n </body>\n</html>\n\nEste flujo permite procesar grandes volúmenes de transacciones y más información de pagos en lotes o batch payments.A continuación se describe la estructura de datos requerida para realizar un lote de pagos, incluyendo todas las validaciones y restricciones aplicadas por el middleware de validación.
\nSandbox: https://checkoutv2.greenpaysbx.me/batchPayment
Producción: https://checkoutv2.greenpay.me/batchPayment
⚠️ IMPORTANTE:
\n📝 Ejemplo de codificación en JavaScript:
\n// 1. Crear el objeto card con la estructura exacta\nconst cardObject = {\n tokenize: true,\n cardHolder: \"John Doe\",\n expirationDate: {\n month: \"12\",\n year: \"31\"\n },\n cardNumber: \"5597270000001815\",\n cvc: \"196\"\n};\n// 2. Convertir a JSON string\nconst cardJsonString = JSON.stringify(cardObject);\n// 3. Codificar en base64\nconst cardBase64 = btoa(cardJsonString);\n// 4. Resultado final para enviar\nconsole.log(cardBase64);\n// Output: \"eyJ0b2tlbml6ZSI6dHJ1ZSwiY2FyZEhvbGRlciI6IkpvaG4gRG9lIiwiZXhwaXJhdGlvbkRhdGUiOnsibW9udGgiOiIxMiIsInllYXIiOiIzMSJ9LCJjYXJkTnVtYmVyIjoiNTU5NzI3MDAwMDAwMTgxNSIsImN2YyI6IjE5NiJ9\"\n// 5. Verificar decodificación (para debugging)\nconst decodedCard = JSON.parse(atob(cardBase64));\nconsole.log(decodedCard);\n\n�� Nota importante: Para una solicitud batch se pueden enviar transacciones con tarjeta o token. Cada transacción puede usar un método de pago diferente, permitiendo mezclar ambos tipos en la misma solicitud.
\n{\n \"authInfo\": {\n \"secret\": \"U9vbOudD7dc/PoN3mfUHgOY4+0d2ficOByYOQV2KFPQrSpyKztMhwJ+Li3+yuOwmtRofVtyiJkHKzm/VDUGbEe55AXG7D9GWHliEfRQ0p47VIy7eV0YyJ+zB99RA4lZSYiqosioyUp7r5XMqOR8VkIaie+bRYk69Z9knRgYSGkc21ArBHgeavVb4Rs+NlUE8PzbR2hYC2FvoqYr7q4YbZ3kd16mZKHsYFD+zt83FV6FeRplWPwrpfiiaXqJcma1njmnRi3LknFE1YxGNssfpDfVksMDO4TqRmfMtfTpCbj2BSuFPgau1aGTAyOl254A9XNiZYvsa/3Ae7Sbt+X/GUw==\",\n \"merchantId\": \"5c416119-89fe-41dd-a675-50c8f22c06ee\",\n \"terminal\": \"fa736250-d1de-4169-bb76-6b9bebdf54cc\",\n \"callback\": \"https://greenpaybase64.free.beeceptor.com\"\n },\n \"transactions\": [\n {\n \"paymentMethod\": {\n \"card\": \"eyJ0b2tlbml6ZSI6dHJ1ZSwiY2FyZEhvbGRlciI6IkpvaG4gRG9lIiwiZXhwaXJhdGlvbkRhdGUiOnsibW9udGgiOiIxMiIsInllYXIiOiIzMSJ9LCJjYXJkTnVtYmVyIjoiNTU5NzI3MDAwMDAwMTgxNSIsImN2YyI6IjE5NiJ9\"\n },\n \"details\": [\n {\n \"amount\": 1000,\n \"currency\": \"USD\",\n \"description\": \"Compra producto A\",\n \"orderReference\": \"compra-1454455-A\",\n \"customer\": {\n \"name\": \"John Doe\",\n \"email\": \"johndoe@greenpay.me\",\n \"identification\": \"12345\",\n \"billingAddress\": {\n \"country\": \"CR\",\n \"province\": \"Nombre de la provincia\",\n \"city\": \"Ciudad\",\n \"street1\": \"Dirección Calle 1\",\n \"street2\": \"Dirección Calle 2\",\n \"zip\": \"10801\"\n },\n \"shippingAddress\": {\n \"country\": \"CR\",\n \"province\": \"Nombre de la provincia\",\n \"city\": \"Ciudad\",\n \"street1\": \"Dirección Calle 1\",\n \"street2\": \"Dirección Calle 2\",\n \"zip\": \"10801\"\n }\n },\n \"products\": [\n {\n \"description\": \"Producto A\",\n \"skuId\": \"SKU001\",\n \"quantity\": 1,\n \"price\": 1000,\n \"type\": \"physical\"\n }\n ]\n }\n ]\n },\n {\n \"paymentMethod\": {\n \"tokenGp\": {\n \"id\": \"c9693890-5bc0-11f0-85c2-d54f78ec1484\"\n }\n },\n \"details\": [\n {\n \"amount\": 2500,\n \"currency\": \"USD\",\n \"description\": \"Compra producto B\",\n \"orderReference\": \"compra-1454455-B\",\n \"customer\": {\n \"name\": \"Jane Doe\",\n \"email\": \"janedoe@greenpay.me\",\n \"identification\": \"67890\",\n \"billingAddress\": {\n \"country\": \"CR\",\n \"province\": \"Otra provincia\",\n \"city\": \"Otra Ciudad\",\n \"street1\": \"Otra Calle 1\",\n \"street2\": \"Otra Calle 2\",\n \"zip\": \"10802\"\n },\n \"shippingAddress\": {\n \"country\": \"CR\",\n \"province\": \"Otra provincia\",\n \"city\": \"Otra Ciudad\",\n \"street1\": \"Otra Calle 1\",\n \"street2\": \"Otra Calle 2\",\n \"zip\": \"10802\"\n }\n },\n \"products\": [\n {\n \"description\": \"Producto B\",\n \"skuId\": \"SKU002\",\n \"quantity\": 2,\n \"price\": 1250,\n \"type\": \"digital\"\n }\n ]\n }\n ]\n }\n ]\n}\n\n📝 Nota sobre el campo card codificado en base64:El campo card en el ejemplo anterior contiene el siguiente objeto codificado en base64:
\n{\n \"tokenize\": true,\n \"cardHolder\": \"John Doe\",\n \"expirationDate\": {\n \"month\": \"12\",\n \"year\": \"31\"\n },\n \"cardNumber\": \"5597270000001815\",\n \"cvc\": \"196\"\n}\n\nProceso de codificación:
\n{\n \"code\": 400,\n \"status\": \"failed\",\n \"message\": \"Invalid request data.\",\n \"error\": {\n \"errorCode\": \"0002\",\n \"errorDetails\": \"must have required property 'email'\"\n }\n}\n\nNota importante: Todas las respuestas fallidas tienen esta estructura. Para evitar errores, asegúrate de enviar todos los campos requeridos y seguir exactamente la estructura documentada en esta guía.
\n{\n \"code\": 200,\n \"status\": \"success\",\n \"message\": \"Mensajes recibidos exitosamente. Se procesará cada 'detail' individualmente y se reportará su resultado.\",\n \"summary\": {\n \"countTransaction\": 5,\n \"countDetail\": 5,\n \"batchId\": \"7e44c1d5-271c-4c68-9bed-3ba5c595b055\"\n }\n}\n\nNota importante:
\nNota importante: En las respuestas de las transacciones que llegan al callback, si te fijas, el pago con token y con tarjeta tienen diferencias en paymentMethod, pero la estructura general es la misma.
{\n \"code\": 200,\n \"status\": \"success\",\n \"message\": \"Transacción exitosa\",\n \"paymentMethod\": {\n \"card\": {\n \"tokenize\": true,\n \"tokenCard\": \"2a0a45b0-76e5-11f0-a830-d3cadc024e83\",\n \"bin\": \"456897\",\n \"brand\": \"Visa\",\n \"cardnumber\": \"456897******8886\",\n \"khash\": \"456897WIMPVRZQCLU0EA\",\n \"last4\": \"8886\"\n }\n },\n \"additionalData\": {\n \"customer\": {\n \"name\": \"John Doe\",\n \"email\": \"johndoe@greenpay.me\",\n \"identification\": \"12345\"\n },\n \"transaction\": {\n \"id\": \"427d8118-e7c5-4ffb-82b7-3b3d3c389517\",\n \"merchantId\": \"7c383115-80af-432e-a966-2be134d0a754\",\n \"orderReference\": \"compra-626-1-73887820-1e81-4c99-b104-12c18f982cdd\",\n \"terminal\": \"f8c26f02-0053-4ff6-b8b0-1edfc306bbad\",\n \"amount\": 1000,\n \"currency\": \"USD\",\n \"bankApprovalCode\": \"831000\"\n },\n \"batchId\": \"497fbb93-fd8f-4001-b546-ddf237358cf3\"\n }\n}\n\n{\n \"code\": 200,\n \"status\": \"success\",\n \"message\": \"Transacción exitosa\",\n \"paymentMethod\": {\n \"card\": {\n \"tokenize\": false,\n \"tokenCard\": null,\n \"bin\": \"474581\",\n \"brand\": \"Visa\",\n \"cardnumber\": \"474581******3511\",\n \"khash\": null,\n \"last4\": \"3511\"\n }\n },\n \"additionalData\": {\n \"customer\": {\n \"name\": \"John Doe\",\n \"email\": \"johndoe@greenpay.me\",\n \"identification\": \"12345\"\n },\n \"transaction\": {\n \"id\": \"c7dd8f81-ea42-4c43-9130-c6f266b41228\",\n \"merchantId\": \"7c383115-80af-432e-a966-2be134d0a754\",\n \"orderReference\": \"compra-1325-1-d947590d-d61e-40f3-b482-74dbea7bc61c\",\n \"terminal\": \"f8c26f02-0053-4ff6-b8b0-1edfc306bbad\",\n \"amount\": 1000,\n \"currency\": \"USD\",\n \"bankApprovalCode\": \"831000\"\n },\n \"batchId\": \"497fbb93-fd8f-4001-b546-ddf237358cf3\"\n }\n}\n\n{\n \"code\": 400,\n \"status\": \"failed\",\n \"message\": \"Formato de tarjeta inválido\",\n \"error\": {\n \"errorCode\": \"021\",\n \"errorDetails\": \"Formato de tarjeta inválido\"\n },\n \"paymentMethod\": {\n \"card\": {\n \"tokenize\": null,\n \"tokenCard\": null,\n \"bin\": null,\n \"last4\": null,\n \"brand\": null,\n \"cardnumber\": null,\n \"khash\": null\n }\n },\n \"additionalData\": {\n \"customer\": {\n \"name\": \"John Doe\",\n \"email\": \"johndoe@greenpay.me\",\n \"identification\": \"12345\"\n },\n \"transaction\": {\n \"id\": \"ebbb3d11-38c4-4649-8214-66e2d89e6901\",\n \"merchantId\": \"7c383115-80af-432e-a966-2be134d0a754\",\n \"orderReference\": \"compra-26-2-aba2414d-ef36-4e27-b6c0-5994c8d8efbe\",\n \"terminal\": \"f8c26f02-0053-4ff6-b8b0-1edfc306bbad\",\n \"amount\": 2500,\n \"currency\": \"USD\",\n \"bankApprovalCode\": null\n },\n \"batchId\": \"9c83de2-962a-45f5-9a6f-ed04b4a6fe3f\"\n }\n}\n\nNota importante: En algunas ocasiones, aunque la respuesta sea fallida, pueden aparecer campos como brand, last4, bin, pueden ser diferente de null, dependiendo de la información que se haya podido extraer de la tarjeta antes del fallo.
\n{\n \"code\": 200,\n \"status\": \"success\",\n \"message\": \"Transacción exitosa\",\n \"paymentMethod\": {\n \"tokenGp\": {\n \"id\": \"2a0a45b0-76e5-11f0-a830-d3cadc024e83\"\n }\n },\n \"additionalData\": {\n \"customer\": {\n \"name\": \"John Doe\",\n \"email\": \"johndoe@greenpay.me\",\n \"identification\": \"12345\"\n },\n \"transaction\": {\n \"id\": \"2829519f-8086-4e50-8154-acb6df7129a7\",\n \"merchantId\": \"7c383115-80af-432e-a966-2be134d0a754\",\n \"orderReference\": \"compra-1-1-03489016-7684-428d-9cfd-e6ebef3bdf88\",\n \"terminal\": \"f8c26f02-0053-4ff6-b8b0-1edfc306bbad\",\n \"amount\": 1000,\n \"currency\": \"USD\",\n \"bankApprovalCode\": \"831000\"\n },\n \"batchId\": \"0655a420-93e6-44f1-9626-17be169d3f8b\"\n }\n}\n\n{\n \"code\": 400,\n \"status\": \"failed\",\n \"message\": \"Pago fallido\",\n \"error\": {\n \"errorCode\": \"024\",\n \"errorDetails\": \"STOLEN_LOST_CARD - Decline - Stolen or lost card.\"\n },\n \"paymentMethod\": {\n \"tokenGp\": {\n \"id\": \"2a0a45b0-76e5-11f0-a830-d3cadc024e83\"\n }\n },\n \"additionalData\": {\n \"customer\": {\n \"name\": \"John Doe\",\n \"email\": \"johndoe@greenpay.me\",\n \"identification\": \"12345\"\n },\n \"transaction\": {\n \"id\": \"b9c787d6-bab8-43b1-b1f8-d9fdc0d8d62d\",\n \"merchantId\": \"7c383115-80af-432e-a966-2be134d0a754\",\n \"orderReference\": \"compra-1-1-a00e879c-dbc6-4cfa-b80a-90dcc195ee4d\",\n \"terminal\": \"f8c26f02-0053-4ff6-b8b0-1edfc306bbad\",\n \"amount\": 4004,\n \"currency\": \"USD\",\n \"bankApprovalCode\": null\n },\n \"batchId\": \"af049248-e940-4482-9ad6-1347a9fbabd4\"\n }\n}\n\nEste endpoint permite obtener los planes de financiamiento asociados a un comercio (merchant) y una terminal específica. Los planes incluyen opciones de cuotas con diferentes tasas de interés y están asociados a rangos específicos de BINs de tarjetas.
\nSandbox (Desarrollo):
\nhttps://checkoutv2.greenpaysbx.me/merchant/{merchantId}/planes/terminal/{terminalId}\n\nProducción:
\nhttps://checkoutv2.greenpay.me/merchant/{merchantId}/planes/terminal/{terminalId}\n\nGET\n\nEstructura de Respuesta:
\n{\n \"plans\": [\n {\n \"id\": \"06ae4d6a-a55d-41b8-894e-be9b75c4f063\",\n \"planName\": \"Plan 6 Meses\",\n \"bins\": [552882, 445653],\n \"planType\": \"CUOTAS\",\n \"planValue\": [6, 12],\n \"programs\": \"VISA_MASTERCARD\",\n \"status\": 1,\n \"createdAt\": \"2024-01-15T10:30:00Z\",\n \"updatedAt\": \"2024-01-15T10:30:00Z\"\n },\n {\n \"id\": \"1a2b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6\",\n \"planName\": \"Plan 12 Meses\",\n \"bins\": [552882, 445653],\n \"planType\": \"CUOTAS\",\n \"planValue\": [12, 18],\n \"programs\": \"VISA_MASTERCARD\",\n \"status\": 1,\n \"createdAt\": \"2024-01-15T10:30:00Z\",\n \"updatedAt\": \"2024-01-15T10:30:00Z\"\n }\n ],\n \"mergedPlans\": [\n {\n \"text\": \"6 cuotas\",\n \"planValue\": \"6_06ae4d6a-a55d-41b8-894e-be9b75c4f063\",\n \"planId\": \"06ae4d6a-a55d-41b8-894e-be9b75c4f063\",\n \"planName\": \"Plan 6 Meses\",\n \"planType\": \"CUOTAS\"\n },\n {\n \"text\": \"12 cuotas\",\n \"planValue\": \"12_06ae4d6a-a55d-41b8-894e-be9b75c4f063\",\n \"planId\": \"06ae4d6a-a55d-41b8-894e-be9b75c4f063\",\n \"planName\": \"Plan 6 Meses\",\n \"planType\": \"CUOTAS\"\n }\n ],\n \"mergedBins\": [552882, 445653]\n}\n\nCampos de Respuesta:
\nEjemplo de Respuesta:
\n{\n \"error\": \"Merchant not found\",\n \"status\": 400\n}\n\nPosibles Causas de Error:
\nIMPORTANTE: Este endpoint debe ser consultado desde el frontend. GreenPay ya envía los datos procesados para usar mergedPlans directamente en un combobox o lista desplegable.Estructura recomendada para combobox/select:
\ntext de mergedPlansplanValue de mergedPlans// Obtener planes del comercio\nconst getMerchantPlans = async () => {\n try {\n const response = await fetch(\n `${process.env.NEXT_PUBLIC_ORCHESTRATOR_URL}/merchant/${merchantId}/plans/terminal/${terminalId}`,\n {\n method: 'GET',\n headers: {\n 'Content-Type': 'application/json'\n }\n }\n )\n if (!response.ok) {\n throw new Error('Error al obtener planes')\n }\n const data = await response.json()\n return data.mergedPlans // Usar directamente mergedPlans\n } catch (error) {\n console.error('Error:', error)\n throw error\n }\n}\n// Crear opciones para combobox/select\nconst createPlanOptions = (mergedPlans) => {\n return mergedPlans.map(plan => ({\n label: plan.text, // Texto para mostrar\n value: plan.planValue // Valor del option\n }))\n}\n// Ejemplo de combobox en React\nconst PlanSelector = () => {\n const [plans, setPlans] = useState([])\n useEffect(() => {\n const loadPlans = async () => {\n const plansData = await getMerchantPlans()\n setPlans(plansData)\n }\n loadPlans()\n }, [])\n return (\n <select onChange={handlePlanChange}>\n <option value=\"\">Seleccionar plan</option>\n {plans.map((plan) => (\n <option key={plan.planId} value={plan.planValue}>\n {plan.text}\n </option>\n ))}\n </select>\n )\n}\n\nIMPORTANTE: El campo planValue contiene la cuota y el plan separados por guion bajo. La cuota debe parsearse a número entero, NO puede enviarse como string.
const handlePlanSelection = (selectedPlanValue) => {\n if (selectedPlanValue.includes('_')) {\n const [quota, plan] = selectedPlanValue.split('_')\n // CRÍTICO: Parsear quota a número entero\n const quotaNumber = parseInt(quota)\n console.log('Cuotas:', quotaNumber) // Número entero\n console.log('Plan ID:', plan) // String\n // Construir objeto cardData con planes\n const cardData = {\n card: {\n cardHolder: \"John Doe\",\n expirationDate: {\n month: \"12\",\n year: \"31\",\n },\n cardNumber: \"5528820000000003\",\n cvc: \"196\",\n },\n additional: { \n channelData: { \n channel: \"01\", \n source: \"API_CARD\" \n } \n },\n // campos requeridos para pagos con planes\n plan: plan, // String del plan ID\n quota: quotaNumber, // Número entero de cuotas\n };\n // Codificar en base64 para envío\n const encodedData = btoa(JSON.stringify(cardData))\n return encodedData\n }\n}\n\nIMPORTANTE: En los procesos de pago con 3DS (enrollment y/o validate) o autorización normal, se debe enviar el quota y plan en los datos de la tarjeta que van en base64.
\n// Card data\nconst cardData = {\n card: {\n cardHolder: \"John Doe\",\n expirationDate: {\n month: \"12\",\n year: \"31\",\n },\n cardNumber: \"5528820000000003\",\n cvc: \"196\",\n },\n additional: { \n channelData: { \n channel: \"01\", \n source: \"API_CARD\" \n } \n },\n // campos requeridos para pagos con planes\n plan: \"06ae4d6a-a55d-41b8-894e-be9b75c4f063\",\n quota: 6, // DEBE ser número entero, NO string\n};\n\nconst enrollmentData = {\n cardData: {\n session: sessionId,\n ed: encodedCardDataWithPlans // Incluye quota (número) y plan (string)\n },\n referenceId: referenceId,\n transactionId: transactionId,\n redirectURL: redirectURL\n}\n\nconst validateData = {\n cardData: {\n session: sessionId,\n ed: encodedCardDataWithPlans // Incluye quota (número) y plan (string)\n },\n authenticationTransactionId: authTransactionId,\n transactionId: transactionId\n}\n\nconst authData = {\n cardData: {\n session: sessionId,\n ed: encodedCardDataWithPlans // Incluye quota (número) y plan (string)\n }\n}\n\nRevisar la documentacion con 3DS o Authorizacion, ahí se encuentra el apartado de planes de cada integración
\nPuede revisar los siguientes ejemplos de código
\n\n\n","urlObject":{"path":["merchant","d17d1cec-ae39-4a1e-b0c6-8e9192824c3f","plans","terminal","832c10f8-726b-40d3-9f92-8db34f5141f7"],"host":["https://checkoutv2.greenpaysbx.me"],"query":[],"variable":[]}},"response":[],"_postman_id":"193a5a4b-96ec-487d-bf68-4a65451175ec"}],"id":"1112c503-ffb3-4374-b272-2a1c6f711a9d","_postman_id":"1112c503-ffb3-4374-b272-2a1c6f711a9d","description":""}],"id":"a44c5ac3-1ee0-4b54-bb44-207ff66a2357","_postman_id":"a44c5ac3-1ee0-4b54-bb44-207ff66a2357","description":""}],"event":[{"listen":"prerequest","script":{"id":"4cb80fa5-a2d7-42d9-a26a-4249ecc9498c","type":"text/javascript","packages":{},"exec":[""]}},{"listen":"test","script":{"id":"7ef34627-37a1-40b9-95a1-9ceae286c13c","type":"text/javascript","packages":{},"exec":[""]}}],"variable":[{"key":"secret","value":"{{Secret provisto por GreenPay}}","type":"string"},{"key":"merchantId","value":"{{Merchant ID provisto por GreenPay}}","type":"string"},{"key":"terminal_CRC","value":"","type":"string"},{"key":"terminal_USD","value":"","type":"string"},{"key":"orchestrator_url","value":"https://checkoutv2.greenpaysbx.me","type":"string"},{"key":"environment","value":"","type":"string"},{"key":"liszt-token","value":"","type":"string"},{"key":"GP_SESSION","value":"{{ID de sesión obtenido al momento de crear la orden de pago o tokenizacion}}","type":"string"},{"key":"GP_TOKEN","value":"{{ID de token obtenido al momento de crear la orden de pago o tokenizacion}}","type":"string"},{"key":"terminal_CYBS","value":"","type":"string"},{"key":"cybs_terminal_USD","value":"{{Terminal en USD provista por GreenPay}}","type":"string"},{"key":"cybs_terminal_CRC","value":"{{Terminal en CRC provista por GreenPay}}","type":"string"},{"key":"card_token","value":"{{Token de la tarjeta con que se realizó la transacción}}","type":"string"},{"key":"confirm-authorization-token","value":"","type":"string"},{"key":"ed","value":"{{Información de la tarjeta codificada en base64}}","type":"string"},{"key":"referenceId","value":"{{ID de referencia obtenido al momento de ejecutar el proceso PA SETUP}}","type":"string"},{"key":"transactionId","value":"{{ID de transacción obtenido al momento de ejecutar el proceso PA SETUP}}","type":"string"},{"key":"checkoutFormURL","value":"{{URL del formulario de checkout donde se ingreso la informacion de la tarjeta}}","type":"string"},{"key":"authenticationTransactionId","value":"{{ID de autenticación de la transacción obtenido al momento de ejecutar el proceso PA ENROLLMENT}}","type":"string"}]}