Create payment order

Create payment order

To consider

A payment order is created to prepare the Greenpay API for a make a payment process. The following aspects have to be consider:
  1. Use these endpoints:
    1. Sandbox: https://sandbox-merchant.greenpay.me/
    2. Production: https://merchant.greenpay.me/
  2. The response is an JSON that contains and transaction token and session.
  3. The transaction token and session is valid for 30 minutes since it  was created. After this time the session and the token will expire, therefore another payment order must be generated.
  4. It is recommended do this process from the backend side of the application.

Step of using the service

1. Data structure

1.1 Payment order

In order to use the service send a post request with the follow structure.

{
"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",
"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"
}],
"details":{
"description":"description",
"seller":"seller",
"other":"other details"
}
}
}


The required data are:


  • secret: secret key provided by Greenpay. (String)

  • merchantId: merchant unique identifier provided by Greenpay. (String)

  • terminalId: bank terminal id provided by Greenpay. (String)

  • amount: order amount in numbers. (Int)

  • currency: currency type code configured in the terminal, example CRC or USD. (String)

  • description: order description, example, parking ticket payment. (String)

  • orderReference: Unique identifier for an order. It must be handled by the merchant

  • name: Complete user name.

  • email: Unique user email.

  • identification: Unique user identification.

  • shippingAddress:  

    • country: country code according to ISO 3166-1 alpha2. (String)

    • street1: exact customer address. (String)

  • billingAddress:  

    • country: country code according to ISO 3166-1 alpha2. (String)

    • street1: exact customer address. (String)

  • products:

    • description: product description. Example: parking ticket. (String)

    • skuid: merchant product id. Example: tc_10001. (String)

    • quantity: product quantity bought by the user. (Int)

    • price: product price. (Double)

    • type: product type. Ecample: digital ticket (String)


Optional params
  1. callback: This field (url) is only necessary if the application uses the checkout form provided
    by Greenpay. The callback is used to redirect the form to that address. In case of success or
    failure, the base url will be invoked, in case the request is canceled a cancel resource will be
    invoked on the base.

  • shippingAddress: 

    • province: province name. (String)

    • city: city name. (String)

    • street2: exact address. (String)

    • zip: user address postal code. (String)

  • billingAddress: 

    • province: province name. (String)

    • city: city name. (String)

    • street2: exact address. (String)

    • zip: user postal code. (String)

  • details: Any useful information for the merchant or other information required by Greenpay.


1.2 Orden de pago con credix

If the payment is going to be process with CREDIX, the JSON structure have to comply with the same mandatory data established in section 1.1 Payment order. 
However, the param numberOfPayments have to be added. This param indicates how many payments the customer is going to do for a product. Commonly, the values are 3, 6 and 12 month, like this:

  1. numberOfPayments:["3","6","12"]
In order to use the service send a post request with the follow structure.

{
"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": {
"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"
}],
"details":{
"description":"description",
"seller":"seller",
"other":"other details"
}
}
}


2. Send POST request


An HTTP POST type request must be sent to the payment order creation endpoint. It needs to be sent with the JSON created in the previous step.

Once the request has been sent and it has been successfully completed, a JSON object is obtained in response.

To receive this response, the parameter must be obtained from the JSON located in the “body”, since it contains the session and the token that must be sent to execute the deduction to the corresponding card.

The following image shows an example of the response received after submitting a payment order request: 


API response example

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


The following code is a javascript example of the payment order creation endpoint request. This function also obtains the JSON object “body” that is received in response.

Payment order POST to API example

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

    • Webform payment process

      To consider To use the card payment form, the following aspects should be considered: The form is available at: Sandbox: https://sandbox-checkoutform.greenpay.me/ Producción: https://checkout-form.greenpay.me/ Get a session and token of a valid ...

    • Create tokenization order

      To consider A tokenization order is created to prepare the Greenpay API for create a token from credit or debit card data. The following aspects have to be consider for it: Use these endpoints: Sandbox: https://sandbox-merchant.greenpay.me/tokenize ...

    • Create subscription

      For this service, the following endpoint must be consumed:  https://sandbox-merchant.greenpay.me/subscriptions Step by step to successfully create a subscription in our API : 1. Create the JSON object to be sent It must contain the following ...

    • Manual payment

      For this service, the following endpoint must be consumed:  https://sandbox-merchant.greenpay.me/subscriptions/pay Step by step to process a successful manual payment in our API:  1.Create the JSON object to be sent. JSON structure example {   ...

    • Widget payment process

      To consider Para utilizar el widget de pago de Greenpay, se debe considerar los siguiente: You must have a sandbox or production account, to obtain a sandbox account visit About sandbox or test account. The payment widget is a web element that can be ...