Consideraciones

Se debe haber creado una orden de pago previamente para poder realizar un cobro por API V2

Pasos para el uso del API (Ejemplo desde postman)

1.1) Agregar los datos requeridos para la solicitud de pago con Token

Datos Requeridos

{
    "secret": "Secret de su comercio",
    "merchantId": "Su merchantID",
    "terminal": "El ID de su terminal",
    "amount": "Cantidad autorizar",
    "currency": "Moneda (USD, CRC)",
    "description": "Descripcion de la compra",
    "orderReference": "Referencia única",
    "token": "Token de la tarjeta",
    "additional": {
        "customer": {
            "email": "Correo electrónico del cliente ",
            "name": "Nombre del cliente",
            "billingAddress": {
                "country": "Alpha-2 code",
                "province": "Provincia",
                "city": "Ciudad"
            }
        }
    }
}

Datos adicionales

{
    "secret": "Secret de su comercio",
    "merchantId": "Su merchantID",
    "terminal": "El ID de su terminal",
    "amount": "Cantidad autorizar",
    "currency": "Moneda (USD, CRC)",
    "description": "Descripcion de la compra",
    "orderReference": "Referencia única",
    "token": "Token de la tarjeta",
    "additional": {
        "customer": {
            "email": "Correo electrónico del cliente ",
            "name": "Nombre del cliente",
            "billingAddress": {
                 "country": "Alpha-2 code",
                "province": "Provincia",
                "city": "Ciudad"
                "street1": "Dirección Calle 1",
                "street2": "Dirección Calle 2",
                "zip": "código postal"
            },
            "shippingAddress": {
                 "country": "Alpha-2 code",
                "province": "Provincia",
                "city": "Ciudad"
                "street1": "Dirección Calle 1",
                "street2": "Dirección Calle 2",
                "zip": "código postal"
            }
        },
        "products": [{
            "description": "Descripción de producto",
            "skuId": "Identificador único en el comercio",
            "quantity": "Cantidad",
            "price": "precio",
            "type": "Tipo de producto"
        }]
    } 

1.2) Enviar solicitud pago con token

Respuesta exitosa

{
    "status": 200,
    "orderId": "compra-token-19-CRC-409",
    "authorization": "172012",
    "amount": 116,
    "currency": "CRC",
    "token": "8a655ae0-34c3-11ef-91b4-6b798695d25d",
    "internalRef": 3924210174186,
    "transactionId": "5ebc599a-d3ef-413b-98a9-1548388a5501",
    "errors": [],
    "last4": "9358",
    "brand": "Visa"
}

Respuesta fallida

{
    "message": "Error: invalid currency",
    "status": "fail"
}

2. Autorización

Consideraciones

Para invocar el Api de pagos se debe considerar lo siguiente

1. Utilizar el servicio en los endpoints: 

Ambiente de desarrollo o sandbox: https://checkoutv2.greenpaysbx.me

Ambiente productivo: https://checkoutv2.greenpay.me

Tener los valores de session y token de una orden de pago, que se ha creado en el paso previo y que no haya excedido los 30 minutos establecidos para el vencimiento.

Pasos para el uso del servicio

2.1 Incluir el Data Collector (En su frontend)

Solo aplica si usará el servicio de antifraude de transacciones que facilita GreenPay

El datacollector solo funciona en aplicaciones web                                                        

2.2 Estructura de los datos

2.2.1 Crear Objeto JSON para los datos de la tarjeta

El objeto JSON con los datos de la tarjeta debe tener la siguiente estructura:

{
  card: {
    cardHolder: "John Doe",
    expirationDate: {
      month: "12",
      year: "31",
    },
    cardNumber: "5597270000001815",
    cvc: "196",
  },
  additional: { channelData: { channel: "01", source: "API_CARD" } },
  kountSession: "58218d22a34f42cda041789b3abc9d50", // Antifraud value
}

Datos obligatorios                                                              

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

kountSession es requerido si utilizará el antifraude y si sus sistemas son aplicaciones web (a la hora de realizar un pago) para correr el script

 Cifrar el objeto tipo JSON que contiene la información de la tarjeta
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 TLS 1.2.  Y cómo un método extra de seguridad, la información de la tarjeta se debe enviar codificada en base64.
En Bitbucket podrá encontrar ejemplos de integración desarrollados en NodeJS.

A continuación, se muestran los pasos a seguir para cifrar la información de la tarjeta.
 
Utilizando Javascript

const cardData = {
  card: {
    cardHolder: "Angel Gonzalez",
    expirationDate: {
      month: "03",
      year: "25",
    },
    cardNumber: "5597270000001815",
    cvc: "196",
  },
  additional: { channelData: { channel: "01", source: "API_CARD" } },
  kountSession: "58218d22a34f42cda041789b3abc9d50",
};

const base64 = Buffer.from(JSON.stringify(cardData)).toString("base64");

console.log(base64);

Se debe enviar una solicitud HTTP de tipo POST al endpoint de pagos con el objeto JSON que contiene los datos cifrados y la sesión obtenida en el paso anterior, este JSON se envía en el cuerpo de la solicitud.

A esta solicitud se le debe agregar el header session-token, este header debe contener el token obtenido en la solicitud de creación de una orden de pago.  Puede ver el siguiente ejemplo 

Respuesta autorización exitosa

La autorización exitosa responde con un HTTP Code 200

1. {
   
2.       "status": 200,
   
3.        "orderId": "compra-2024-10-23-USD-265",
   
4.        "authorization": "445000",
   
5.        "amount": 302,
   
6.        "currency": "USD",
   
7.        "token": "0c86cae0-917b-11ef-8500-27f1ad691f71",
   
8.         "internalRef": 10819032514292,
   
9.         "transactionId": "beb386d4-0595-49b1-a7a9-e23876cf0b97",
   
10.          "errors": [],
    
11.          "last4": "1815",
    
12.          "brand": "Mastercard",
    
13.          "statusCode": 200
    
14. }