Documentation

Payment protocol PaymentsAPI

Find out how we can help you. For more information, contact us today ! .

General description of the protocol

Technology: REST HTTP API

Data format: JSON

List of methods:

• Init - payment initialization
• Confirm - confirmation of payment

Authentication:

• Client certificate
• HMAC signature

2. Authentication

2.1 Client certificate

Each request must contain information about the client certificate An example of using a client certificate in the code of a test utility:

            var client = new RestClient(url);
            if (File.Exists(clientCertPath))
            {
              X509Certificate2 clientCert = new X509Certificate2(clientCertPath, certPass);
              client.ClientCertificates = new X509CertificateCollection() { clientCert };
            }   
 

,where

<clientCertPath –> path to certeficate

<certPass –>pswd of certeficate

If you need more information, please contact US

2.2 Signature HMAC

            If
            CLIENT = Client ID
            BODY = request body (JSON)
            TS = unix timestamp (UTC+0) in milliseconds (calculated each time before request)
            API-SECRET = client's private key
            
            , then the message to sign would be:
            MESSAGE = CLIENT + TS + BODY 
            
            We calculate the signature as HMAC-SHA256
            from MESSAGE using a private key API-SECRET
            and then convert the byte array to string HEX - format
            SIGN = HEX (HMAC-SHA256(MESSAGE, API-SECRET))
            
            When sending a request, fill in the following HTTP headers:
            RP-CLIENT = CLIENT 
            RP-TS = TS
            RP-SIGN = SIGN  
             

            CLIENT = N1Lin11
            BODY = {
            "clientTranId": "130",
            "account": "282380",
            "amount": 54.80,
            "commissionAmount": 1.50,
            "currency": "DZ",
            "operatorCode": 5293
            }

            TS =1614696692368
            API-SECRET = 12345

            , then the message to be signed will be:
            MESSAGE = N1Lin111614696692368{
            "clientTranId": "130",
             "account": "282380",
             "amount": 54.80,
             "commissionAmount": 1.50,
             "currency": "DZ",
             "operatorCode": 5293
            }
 

We calculate the signature as HMAC-SHA256 from MESSAGE using a private key API-SECRET and then convert the byte array to string HEX - format SIGN = HEX (HMAC-SHA256(MESSAGE, API-SECRET)) = 108b03d50319b9422df3a121991c474fa441df41f94c62683373099d473275b0

When sending a request, fill in the following HTTP headers:

RP-CLIENT N1Lin11

RP-TS 1614696692368

RP-SIGN 108b03d50319b9422df3a121991c474fa441df41f94c62683373099d473275b0

    var body = edtRequest.Text;
    var request = new RestRequest(Method.POST).AddJsonBody(body);
    
    //sign
    var timestamp = ToTimeStampLong(DateTime.UtcNow);
    var teminalid = edtCLIENT.Text;
    var strToSign = $"{teminalid}{timestamp}{body}";
    var secret = edtSECRET.Text;
    
    string sign = string.Empty;
    var keyByte = Encoding.UTF8.GetBytes(secret);
    byte[] inputBytes = Encoding.UTF8.GetBytes(strToSign);
    using (var hmac = new HMACSHA256(keyByte))
    {
        byte[] hashValue = hmac.ComputeHash(inputBytes);
        sign = ByteArrayToHEXString(hashValue);
    }
    
    request.AddHeader("RP-CLIENT", teminalid);
    request.AddHeader("RP-TS", timestamp.ToString());
    request.AddHeader("RP-SIGN", sign);
    
    ------
    
    public static long ToTimeStampLong(DateTime dt)
    {
        long timestamp = (Int64)(dt.Subtract(new DateTime(1970, 1, 1))).TotalMilliseconds;
        return timestamp;
    }
    
    private static string ByteArrayToHEXString(byte[] ba)
    {
        return BitConverter.ToString(ba).Replace("-", "").ToLower();
    }
    

3. Service methods

3.1 [Payment/Init] Payment initialization method

Request type: POST

This is the first request in a billing session. At this stage, various checks are carried out for the correctness of the payment data and for the possibility of performing this operation.

Request example:

  {
    "clientTranId": "1618817505702",
    "account": "213780221111",
    "amount": 1.00,
    "commissionAmount": 0.00,
    "currency": "DZ",
    "operatorCode": 101,
    "operatorParams": {
       "CheckedIDNP": "2000003147230"
     }
   } 

,where

clientTranId - transaction number in the client's system (optional)

account - account

amount – amount to pay

commissionAmount - commission amount

currency - currency

operatorCode - operator code

operatorParams - incoming operator parameters (each operator has its own parameters)

Sample response:

  {
    "serverTranId": 554161817,
    "account": "213780221111",
    "amount": 1,
    "operatorCode": 101,
    "operatorParams": {
      "MonthLimitIncome": "499997838,00",
      "MonthLimitOutgo": "499997844,46",
    },
    "status": "InitSuccess",
    "errorCode": 0,
    "errorMessage": "No Errors"
  }  

,where

serverTranId - transaction identifier (This value then needs to be substituted in the Confirm request)

operatorParams - various operator parameters

status – transaction status (see description of statuses)

errorCode - error code (see description of error codes)

errorMessage error description

operatorParams - outgoing operator parameters

3.2. [Payment/Confirm] Payment confirmation method

Request type: POST

This method is called after successful initialization to process the payment.

Request example:

  {
    "serverTranId": 554161817,
    "account": "213780221111",
    "amount": 1.00,
    "commissionAmount": 0,
    "currency": "DZ",
    "operatorCode": 101
  }

,where

serverTranId - transaction number (comes in response to /Init)

Sample answer:

  {
    "serverTranId": 554161817,
    "account": "213780221111",
    "amount": 1,
    "commissionAmount": 0,
    "commissionType": 0,
    "operatorCode": 101,
    "operatorParams": {
      "MonthLimitIncome": "499997838,00",
      "MonthLimitOutgo": "499997844,46",
    },
    "status": "PaySuccess",
    "errorCode": 0,
    "errorMessage": "No errors"
  }   

3.3. [Payment/Check] Payment verification method

Request type: POST

This method is called to clarify the status of the sent payment or check if the operation ended with an error or the connection was interrupted.

Request example:

  {
    "clientTranId": "1618817505702",
    "serverTranId": "7505702"
  }     

,where

clientTranId - transaction number in the client's system

serverTranId - transaction number in the RunPay system (comes in response to Init/Confirm)

It is enough to fill in one of the parameters.

If both parameters are filled, then the priority serverTrandId.

The response is identical to the response to the Init/Confirm methods.

3.4. [/Balance] Payment verification method

Request type: GET

Note This method is used to query the user's balance.

Request example:

  {
    "balance": "12300.45"
  }     

4. Basic scenario for making a payment

• Sending request /Init
• From the answer we take serverTranId and substitute in the request /Confirm
• We send request /Confirm