Crear una orden de pago

Crear una orden de pago

La solicitud de creación de una orden de pago habilita al API de pagos para que reciba una solicitud de pago con los datos que se reciben en la respuesta (session, token) de la solicitud de creación de una orden de pago.

El API de pago esperará por 30 minutos la solicitud de pago, después de este tiempo la sesión y el token expiran. Por lo tanto, se deberá generar otra orden de pago.

Este paso se debe realizar siempre, tanto para realizar débitos por medio de nuestro formulario, como por medio de llamados directos al servicio de pagos. Además recomendamos realizar este paso desde el backend de la aplicación para no exponer las credenciales del API.

Para crear una orden de pago se deben realizar lo siguiente:

1. Crear un objeto de tipo JSON con los datos de la orden de pago

Se debe crear un objeto de tipo json con la siguiente estructura:

Ejemplo de JSON a enviar
  1. {
  2.     "secret": "secret provisto por GreenPay",
  3.     "merchantId": "merchant provisto por GreenPay",
  4.     "terminal": "terminalId provisto por GreenPay",
  5.     "amount": 0.00,
  6.     "currency": "Código aceptados CRC | USD | GTQ",
  7.     "description": "La descripción de la orden i.e Pago tiquete de parqueo",
  8.     "orderReference": "Identificador único de la orden a crear",
  9.     "callback": "https://yourhost.url/callback",
  10.     "additional": {
  11.         "customer": {
  12.             "name": "User Example",
  13.             "email": "user@example.com",
  14.             "billingAddress": {
  15.                 "country": "ISO 3166-1 alpha-2",
  16.                 "province": "Nombre de la provincia",
  17.                 "city": "Ciudad",
  18.                 "street1": "Dirección Calle 1",
  19.                 "street2": "Dirección Calle 2",
  20.                 "zip": "código postal"
  21.             },
  22.             "shippingAddress": {
  23.                 "country": "ISO 3166-1 alpha-2",
  24.                 "province": "Nombre de la provincia",
  25.                 "city": "Ciudad",
  26.                 "street1": "Dirección Calle 1",
  27.                 "street2": "Dirección Calle 2",
  28.                 "zip": "código postal"
  29.             }
  30.         },
  31.         "products": [{
  32.             "description": "Descripción de producto",
  33.             "skuId": "Identificador único en el comercio",
  34.             "quantity": 1,
  35.             "price": 100.50,
  36.             "type": "Tipo de producto"
  37.         }]
  38.     }
  39. }

Parámetros del JSON:

 Obligatorios

  1. secret: String de una llave secreta utilizada en conjunto con el merchantId del comercio en particular, es provisto por GreenPay.
  2. merchantId: String del identificador único para el comercio, es provisto por GreenPay.
  3. terminalId: String del terminal o afiliado del banco, este valor es provisto 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 i.e Pago tiquete de parqueo.
  7. orderReference: String del Identificador único de la orden a crear.
  8. billingAddress:
    1. country: Tipo string. Código del país según el ISO 3166-1 alpha-2.
    2. street1: Tipo string. Dirección exacta del cliente.
  9. shippingAddress:
    1. country: Tipo string. Código del país según el ISO 3166-1 alpha-2.
    2. street1: Tipo string. Dirección exacta del cliente.
  10. products: 
    1. description: Tipo string. Descripción de producto. Por ejemplo Tiquete de parqueo.
    2. skuId: Tipo string. Identificador del producto del lado del comercio. Por ejemplo tc_10001.
    3. quantity: Tipo INT. Cantidad del producto comprado por el usuario.
    4. price: Tipo Double. Precio del producto.
    5. type: Tipo string.  Tipo de producto. Por ejemplo Tiquete digital , Electrónicos.

Opcionales

  1. callback: Este campo (url) solamente es necesario si se utilizará el débito con el formulario de checkout que provee GreenPay. Se utiliza este callback para hacer un redireccionamiento del formulario hacia dicha dirección. En caso de éxito o fallo, se invocará la url base, en caso de que se cancele la solicitud, se invocará un recurso cancel sobre la url base (base_url/cancel).
  2. shippingAddress:
    1. province: Tipo string. Provincia.
    2. city: Tipo string. Ciudad.
    3. street2 : Tipo string. Dirección exacta.
    4. zip: Tipo string. Código postal de la dirección del usuario.
  3. billingAddress:
    1. province: Tipo string. Provincia.
    2. city: Tipo string. Ciudad
    3. street2 : Tipo string. Dirección exacta.
    4. zip: Tipo string. Código postal de la dirección del usuario.

