Summary
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.
- secretKey
Summary: Key for signing request to API
Example: 6629a8bbe29524bb57f15956b194cc2a35eefa503287ddeeb4c73d1e63622300bebbe844e1b64209
- apiKey
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:
Data type: string
Description: User key access
Example: 7E1D9BF9A76BA0782452
Data type: string (maximun 10 caharacters)
Description: Cheksun chain
Example: jrewgbfemz
Data type: string
Description: Signature of the petition
Example: QwMDUwNDRkMTI0NTJiYjU5YTNmNGNkYTdkMDI5Y2I1MDFkZGJkN2YwYWJjOWRlZDBiYWZkZA==
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:
- Construct the string to sign
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.
- Ejemplo de código 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:
1
It is necessary to connect to the web using the user's credentials.
2
Once logged in, click on 'User Details' within the left side menu.
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.
4
Within the ‘Edit User’ section we will select the ‘Response Url’ field. When pressed, it will be displayed as follows.
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:
- Generate API Key
This button automatically generates an Api Key and Secret Key to the user that will allow him to integrate with the REST API.
- Test Callback
Makes a request to our application that will return a test transaction for the user to receive at the URL specified in «Callback URL».
- Test Refund Callback
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
- Headers
Content–Type *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.
- Body Parameters
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
- Headers
Content–Type *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.
- Body Parameters
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
- Headers
Content–Type *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.
- Body Parameters
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
