Crear orden de pago

Crear orden de pago

Consideraciones

La orden de pago se genera para indicar al API de pago que se realizará una transacción, basándose en los datos proporcionados en la orden. Para esto, se debe considerar lo siguiente:
  1. Utilizar el servicio en los endpoints:
    1. En sandbox: https://sandbox-merchant.greenpay.me/
    2. En producción: https://merchant.greenpay.me/
  2. Una orden de pago genera una respuesta en formato JSON que contiene un session y un token. 
  3. La session y el token tienen una vigencia de 30 minutos a partir de la creación de la orden de pago. Después de este período, pierden validez. Si se requiere continuar con el proceso, será necesario generar una nueva orden.
  4. Se recomienda realizar este proceso desde el backend del comercio, con el fin de proteger los datos sensibles, como las credenciales y los detalles de la orden de pago.
  5. La creación de la orden de pago es necesaria en todo momento, ya sea que el servicio adquirido se integre directamente con el API de pagos o a través del formulario de GreenPay.

Pasos para uso del servicio

1. Estructura de los datos

1.1 Orden de pago

Para consumir el servicio, es necesario realizar un POST con la siguiente estructura:

{
  "secret": "Secret provisto por GreenPay",
  "merchantId": "Merchant provisto por GreenPay",
  "terminal": "TerminalId provisto por GreenPay",
  "amount": 0,
  "currency": "Código aceptados CRC | USD | GTQ",
  "description": "La descripción de la orden i.e Pago tiquete de parqueo",
  "orderReference": "Identificador único de la orden a crear",
  "additional": {
      "customer": {
          "name": "User Example",
          "email": "user@example.com",
          "identification": "Unique user identification",
          "billingAddress": {
              "country": "ISO 3166-1 alpha-2",
              "province": "Nombre de la provincia",
              "city": "Ciudad",
              "street1": "Dirección Calle 1",
              "street2": "Dirección Calle 2",
              "zip": "código postal"
          },
          "shippingAddress": {
              "country": "ISO 3166-1 alpha-2",
              "province": "Nombre de la 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": 1,
              "price": 100.5,
              "type": "Tipo de producto"
          }
      ],
      "details": {
          "description": "description",
          "seller": "seller",
          "other": "other details"
      }
  }
}

