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. 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 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 que este proceso se realice desde el backend del comercio, para proteger lo 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

Para consumir el servicio se debe hacer 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 una llave secreta 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. name: Nombre del cliente involucrado.
  9. email: Correo del usuario.
  10. identification: Identificador único de un usuario.
  11. 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.
  1. 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.
  1. 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.
Otros datos que se pueden proporcionar son:

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

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

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

1.2. Orden de pago para el formulario web

Si lo que se desea es utilizar el formulario del checkout en vez de hacerlo por medio del API, a la estructura se debe agregar el parámetro callback. El parámetro callback debe ser una URL que debe proporcionar el comercio y es donde se recibirá la respuesta del formulario de checkout. 

El siguiente objeto muestra cómo se incluye el parámetro callback.

{
"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", //This is que callback param require for checkout form
"additional": {
//all requiered additional data
}
}


1.3 Orden de pago con Credix 

Para procesar ordenes de pago con Credix, se debe cumplir con todos los campos requeridos en la orden de pago normal. Además, se debe agregar un parámetro llamado numberOfPayments que debe contener un arreglo de strings que corresponde a la cantidad de meses soportados por la terminal de Credix.

Para consumir el servicio se debe hacer 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",
"numberOfPayments": ["3", "6", "12"], //required for credix
"additional": {
//all requiered additional data
}
}

Agregar el parámetro callback si se va utilizar el formulario checkout.

1.4 Orden de pago con varias terminales

Si el comercio quiere crear la orden con varias terminales, estas se deben agregar en el parámetro terminal como un arreglo.
Esta opción es recomendada con el formulario de checkout, para ellos debe agregar el parámetro callback.
El siguiente objeto JSON muestra cómo se debe enviar el parámetro terminal para que soporte varias terminales.

{
"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"
], //terminal array
"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": {
//all requiered additional data
}
}

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.


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


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",
"numberOfPayments": ["3", "6", "12"],
"additional": {
//all required data
}
}
}

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

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

    • Proceso de pago con webform

      Consideraciones Para utilizar el formulario de pago de Greenpay, se debe considerar los siguiente: El formulario está disponible en: Sandbox: https://sandbox-checkoutform.greenpay.me/ Producción: https://checkout-form.greenpay.me/ Tener ...

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