CashCom TopUp PayCenter API documentation

API to topup subscriber accounts of providers and sell digital goods in the system PayCenter

Version: 2.1
Last updated: 17 Jan 2024

Get started

    API Endpoint (API\_URL will be available after registration)

       https://API\_URL/joinCashcom/api/cashcom\_v2\_1

Login with your account and generate a secret token.

Requests are sent using the POST method. Requests are sent in JSON format. Each request contains the HTTP headers presented in the table below.

HEADERS
Key Description
customer_pin_number Prepaid card PIN code.
serial_nr Serial number of prepaid card PIN code.
screen_info Contains information to display the product to the buyer.
receipt_text Contains information for printing on a receipt.
transaction_id Transaction identifier at the end provider.

Signature generation

##example of generating a signature in PYTHON
srcSign = secretToken + request + pointId + API_PUBLIC_TOKEN
sign = hashlib.sha512(srcSign.encode('utf-8')).hexdigest()



##example of generating a signature in PHP
$srcSign = $secretToken.$request.$pointId.$API_PUBLIC_TOKEN;
$sign = hash('sha512', $srcSign);



//example of generating a signature in Java
String srcSign = secretToken + request + pointId + API_PUBLIC_TOKEN
MessageDigest md = MessageDigest.getInstance(algoritm);
md.reset();
byte[] buf = srcSign.getBytes();
StringBuilder builder = new StringBuilder();
md.update(buf, 0, buf.length);
buf = null;
buf = md.digest();
for (int j = 0; j < buf.length; j++) {
   builder.append(String.format("%02X", buf[j]).toLowerCase());
}
String signature = builder.toString();

The request signature is generated using the following algorithm: the original signature string, such as srcSign, is formed by concatenating strings of the following parameters: srcSign = secretToken + request + pointId + API_PUBLIC_TOKEN (!order is important).

Next, the srcSign string is encrypted using the SHA-512 algorithm
PARAMETERS
Field Description
secretToken The token you generated earlier.
request Request body to send.
pointId Point number (you also received this when generating the secret token).
API_PUBLIC_TOKEN Public API token (available after registration).

ping

## Here is a curl example
curl -i -X POST https://API_URL/joinCashcom/api/cashcom_v2_1/ping
-H 'CashCom-PointId: <YOUR_POINTID_HERE>' 
-H 'CashCom-Authorization-Type: Token' 
-H 'CashCom-Signature: <YOUR_SIGNATURE_HERE>' 
-H 'Content-Type: application/json' 
-d '{}'

The ping request does not perform any business processes and is only executed to check the availability of the CashCom server and authorization means.

Request URL :

https://API_URL/joinCashcom/api/cashcom_v2_1/ping

Result example :

{
    "code": 0,
    "comment": "27.01.2024 14:55:16 EET ver. 2.1"
}

get price

## Here is a curl example
curl -i -X POST https://API_URL/joinCashcom/api/cashcom_v2_1/getprice
-H 'CashCom-PointId: <YOUR_POINTID_HERE>' 
-H 'CashCom-Authorization-Type: Token' 
-H 'CashCom-Signature: <YOUR_SIGNATURE_HERE>' 
-H 'Content-Type: application/json' 
-d '{
     "countryCode":"VN"
     }'

Request a price list (list of products).

Request URL :

https://API_URL/joinCashcom/api/cashcom_v2_1/getprice

Result example :

