Developers
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
- SecretKey :
Key for signing requests to API.
- ApiKey :
Key for user access.
Examples
- SecretKey :
ads5d54g544kljl4454g54gv1c5bh4fd545rf4sdf1
- ApiKey :
t454fdgdf4gtr5y4rtyuutj4h5g4hjfg4h54h
API Requests 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
parameter | Data type | description | example |
---|---|---|---|
apiKey |
String | User access key | 7E1D9BF9A76BA0782452 |
salt |
string (maximum 10 characters) | Cheksun chain | jrewgbfemz |
signature |
String | Signature of the petition | QwMDUwNDRkMTI0NTJiYjU5YTNmNGNkYTdkMDI5Y2I1MDFkZGJkN2YwYWJJOWRlZDBiYWZkZA== |
Constructing API requests
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;
- Salt :
String (Random string of maximum 10 characters).
- SecretKey :
Private user key.
- ApiKey :
Access key user.
- Body : Body of the request. – Empty string will be passed if there is no body.
- 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.
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.UnsupportedEncodingException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
public class Test {
private static String serviceName = "service name";
private static String salt = "salt";
private static String apiKey = "apiKey";
private static String secretKey = "secretKey";
private static String body = "{}";
public static void main(String[] args){
String msg = serviceName + salt + apiKey + secretKey + body;
String algorithm = "HmacSHA256";
String strHashCode = hmacDigest(msg, secretKey, algorithm);
String signature = Base64.getEncoder().encodeToString(strHashCode.getBytes());
System.out.println("Signature: " + signature);
}
private static String hmacDigest(String msg, String secretKey, String algorithm){
String digest = null;
try {
SecretKeySpec key = new SecretKeySpec(secretKey.getBytes("ASCII"), algorithm);
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: " + e.getMessage());
} catch (InvalidKeyException e){
System.out.println("hmacDigest InvalidKeyException: " + e.getMessage());
} catch (NoSuchAlgorithmException e){
System.out.println("hmacDigest NoSuchAlgorithmException: " + e.getMessage());
}
return digest;
}
}
REST API Integration
Steps for Integration via REST
- It is necessary to connect to the web using the user's credentials.
- Once logged in, click on 'User Details' within the left side menu.
- 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.
- Within the 'Edit User' section, select the 'Response URL’ field.
- When pressed, it will be displayed as follows.
- 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.
- URLs’ examples:
- 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 received | Data type | Description | Example |
---|---|---|---|
Id | number (-2147483648 to 2147483647) | Unique transaction identifier | 100 |
amount | decimal | Amount that is issued in the payment of the order | 1000.50 |
status | String | Different states in which an order can be found: ("Pending", "Sent", "Sign Pending", "Completed", "Refund", "Chargeback", "Error") | "Pending" |
date | Date formatted (yyyy-MM-d) | Order creation date | "2020-12-17" |
The user must create a "Web Service" to receive notifications of the created transactions and another like the previous one for the returned transactions.
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 Name | Method | Description |
---|---|---|
ordersExt | POST | Get list of orders |
ordersExtDetail | POST | Get order details by id |
createOrderExt | POST | Create order |
createOrderExtWithTpvSelected | POST | Create order with selected TPV |
createOrderEcheckExt | POST | Create Echeck order |
createOrderEcheckExtWithTpvSelected | POST | Create Echeck order with selected TPV |