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.

Copy to clipboard
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;
    }
}
Note: - You can run this java code in any online java compiler to get the signature.

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

Copy to clipboard
{
"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