This manual’s purpose is to instruct on how to integrate an application against our API REST. First, to do this, we have to configurate certain information or data in the Zest application, after that, we must create (or build) a URL with which we can use this service, for that the app user’s Api Key will be necessary.

Additionally, if we want our integrated application to have all the information about transactions, it will be necessary to create two Web services, one for payments and another one for refunds.

Any knight have a very done workable and doing it as a very wonderfull done and subscriptions dejamos elcontenido de los usuarios que quieran suscribirse: en cuanto paguen deberían

User keys

Each API user has two keys, an API access key (apiKey) and another private and secret key (secretKey) that will be used to sign the requests. This second key is private, non-transferable and will not travel in requests to the API.

Summary: Key for signing request to API

Example: 6629a8bbe29524bb57f15956b194cc2a35eefa503287ddeeb4c73d1e63622300bebbe844e1b64209

Descripción: Key for users access

Example: 67B2298C03E39C365D47

API request table

All requests to the API conform to a particular format, must provide mandatory parameters in the header, and must be signed following an encryption algorithm. In order to continue, it is explained in detail:

Required parameters in the header of all requests:

Constructing API request

Signature calculation:

As shown in the table in the “API Requests Table” section it is necessary to pass the signature parameter with the signature of the request. The steps to sign are:

String msg = serviceName + salt + apiKey + secretKey + bodyStr;

serviceName:   The name of the service being called.

salt:                       String  (Random string of maximun 10 characters).

apiKey:                User key access.

secrectKey:        Private user key.

body:                    Body of the request. – Empty string will be passed if thereis no body. Alseo, the body cannot have white space.

Once built to the previous string, the HMACSHA256 algorithm is used to encrypt it. The signature is the result of base64 encoding the result of encryption. JAVA code example. 

Then as an example, the generation of a signature for the API is encoded in JAVA.

A continuación, a modo de ejemplo, se codifica en JAVA la generación de una firma para la API.

String msg = serviceName + salt + apiKey + secretKey + body;

String algorithm = “HmacSHA256”;

String StrhashCode = hmacDigest(msg,  secretKey,  algorithm);

String signature= base64. getEncoder(). encodeToString(StrhashCode.getBytes());

private static String hmacDigest(String  msg, String  secretKey,String  algoritmo){

       

String digest  =  null;

        try {

SecretKeySpec key  =  new  SecretKeySpec((secretKey).getBytes(“ASCII”),  algoritmo);

Mac mac  = Mac. getInstance(algorithm);

            mac.init(key);

           

byte[]bytes  =  mac.doFinal(msg.getBytes(“ASCII”));

StringBuffer hash  =  new  StringBuffer();

for (int  i  = 0; i  <  bytes. length;  i++) {

String hex  = Integer. toHexString(0xFF &  bytes[i]);

                if (hex.length() == 1) {

                    hash.append(‘0’);

                }

                hash.append(hex);

            }

digest =  hash.toString();

} catch  (UnsupportedEncodingException  e){

            System. out.println(“hmacDigest UnsupportedEncodingException”);

        }

catch (InvalidKeyException  e){

            System. out.println(“hmacDigest InvalidKeyException”);

        }

catch (NoSuchAlgorithmException  e){

            System. out.println(“hmacDigest NoSuchAlgorithmException”);

        }

        return digest;

}

REST API Integration

The stepst to follow for an integration via REST will be as follows:

CRM Landing

1

It is necessary to connect to the web using the user's credentials.

CRM

2

Once logged in, click on 'User Details' within the left side menu.

Profile

3

Then, we will see a panel like this, which shows us the main data of the user, including the API Key. Select the 'Edit' button.

Callback

4

Within the ‘Edit User’ section we will select the ‘Response Url’ field. When pressed, it will be displayed as follows.

Response

5

Response URL will be the section that will allow us to integrate with the REST API.

Callback URL: This will be the address to which transactions are sent.

Refund Callback URL: This will be the address to which refund-type transactions are sent.

We advise that depending on whether you are going to work in a production environment or not, the client should put in the commented sections the URLs correctly.

There are three buttons each with a functionality: 

This button automatically generates an Api Key and Secret Key to the user that will allow him to integrate with the REST API.

Makes a request to our application that will return a test transaction for the user to receive at the URL specified in “Callback URL”.

