Crear orden de pago

Crear orden de pago

Consideraciones 

Una 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:
  1. Tener acceso al endpoint:
    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 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.
  4. Se 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.
  5. La orden de pago se debe crear siempre, indiferentemente si el servicio adquirido es integración directamente con el API de pagos o por medio del formulario de GreenPay.

Pasos para uso del servicio

1. Estructura de los datos

1.1. Orden de pago

Si se quiere crear  una orden de pago se se debe utilizar la siguiente estructura.
  1. {
      "secret": "Njg3RDM5RDc1QkE3MzI0MTJEM0YwMjAxRjdFRDQ4NUI2RUQ2NEU2RDQ3NkVCMDJEMTNEQzEyQTUyMkY2RURBMjkxODY2OTFDRDBBMTM1QTE4OTdCNzkzNzhBREQ3QkU5RTMxMUFGODNEMzQ0NzY3MjAzQjVDQjNEQjBDRDJGQzk=",
      "merchantId": "06c229a2-2632-46ac-a9a5-f63397e59573",
      "terminal": "Postman Examples-efe6-BNCR-CRC",
      "amount": 591,
      "currency": "CRC",
      "description": "Compra producto 625",
      "orderReference": "8f051999-c482-46e0-af75-c6be65906906",
      "additional": {
          "customer": {
              "name": "User Example",
              "email": "user@example.com",
              "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,
                  "type": "Tipo de producto"
              }
          ],
          "details": {
              "seller": "abcs",
              "topic": "qwer"
          }
      }
    }


Los datos que se deben proporcionar son lo siguientes:

 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. Estos son provistos 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.

  4. name, email, identification: Si el comercio tiene la información, es recomendado enviarlos. En caso que no los tenga, se recomienda no enviar estos parámetros.

  5. details: Es un parámetro opcional que se pone a disposición de los comercios, donde se puede agregar cualquier información que sea relevante para el comercio. Por ejemplo, vendedores de productos.

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

1.2 Orden de pago con varias terminales

Si se quieren presentar en el formulario de pago, varias terminales, el POST de crear orden de pago debe tener la siguiente estructura.

  1. {
      "secret": "Njg3RDM5RDc1QkE3MzI0MTJEM0YwMjAxRjdFRDQ4NUI2RUQ2NEU2RDQ3NkVCMDJEMTNEQzEyQTUyMkY2RURBMjkxODY2OTFDRDBBMTM1QTE4OTdCNzkzNzhBREQ3QkU5RTMxMUFGODNEMzQ0NzY3MjAzQjVDQjNEQjBDRDJGQzk=",
      "merchantId": "06c229a2-2632-46ac-a9a5-f63397e59573",
      "terminal": [
          "Postman Examples-efe6-BNCR-CRC",
          "Postman Examples-efe6-BAC-CRC",
          "Postman Examples-efe6-CREDIX-CRC"
      ],
      "amount": 591,
      "currency": "CRC",
      "description": "Compra producto 625",
      "orderReference": "8f051999-c482-46e0-af75-c6be65906906",
      "additional": {
          "customer": {
              "name": "User Example",
              "email": "user@example.com",
              "identification": "Identificador único del usuario",
              "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,
                  "type": "Tipo de producto"
              }
          ],
          "details": {
              "seller": "abcs",
              "topic": "qwer"
          }
      }
    }

Los datos que se deben proporcionar son lo siguientes:

 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 (si es solo una terminal) o un arreglo de String (si se tienen varias terminales). Estos son provistos 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.

  4. name, email, identification: Si el comercio tiene la información, es recomendado enviarlos. En caso que no los tenga, se recomienda no enviar estos parámetros.

  5. details: Es un parámetro opcional que se pone a disposición de los comercios, donde se puede agregar cualquier información que sea relevante para el comercio. Por ejemplo, vendedores de productos.

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

1.3. Orden de pago con varias terminales y Credix

Si se quieren presentar en el formulario de pago, varias terminales y que soporte pagos con Credix, se debe de cumplir con los mismos parámetros definidos en la sección Orden de pago con varias terminales.
Sin embargo, a la estructura se le debe agregar el siguiente parámetro, que hace indica la cantidad de pagos que hará la persona que adquiere un producto o servicio del comercio, que son 3, 6 y 12 meses.
  1. numberOfPayments: ["3", "6", "12"]
Para consumir el servicio se debe hacer un POST con la siguiente estructura.
  1. {
      "secret": "Njg3RDM5RDc1QkE3MzI0MTJEM0YwMjAxRjdFRDQ4NUI2RUQ2NEU2RDQ3NkVCMDJEMTNEQzEyQTUyMkY2RURBMjkxODY2OTFDRDBBMTM1QTE4OTdCNzkzNzhBREQ3QkU5RTMxMUFGODNEMzQ0NzY3MjAzQjVDQjNEQjBDRDJGQzk=",
      "merchantId": "06c229a2-2632-46ac-a9a5-f63397e59573",
      "terminal": [
          "Postman Examples-efe6-BNCR-CRC",
          "Postman Examples-efe6-BAC-CRC",
          "Postman Examples-efe6-CREDIX-CRC"
      ],
      "amount": 591,
      "currency": "CRC",
      "description": "Compra producto 625",
      "orderReference": "8f051999-c482-46e0-af75-c6be65906906",
      "numberOfPayments": [
          "3",
          "6",
          "12"
      ],
      "additional": {
          "customer": {
              "name": "User Example",
              "email": "user@example.com",
              "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,
                  "type": "Tipo de producto"
              }
          ],
          "details": {
              "seller": "abcs",
              "topic": "qwer"
          }
      }
    }​

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 con el objeto JSON creado en el paso anterior en el cuerpo de la solicitud. La respuesta será un JSON con una session y un token necesario para efectuar el pago.


Ejemplo 1. Respuesta en formato JSON del la solicitud de crear orden de pago.

  1. {
      "statusCode": 200,
      "body": {
          "session": "8798d8b0-6835-47c2-8643-c286fc219988",
          "token": "dc0c4c6d-3d67-4992-b882-a781b693f374"
      },
      "headers": {
          "...": "..."
      },
      "request": {
          "uri": {
              "...": "..."
          },
          "method": "post",
          "headers": {
              "...": "..."
          }
      }
    }

3. Redirigir al formulario de pago GreenPay

Para efectuar el pago por medio del formulario provisto por GreenPay se debe hacer redirigir  a las siguientes endpoints:
  1. Sandbox: https://sandbox-checkoutform.greenpay.me/{{session}}
  2. Producción: https://checkout-form.greenpay.me/{{session}}
Donde el session es la obtenida en como resultado del POST de creación de la orden. En la siguiente imagen se muestra un ejemplo del resultado de la redirección.







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

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

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