Observaciones:

  1. El parámetro “orderReference” del objeto JSON es un identificador único que deberá ser manejado por el comercio. Este identificador tiene la finalidad de generar trazabilidad entre las solicitudes de creación de órdenes de pagos que realice el comercio y las transacciones que se procesen en el API de pagos.
  2. En caso de enviar el objeto shippingAddress, aunque sea opcional es requerido enviar mínimo los parámetros "country" y "stree1".

2. Enviar un request para crear la orden de pago

Se debe enviar una solicitud HTTP de tipo POST al endpoint de creación de órdenes de pagos con el objeto json creado en el paso anterior en el cuerpo de la solicitud.

Una vez se ha enviado la solicitud de creación de una orden de pago y esta se haya realizado con éxito, se obtiene un objeto de tipo JSON como respuesta.

A recibir esta respuesta, el parámetro que se debe obtener del objeto JSON es el “body”, ya que este contiene la sesión y el token que se deben enviar para realizar el débito a la tarjeta correspondiente. En la siguiente imagen se muestra un ejemplo de la respuesta que se recibe después de enviar una solicitud de orden de pago:


Ejemplo de la respuesta recibida del API
  1. {
  2.     "statusCode": 200,
  3.     "body": {
  4.         "session": "8798d8b0-6835-47c2-8643-c286fc219988",
  5.         "token": "dc0c4c6d-3d67-4992-b882-a781b693f374"
  6.     },
  7.     "headers": {
  8.         "...": "..."
  9.     },
  10.     "request": {
  11.         "uri": {
  12.             "...": "..."
  13.         },
  14.         "method": "post",
  15.         "headers": {
  16.             "...": "..."
  17.         }
  18.     }
  19. }

A continuación, se muestra un ejemplo en javascript del envío de la solicitud al endpoint de creación de órdenes de pagos. Esta función también obtiene el “body” del objeto tipo JSON que se recibe como respuesta.

Ejemplo de solicitud POST al API para crear una orden de pago
  1. var body = {
  2.     "secret": "your_secret",
  3.     "merchantId": "your_merchant_id",
  4.     "terminal": "your_terminal",
  5.     "amount": ####,
  6.     "currency": "CRC",
  7.     "description": "Pago tiquete de parqueo",
  8.    "orderReference": "xwr1092",
  9.    "callback": "https://yourhost.url/callback"
  10. }
  11.  
  12. var unirest = require("unirest");
  13. function postCreateOrder(data) {
  14.   return new Promise(function (resolve, reject) {
  15.     unirest.post("https://sandbox-merchant.greenpay.me/")
  16.       .headers({
  17.         "Accept": "application/json",
  18.         "Content-Type": "application/json",
  19.       })
  20.       .send(JSON.stringify(data))
  21.       .end(function (response) {
  22.         if (response.status === 200) {
  23.           console.log( JSON.stringify("body:",response.body));
  24.           resolve(response.body);
  25.         } else {
  26.           reject(response.body);
  27.         }
  28.       });
  29.   });
  30. }

    • Related Articles

    • Proceso de pago con formulario de GreenPay

      En esta sección se muestra una guía paso a paso de cómo integrarse al servicio de pagos por medio del formulario web. Para utilizar esta funcionalidad es necesario haber creado una orden de pago, para crear la orden pago puede revisar el  ...

    • Proceso de pago sin formulario de GreenPay

      En esta sección se muestra una guía paso a paso de cómo integrarse al API de pago. Para utilizar esta funcionalidad es necesario haber creado una orden de pago, para crear la orden pago puede revisar el  articulo "Crear una orden de pago" . Para ...

    • Crear una orden de tokenización

      La solicitud de creación de una orden de tokenización habilita al API de tokenización para que reciba una solicitud de tokenización con los datos que se reciben en la respuesta (session, token) de la solicitud de creación de una orden de ...

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