Los datos que debe proporcionar obligatorios son:
  1. secret: String de la llave secreta proporcionada por GreenPay.
  2. merchantId: String del identificador único para el comercio,  proporcionado por GreenPay.
  3. terminalId: String de la terminal o afiliado del banco, este valor es proporcionado por GreenPay.
  4. amount: El monto de la orden en números.
  5. currency: String del código del tipo de moneda configurado para el terminal, debe ser el valor correspondiente en el ISO 4217. Por ejemplo: CRC o USD.
  6. description: String de la descripción de la orden por ejemplo: Pago de tiquete de parqueo.
  7. orderReference: String del identificador único de la orden a crear.
  8. name: Nombre del cliente involucrado.
  9. email: Correo electrónico del cliente.
  10. identification: Identificador único del cliente.
  11. billingAddress:
    1. country: String. Código del país según el ISO 3166-1 alpha-2.
    2. street1: String. Dirección exacta del cliente.
  1. shippingAddress:
    1. country: String. Código del país según el ISO 3166-1 alpha-2
    2. street1: String. Dirección exacta del cliente.
  1. products:
    1. description: String. Descripción de producto, por ejemplo: Tiquete de parqueo.
    2. skuId: String. Identificador del producto del lado del comercio, por ejemplo: tc_10001.
    3. quantity: Int. Cantidad del producto comprado por el usuario.
      1. price: Double. Precio del producto.
      2. type: String.  Tipo de producto. Por ejemplo: Tiquete digital , Electrónicos.
    Otros datos que se pueden proporcionar son:

    1. shippingAddress:

      1. province: String. Provincia.

      2. city: String. Ciudad.

      3. street2 : String. Dirección exacta.

      4. zip: String. Código postal de la dirección del usuario.

    2. billingAddress:

      1. province: String. Provincia.

      2. city: String. Ciudad

      3. street2 : String. Dirección exacta.

      4. zip: String. Código postal de la dirección del usuario.

    1. details: Objeto donde el comercio puede agregar cualquier otra información que sea útil en la transacción o cualquier información adicional que solicite Greenpay.

    1.2. Orden de pago para el formulario web

    Se debe añadir el parámetro callback a la estructura, este parámetro es una URL proporcionada por el comercio, donde se recibirá la respuesta del formulario de checkout.

    A continuación se muestra cómo incluir el parámetro callback en el objeto:
    1. {
          "secret": "secret provisto por GreenPay",
          "merchantId": "merchant provisto por GreenPay",
          "terminal": "terminalId provisto por GreenPay",
          "amount": 0,
          "currency": "Código aceptados CRC | USD | GTQ",
          "description": "La descripción de la orden i.e Pago tiquete de parqueo",
          "orderReference": "Identificador único de la orden a crear",
          "callback": "https://yourhost.url/callback",
          "additional": {
              //Toda la información adicional descrita en el punto anterior.
          }
      }

    1.3 Orden de pago con Credix 

    Para procesar órdenes de pago con Credix, se debe cumplir con todos los campos requeridos en una orden de pago normal. Además, se debe incluir un parámetro llamado numberOfPayments, el cual debe contener un arreglo de strings que corresponde a la cantidad de meses soportados por la terminal de Credix ( 3,6 o 12 meses)

    Para consumir el servicio se debe hacer un POST con la siguiente estructura:
    1. {
          "secret": "secret provisto por GreenPay",
          "merchantId": "merchant provisto por GreenPay",
          "terminal": "terminalId provisto por GreenPay",
          "amount": 0,
          "currency": "Códigos aceptados CRC | USD | GTQ",
          "description": "La descripción de la orden i.e Pago tiquete de parqueo",
          "orderReference": "Identificador único de la orden a crear",
          "numberOfPayments": [
              "3",
              "6",
              "12"
          ], //requerido para credix
          "additional": {
             //Toda la información adicional descrita arriba
          }
      }
    Agregar el parámetro  callback si se va utilizar el formulario checkout.

    1.4 Orden de pago con varias terminales

    Si el comercio desea crear la orden con varias terminales, estas deben ser agregadas al parámetro terminal como un arreglo.
    Esta opción es recomendada con el formulario de checkout, para ello debe agregar el parámetro callback.
    El siguiente objeto JSON muestra cómo se debe de enviar el parámetro terminal para que soporte varias terminales:
    1. {
          "secret": "secret provisto por GreenPay",
          "merchantId": "merchant provisto por GreenPay",
          "terminal": [
              "Postman Examples-efe6-BNCR-CRC",
              "Postman Examples-efe6-BAC-CRC",
              "Postman Examples-efe6-CREDIX-CRC"
          ], //arreglo de terminales
          "amount": 0,
          "currency": "Código aceptados CRC | USD | GTQ",
          "description": "La descripción de la orden i.e Pago tiquete de parqueo",
          "orderReference": "Identificador único de la orden a crear",
          "additional": {
              //Toda la información adicional descrita arriba
          }
      }

    2. Realizar POST para crear la orden de pago.
    Se debe enviar una solicitud HTTP de tipo POST al endpoint de creación de órdenes de pagos. El cuerpo de la solicitud debe contener un objeto JSON previamente creado. La respuesta esperada será un JSON con una session y un token necesarios para efectuar el pago.
    1. {
          "statusCode": 200,
          "body": {
              "session": "8798d8b0-6835-47c2-8643-c286fc219988",
              "token": "dc0c4c6d-3d67-4992-b882-a781b693f374"
          },
          "headers": {
              "...": "..."
          },
          "request": {
              "uri": {
                  "...": "..."
              },
              "method": "post",
              "headers": {
                  "...": "..."
              }
          }
      }

    A continuación, se presenta un ejemplo en JavaScript de cómo enviar una solicitud al endpoint de creación de órdenes de pago. Esta función también inlcluye la obtención del “body” del objeto tipo JSON recibido como respuesta:
    1. var body = {
          {
              "secret": "secret provisto por GreenPay",
              "merchantId": "merchant provisto por GreenPay",
              "terminal": "terminalId provisto por GreenPay",
              "amount": 0.00,
              "currency": "Código aceptados CRC | USD | GTQ",
              "description": "La descripción de la orden i.e Pago tiquete de parqueo",
              "orderReference": "Identificador único de la orden a crear",
              "callback": "https://yourhost.url/callback%22,
              "numberOfPayments": ["3", "6", "12"],
              "additional": {
                  "customer": {
                      "name": "User Example",
                      "email": "user@example.com",
                           "identification": "Unique user identification",
                      "billingAddress": {
                          "country": "ISO 3166-1 alpha-2",
                          "province": "Nombre de la provincia",
                          "city": "Ciudad",
                          "street1": "Dirección Calle 1",
                          "street2": "Dirección Calle 2",
                          "zip": "código postal"
                      },
                      "shippingAddress": {
                          "country": "ISO 3166-1 alpha-2",
                          "province": "Nombre de la 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": 1,
                      "price": 100.50,
                      "type": "Tipo de producto"
                  }]
              }
          }
      }


      var unirest = require("unirest");
      function postCreateOrder(data) {
        return new Promise(function (resolve, reject) {
            .headers({
              "Accept": "application/json",
              "Content-Type": "application/json",
            })
            .send(JSON.stringify(data))
            .end(function (response) {
              if (response.status === 200) {
                console.log( JSON.stringify("body:",response.body));
                resolve(response.body);
              } else {
                reject(response.body);
              }
            });
        });
      }

      • Related Articles

      • Crear orden de tokenización

        Consideraciones Una orden de tokenización se crea para indicar al API de Greenpay que se creará un token a partir de los datos de una tarjeta de crédito o débito. Para esto se debe tener las siguientes consideraciones: Endpoints para crear la orden ...

      • Invocar API de pago

        Consideraciones Para invocar el Api de pagos se debe considerar lo siguiente: Utilizar el servicio en los endpoints: Sandbox: https://sandbox-checkout.greenpay.me/kount Producción: https://checkout.greenpay.me/kount Tener una session y token de una ...

      • Proceso de pago con Widget

        Consideraciones Al utilizar el widget de pago de Greenpay, es importante tener en cuenta lo siguiente: Es necesario disponer de una cuenta de sandbox o de producción. Para obtener esta cuenta, visite la sección Sobre cuenta de pruebas o sandbox. El ...

      • Crear link de cobro

        Consideraciones Para utilizar la funcionalidad de suscripciones debe considerar lo siguiente: El comercio debe estar habilitado, si esta deshabilitado no podrá ingresar y utilizar la funcionalidades del dashboard. Si desconoce el estado de su ...

      • Actualizar método de pago

        Para este servicio se debe consumir el siguiente endpoint: https://sandbox-merchant.greenpay.me/subscriptions/update/card_token A continuación, se muestra el paso a paso para cancelar una suscripción en nuestro API de forma exitosa: 1. Crear el ...