Makes a request to our application that will return a trial refund type transaction for the user to receive at the URL specified in “Refund callback URL”. It is important to save the user for the changes to be effective.

Callback

Each time a transaction changes status, all transaction information is sent through the URL provided by the user in the “Callback URL” and “Refund Callback URL” sections. 

Value

id

date

amount

status

Data type

number (-2147483648 a 2147483647)

Date con formato (yyyy-MM-d)

decimal

string

Description

Unique transaction identifier

Order creation date

Amount that is issued in the payment of the order

Different states in which an order can be found: (“Pending”, “Sent”, “Sign Pending”, “Completed”, “Refund”, “Chargeback”, “Error”)

Example

100

2021-12-17

1000.50

“Pending”

The user must create a “Web Service” to receive notifications of the created transactions and another like the previous one for the returned transactions. Here we can see a JSON response example:

{

   “status”:”OK”,

   “message”:”Process successfully”,

   “content”: [

      {

         “id”:100,

         “amount”:1000.50,

         “status”:”Pending”,

         “date”:”2020-12-17″

      }

   ]

}

Services

The published API services:

Service

ordersExt

ordersExtDetail

redirect

Method

POST

POST

POST

Description

List the orders belonging to a user

Offers the detail of the requested order

Provides the registrations URL of a new order for the user making the request

ordersExt

ContentType  *string                Indicates that the data travels in JSON format.

apikey             *string                  API Key user

salt                  *string                   Random string, maximun 10 characters used for the signature.

signature        *string                  Signature computed for the request.

None. Example response:

{

    “status”: “OK”,

    “message”: “Process successfully”,

    “content”: [

        {

            “date”: “2021-04-06”,

            “amount”: 200,

            “id”: 30067,

            “status”: “Sent”

        },

        {

            “date”: “2021-04-08”,

            “amount”: 150,

            “id”: 30068,

            “status”: “Pending”

        }

    ]

}

Value

id

date

amount

status

Data type

number (-2147483648 a 2147483647)

Date con formato (yyyy-MM-d)

decimal

string

Description

Unique transaction identifier

Order creation date

Amount that is issued in the payment of the order

Different states in which an order can be found: (“Pending”, “Sent”, “Sign Pending”, “Completed”, “Refund”, “Chargeback”, “Error”)

Example

100

2021-12-17

1000.10

“Completed”

ordersExtDetail

ContentType  *string                Indicates that the data travels in JSON format.

apikey             *string                  API Key user

salt                  *string                   Random string, maximun 10 characters used for the signature.

signature        *string                  Signature computed for the request.

idOrder           *string                  id de la orden de la que se solicita el detalle.

Example: {“idOrder =”30067”}

Example response:

{

    “message”: “Process successfully”,

    “content”: [{

        “date”: “2021-04-06”,

        “amount”: 200,

        “id”: 30067,

        “status”: “Sent”

    }],

    “status”: “OK”

}

Value

id

date

amount

status

Data type

number (-2147483648 a 2147483647)

Date con formato (yyyy-MM-d)

decimal

string

Description

Unique transaction identifier

Order creation date

Amount that is issued in the payment of the order

Different states in which an order can be found: (“Pending”, “Sent”, “Sign Pending”, “Completed”, “Refund”, “Chargeback”, “Error”)

Example

100

2021-12-17

1000.10

“Completed”

Redirect

ContentType  *string                Indicates that the data travels in JSON format.

apikey             *string                  API Key user

salt                  *string                   Random string, maximun 10 characters used for the signature.

signature        *string                  Signature computed for the request.

None. Example response:

{

     “message”: “Process successfully”,

     “content”: [

{

    “url”:  https://crm.zestpayments.com/#/apiform/67B2298C03E39C365D47

}],

   

“status”: “OK”

}

Value

url

Data type

string

Description

Redirect URL to complete the payment

Errors

ERROR_IN_PARAMS

INCORRECT_SIGNATURE

UNKNOWN_API_KEY

ORDER_NOT_FOUND

NO_AUTHORIZED

ID_ORDER_ERROR

Error in the format of the parameters or lack of any of them

Invalid signature

API Key is not valid

Order not found

Not authorized to obtain the requested information

Error in the idOrder parameter