{
    "code": 0,
    "comment": "ok",
    "products": [{
            "productPriceType": "FIXED",
            "countryCodes": ["VN"],
            "productCode": "13",
            "categoryId": 1,
            "providerName": "Gmobile Vietnam",
            "name": "500000 VND",
            "currency": "USD",
            "price": 2778,
            "fields": [{
                    "name": "Account",
                    "code": "account",
                    "type": 1,
                    "regex_inputing": ".*",
                    "regex_complite": "\\d{5,12}",
                    "direction": "Enter your phone number without international code",
                    "display": true,
                    "confirm": false
                }]
        }, {
            "productPriceType": "FIXED",
            "countryCodes": ["VN"],
            "productCode": "217",
            "categoryId": 1,
            "providerName": "Vinaphone Vietnam",
            "name": "500000 VND",
            "currency": "USD",
            "price": 2778,
            "fields": [{
                    "name": "Account",
                    "code": "account",
                    "type": 1,
                    "regex_inputing": ".*",
                    "regex_complite": "\\d{5,12}",
                    "direction": "Enter your phone number without international code",
                    "display": true,
                    "confirm": false
                }]
        }, 
        ..............
        ]
}
QUERY PARAMETERS
Field Type Required Description
countryCode String optional Two-digit country code.
productCode String optional Product code in the system Cashcom.
RESPONSE PARAMETERS
Field Type Description
code Int Return code of request execution and processing result (see full list of return codes in section Return codes).
comment String Comments on the return code.
products List List of objects describing product configuration.
products.productCode String Product code in the system Cashcom.
products.productPriceType String Product price type (FIXED - fixed price of the product, RANGE - the buyer chooses the price from the range).
products.countryCode String Two-digit country code.
products.categoryId String Product category identifier in the system CashCom.
products.providerName String Provider name.
products.name String Product name.
products.currency String Product price currency.
products.price String Product price in units of minor currency (cents). Only for FIXED products.
products.destCurrency String Destination currency (local). Only for RANGE products.
products.destCurrencyRate String Conversion rate from product price currency to destination currency. Only for RANGE products.
products.fields List A list of objects that describe the format of attributes (input fields) to be transferred to the provider when purchasing a product (for example, phone number, account number, etc.).
products.fields.name String Attribute name
products.fields.code String Attribute code
products.fields.type Int Attribute type. Сan take the following values: 1 - Int, 2 - String, 4 - Boolean (true/false), 5 - Select (selecting a value from a predefined collection, the list of values is passed to the selects field), 6 - Double, 7 - Calculate (calculated value, a formula with Java Script syntax is used for calculation)
products.fields.regex_inputing String Regular expression defining the allowable set of characters when entering a value.
products.fields.regex_complite String Regular expression defining the allowable set of characters after the end of input (validation of the entered value).
products.fields.direction String Instruction for the buyer.
products.fields.example String Input example.
products.fields.order Int Order of fields, lower value - higher priority.
products.fields.display Boolean Show input field.
products.fields.confirm Boolean Display field value for buyer confirmation.
products.fields.def String Default field value.
products.fields.formula String Formula for calculating the value of the calculated field (Java Script syntax, variables - field codes, e.g. count*price).
products.fields.selects List List of objects defining possible values for a Select type field (selection from a limited set of values).
products.fields.selects.name String Name of the value (for display to the buyer).
products.fields.selects.value String Selected field value.

validate

## Here is a curl example
curl -i -X POST https://API_URL/joinCashcom/api/cashcom_v2_1/validate
-H 'CashCom-PointId: <YOUR_POINTID_HERE>' 
-H 'CashCom-Authorization-Type: Token' 
-H 'CashCom-Signature: <YOUR_SIGNATURE_HERE>' 
-H 'Content-Type: application/json' 
-d '{
    "orders": [{
            "id": "125358",
            "date": 1706409044132,
            "productCode": "201",
            "amount": 100,
            "currency": "USD",
            "attr": {
                "account": "209407828"
            }
        }]
}'

An order validation request is usually performed before a purchase request and serves to verify product availability and order parameters are filled out correctly.

Request URL :

https://API_URL/joinCashcom/api/cashcom_v2_1/validate

Result example :

{
    "code": 0,
    "comment": "ok",
    "validateResults": [{
            "id": "125358",
            "code": 0,
            "needNextStep": false,
            "comment": "Successfully"
        }]
}
QUERY PARAMETERS
Field Type Required Description
orders List yes List of orders.
orders.id String yes Unique identifier on the client side.
orders.date long yes Time to send the request (number of milliseconds since 1970).
orders.productCode String yes Product code in the system Cashcom.
orders.currency String yes Payment currency. Three digit currency code (ISO 4217 standard).
orders.amount Int optional Product price. Only for products with price type RANGE. In units of the minor currency (cents).
orders.attr Map optional Product price. Order details. The description of the list of details must be clarified in the product description, the result of calling the getPrice request. For most products selling airtime, you only need one attribute called account, which contains the subscriber's phone number.
RESPONSE PARAMETERS
Field Type Description
code Int Return code of request execution and processing result (see full list of return codes in section Return codes).
comment String Comments on the return code.
validateResults List List of order parameters validation objects.
validateResults.id String Unique order identifier on the client side.
validateResults.code Int Order verification result code (see full list of codes in section Verification codes).
validateResult.comment String Comments on the verification result code.
validateResult.needNextStep boolean Flag determining the need to call the validate operation again for clarification or verification of parameters.
validateResult.attr Map The attributes of the payment verification result contain parameters generated by CashCom or the provider, for example, to inform the client about the amount received in local currency, etc (see full list of reserved attributes in section Reserved attributes).

purchase

## Here is a curl example
curl -i -X POST https://API_URL/joinCashcom/api/cashcom_v2_1/purchase
-H 'CashCom-PointId: <YOUR_POINTID_HERE>' 
-H 'CashCom-Authorization-Type: Token' 
-H 'CashCom-Signature: <YOUR_SIGNATURE_HERE>' 
-H 'Content-Type: application/json' 
-d '{
    "orders": [{
            "id": "125357",
            "date": 1706361413172,
            "productCode": "1269.3885",
            "currency": "USD",
            "attr": {
                "account": "377384504"
            }
        }]
}'

The purchase request is used to batch send orders for the purchase of products, as well as to check the status of orders.

Request URL :

https://API_URL/joinCashcom/api/cashcom_v2_1/purchase

Result example :

{
    "code": 0,
    "comment": "ok",
    "statuses": [{
            "id": "125357",
            "status": 1,
            "isfinal": false,
            "comment": "Processing"
        }]
}
QUERY PARAMETERS
Field Type Required Description
orders List yes List of orders.
orders.id String yes Unique identifier on the client side.
orders.date long yes Time to send the request (number of milliseconds since 1970).
orders.productCode String yes Product code in the system Cashcom.
orders.currency String yes Payment currency. Three digit currency code (ISO 4217 standard).
orders.amount Int optional Product price. Only for products with price type RANGE. In units of the minor currency (cents).
orders.attr Map optional Product price. Order details. The description of the list of details must be clarified in the product description, the result of calling the getPrice request. For most products selling airtime, you only need one attribute called account, which contains the subscriber's phone number.
RESPONSE PARAMETERS
Field Type Description
code Int Return code of request execution and processing result (see full list of return codes in section Return codes).
comment String Comments on the return code.
statuses List List of orders processing result objects.
statuses.id String Unique order identifier on the client side.
statuses.status Int Order status code (see full list of codes in section Order statuses).
statuses.isfinal boolean Flag determining the finality of the status, if false, further clarification of the status is required.
statuses.comment String Comments on the status code.
statuses.attr Map Order processing result attributes contain parameters generated by CashCom or provider, for example, for displaying information in a receipt, etc (see full list of reserved attributes in section Reserved attributes).

get status

## Here is a curl example
curl -i -X POST https://API_URL/joinCashcom/api/cashcom_v2_1/getstatus
-H 'CashCom-PointId: <YOUR_POINTID_HERE>' 
-H 'CashCom-Authorization-Type: Token' 
-H 'CashCom-Signature: <YOUR_SIGNATURE_HERE>' 
-H 'Content-Type: application/json' 
-d '{
    "statuses": [{
            "id": "125357"
        }]
}'

The order status request is used to obtain order processing statuses.

Request URL :

https://API_URL/joinCashcom/api/cashcom_v2_1/getstatus

Result example :

{
    "code": 0,
    "comment": "ok",
    "statuses": [{
            "id": "125357",
            "status": 100,
            "isfinal": true,
            "comment": "Success"
        }]
}
QUERY PARAMETERS
Field Type Required Description
statuses List yes List of objects with order identifiers.
statuses.id String yes Unique identifier on the client side.
RESPONSE PARAMETERS
Field Type Description
code Int Return code of request execution and processing result (see full list of return codes in section Return codes).
comment String Comments on the return code.
statuses List List of orders processing result objects.
statuses.id String Unique order identifier on the client side.
statuses.status Int Order status code (see full list of codes in section Order statuses).
statuses.isfinal boolean Flag determining the finality of the status, if false, further clarification of the status is required.
statuses.comment String Comments on the status code.
statuses.attr Map Order processing result attributes contain parameters generated by CashCom or provider, for example, for displaying information in a receipt, etc.

Return codes

Return codes that determine the result of the request.

ATTENTION! These codes determine only the result of request processing, but do not determine the order status. Status сodes are used to determine the order status (see list of order status in section Order statuses)

Error Code Meaning
0 Request successfully processed.
1 Invalid request signature.
2 Invalid request details.
3 No permission to perform this operation.
100 Other error.

Order statuses

Order status codes determine the status of the order.

Code Final Meaning
0 yes No such order, order not found.
1 no Order in progress.
2 yes Order rejected.
3 yes Order cancelled.
4 no Order status is unknown, request status again later.
100 yes Order completed successfully.

Verification codes

Verification codes determine the result of order verification using a validate request.

Code Meaning
0 Successful verification.
1 Invalid details.
2 Invalid amount.
3 Invalid amountIn.
4 Invalid currency.
5 Product temporarily unavailable, please try again later.
6 Product not found or not connected to the point.
7 Point blocked.
8 Common error.

Reserved attributes

Below is a list of reserved attribute codes that are passed in the attr field of response.

Key Description
customer_pin_number Prepaid card PIN code.
serial_nr Serial number of prepaid card PIN code.
screen_info Contains information to display the product to the buyer.
receipt_text Contains information for printing on a receipt.
transaction_id Transaction identifier at the end provider.

Get in touch

Contact information

Email

sale@cashcom.net

Write to us