Signature generation and verification

Overview

All the communication between merchant and the ECommPay payment platform is protected by using the TLS protocol version 1.2 or higher. This ensures message confidentiality while in transit, though the protocol cannot guarantee message integrity and ensure that the message author possesses the secret key. Therefore, every message must be digitally signed by using the secret key issued by ECommPay for the merchant and known only to the merchant and the ECommPay payment platform.

You must create and add a digital signature to every message you send to the ECommPay payment platform and verify signature of every message you receive from the payment platform, either synchronous or asynchronous. You can implement digital signature generation either from scratch or by using the SDK available from ECommPay. (For more information about the SDK, see SDK.).

There are many reasons why message integrity can be compromised, but in any case compromised messages data can never be considered as valid.

This section describes the algorithms for generation of digital signatures for outgoing messages and for integrity verification of incoming messages; also, this section includes examples that use these algorithms and forms that allow you to test signature generation and verification.

Signature generation

Signing algorithm

The algorithm input includes the following:

  1. Data to sign.

    Generally, this is all the parameters or JavaScript object configObj with all its parameters except for the signature parameter.

  2. Signing key.

    For debugging and testing purposes, you are free to use any signing key, though for signing requests in production environment, you are required to use your production secret key.

Depending on the algorithm implementation, its output may be either signature or signed JavaScript object configObj. Generally, the algorithm output consists of the object with integrated signature parameter.

The algorithm description, the example, and test form below include the most common algorithm implementation that includes JavaScript object configObj as input (without the signature parameter) and output (with the signature parameter).

Thus, the algorithm includes the following steps:

  1. Input validation Make sure the following requirements are met:

    1. Data conforms to the JavaScript object format.
    2. Data to sign does not contain any signature parameter even if it is empty.
    3. The signing key is readily available.
  2. Conversion of all the strings to UTF-8 with alphabetical sorting. Complete the following steps:

    1. Encode any Boolean values as follows: replace false with 0, replace true with 1.

      This rule applies only to Boolean values! If any string parameter contains "false" or "true" string value, the value is not replaced with 0 or 1 but is treated as any other string value.

    2. Leave any empty parameter values empty. In other words, do not replace any empty values with blank space or null. For instance, "payment_description":"" is replaced with payment_description:.
    3. Convert all the strings to UTF-8.
    4. Sort the strings in alphabetical order and join them in a single string by using semicolon (;) as a delimiter.
  3. Calculation of HMAC code by using the key and the SHA-512 hash function. Calculate the HMAC code for the string by using the SHA-512 hash function and secret key. The HMAC code must be calculated as a raw binary data.
  4. Encoding the HMAC code by using the Base64 scheme. Encoding the HMAC code by using the Base64 scheme to obtain the signature for the initial data.
  5. Adding signature. Add the signature parameter to the JavaScript object configObj using the signature from the previous step as its value.

Example of purchase request through Payment Page

Suppose that you need to generate a signature for a Payment Page request in the following scenario:

  • Secret key obtained from the ECommPay support service: secret.
  • The parameters you need to pass when opening Payment Page:
    • project_id: 12345
    • payment_id: X03936
    • payment_amount: 3550
    • payment_currency: USD
    • payment_description: Guyliner purchase
    • customer_first_name: Jack
    • customer_last_name: Sparrow
    • customer_phone: 02081234567

If you choose to open the payment page by using the configObj object, it will look similar to the following code (the order of the "parameter-value" pairs may be different):

{
"project_id": 12345, 
"payment_id": "X03936", 
"payment_amount": 2035, 
"payment_currency": "USD",
"payment_description": "Guyliner purchase",
"customer_first_name": "Jack",
"customer_last_name": "Sparrow",
"customer_phone": 02081234567,
"close_on_missclick": true,
"signature": "<digital signature to generate>" 
}

The task is to generate the signature; in other words, you need to compute the value for the signature parameter. The signature is generated as follows:

  1. Make sure there is no signature parameter in your request even it is empty:
    {
    "project_id": 12345, 
    "payment_id": "X03936", 
    "payment_amount": 2035, 
    "payment_currency": "USD",
    "payment_description": "Guyliner purchase",
    "customer_first_name": "Jack",
    "customer_last_name": "Sparrow",
    "customer_phone": 02081234567,
    "close_on_missclick": true,
    "signature": "<digital signature to generate>" 
    }
  2. Convert all the strings to UTF-8 as per algorithm description:
    project_id:12345 
    payment_id:X03936
    payment_amount:2035
    payment_currency:USD
    payment_description:Guyliner purchase
    customer_first_name:Jack
    customer_last_name:Sparrow
    customer_phone:02081234567
    close_on_missclick:1
  3. Sort the strings in alphabetical order:
    close_on_missclick:1
    customer_first_name:Jack
    customer_last_name:Sparrow
    customer_phone:02081234567
    payment_amount:2035
    payment_currency:USD
    payment_description:Guyliner purchase
    payment_id:X03936
    project_id:12345
    
  4. Join all the strings in a single string by using semicolon (;) as a delimiter:
    close_on_missclick:1;customer_first_name:Jack;customer_last_name:Sparrow;customer_phone:02081234567;payment_amount:2035;payment_currency:USD;payment_description:Guyliner purchase;payment_id:X03936;project_id:12345
  5. Calculate the HMAC code for the string by using the SHA-512 hash function and secret key, and then encode the HMAC code by using the Base64 scheme:
    vV1YUoH1XnSowQiJJEHHyBwuKxCy1t+TWwD+E/Q+OpeFagZpDT4TSi98yJGegIYbTTstx16+0IMCOMxizec/vA==
  6. Add the resulting signature in the configObj object:
    {
    "project_id": 12345, 
    "payment_id": "X03936", 
    "payment_amount": 2035, 
    "payment_currency": "USD",
    "payment_description": "Guyliner purchase",
    "customer_first_name": "Jack",
    "customer_last_name": "Sparrow",
    "customer_phone": 02081234567,
    "close_on_missclick": true,
    "signature": "vV1YUoH1XnSowQiJJEHHyBwuKxCy1t+TWwD+E/Q+OpeFagZpDT4TSi98yJGegIYbTTstx16+0IMCOMxizec/vA==" 
    }

Signature verification

Verification algorithm

The algorithm input includes the following:

  1. Signed data to verify.

    Generally, this is callback or response body in JSON format with the signature parameter.

  2. Verification key. It must be the same key that was previously used for signing the data to verify.

Depending on the algorithm implementation, its output may be either a generated signature or the information whether the generated signature matches the one included in the response or callback.

The algorithm description, the example, and test form below use the most common algorithm implementation that includes callback or response body in JSON format as input (without the signature parameter) and output (with the signature parameter) which is the result of signature verification.

Thus, the algorithm includes the following steps:

  1. Input validation Make sure the following requirements are met:

    1. Data conforms to the JSON format.
    2. Data to sign contains a signature parameter with the signature value.
    3. The signing key is readily available.
  2. Extracting signature from the data to verify. Store the value of the signature parameter value for further reference and remove the parameter from the input data.
  3. Generate signature for the data to verify. Complete steps 2 through 4 as specified in the signature generation algorithm description. (For more details, see the following link):
    1. Conversion of all the strings to UTF-8 with alphabetical sorting.
    2. Calculation of HMAC code by using the key and the SHA-512 hash function.
    3. Encoding the HMAC code by using the Base64 scheme.
  4. Signature matching Compare the generated signature with the signature stored in step 2. If the signatures match, the data are authentic and its integrity is considered confirmed; otherwise, the data is considered compromised and cannot be used for production purposes.

Example of callback verification

Suppose that you need to verify the signature a callback in the following scenario:

  • Signing key : secret.
  • The callback body contains the following information:

    Figure: Callback body

    {
      "request_id": "17cd0535c5ffecf5-335e5b5e",
      "transaction": {
        "id": 82452138542211,
        "date": "2019-10-09T07:13:36+0000",
        "type": "purchase"
      },
      "payment": {
        "id": "123456789",
        "method": "webmoney",
        "date": "2019-10-09T07:13:36+0000",
        "result_code": "9999",
        "result_message": "Awaiting processing",
        "status": "awaiting redirect result",
        "is_new_attempts_available": false,
        "attempts_timeout": 0,
        "cascading_with_redirect": false,
        "provider_id": 1234
      },
      "sum_real": {
        "amount": 29100,
        "currency": "USD"
      },
      "account": {
        "number": "79879496816"
      },
      "return_url": {
        "method": "GET",
        "body": {
          "shop": "1234567",
          "transaction": 45712154,
          "iframe": "true",
          "successUrl": "https://mysite.com/process/success",
          "failUrl": "https://mysite.com/process/failure",
          "target": "iframe"
        },
        "encrypted": []
      },
      "rrn": "",
      "general": {
        "project_id": 123,
        "payment_id": "457822332658",
        "signature": "NtDutuRiksyHeBhhUs+nQxQ1FcMSueoACb4vENju0APgHgeZfRfMj46289v1vD4hJ1a8Yhg=="
      },
      "description": "TEST_1543831735980",
      "sum_request": {
        "amount": 29100,
        "currency": "USD"
      },
      "operations": [
        {
          "id": 45712154,
          "type": "sale",
          "status": "awaiting redirect result",
          "date": "2019-10-09T07:13:36+0000",
          "processing_time": null,
          "request_id": "3bd75dc1977cc8c05b50855b-544f7f6af3d989dd42ef8e6ff02df56eef7c5f4e-521457",
          "sum": {
            "amount": 29100,
            "currency": "USD"
          },
          "code": "9999",
          "message": "Awaiting processing"
        }
      ]
    }

The signature is verified as follows:

  1. Remove the signature parameter and its value from the callback:
    {
      "request_id": "17cd0535c5ffecf5-335e5b5e",
      "transaction": {
        "id": 82452138542211,
        "date": "2019-10-09T07:13:36+0000",
        "type": "purchase"
      },
      "payment": {
        "id": "123456789",
        "method": "webmoney",
        "date": "2019-10-09T07:13:36+0000",
        "result_code": "9999",
        "result_message": "Awaiting processing",
        "status": "awaiting redirect result",
        "is_new_attempts_available": false,
        "attempts_timeout": 0,
        "cascading_with_redirect": false,
        "provider_id": 1234
      },
      "sum_real": {
        "amount": 29100,
        "currency": "USD"
      },
      "account": {
        "number": "79879496816"
      },
      "return_url": {
        "method": "GET",
        "body": {
          "shop": "1234567",
          "transaction": 45712154,
          "iframe": "true",
          "successUrl": "https://mysite.com/process/success",
          "failUrl": "https://mysite.com/process/failure",
          "target": "iframe"
        },
        "encrypted": []
      },
      "rrn": "",
      "general": {
        "project_id": 123,
        "payment_id": "457822332658",
        "signature": "NtDutuRiksyHeBhhUs+nQxQ1FcMSueoACb4vENju0APgHgeZfRfMj46289v1vD4hJ1a8Yhg=="
      },
      "description": "TEST_1543831735980",
      "sum_request": {
        "amount": 29100,
        "currency": "USD"
      },
      "operations": [
        {
          "id": 45712154,
          "type": "sale",
          "status": "awaiting redirect result",
          "date": "2019-10-09T07:13:36+0000",
          "processing_time": null,
          "request_id": "3bd75dc1977cc8c05b50855b-544f7f6af3d989dd42ef8e6ff02df56eef7c5f4e-521457",
          "sum": {
            "amount": 29100,
            "currency": "USD"
          },
          "code": "9999",
          "message": "Awaiting processing"
        }
      ]
    }
  2. Convert all the parameter string to UTF-8 according to the algorithm description:
    request_id:17cd0535c5ffecf5-335e5b5e
    transaction:id:82452138542211
    transaction:date:2019-10-09T07:13:36+0000
    transaction:type:purchase
    payment:id:123456789
    payment:method:webmoney
    payment:date:2019-10-09T07:13:36+0000
    payment:result_code:9999
    payment:result_message:Awaiting processing
    payment:status:awaiting redirect result
    payment:is_new_attempts_available:0
    payment:attempts_timeout:0
    payment:cascading_with_redirect:0
    payment:provider_id:1234
    sum_real:amount:29100
    sum_real:currency:USD
    account:number:79879496816
    return_url:method:GET
    return_url:body:shop:1234567
    return_url:body:transaction:45712154
    return_url:body:iframe:true
    return_url:body:successUrl:https://mysite.com/process/success
    return_url:body:failUrl:https://mysite.com/process/failure
    return_url:body:target:iframe
    rrn:
    general:project_id:123
    general:payment_id:457822332658
    description:TEST_1543831735980
    sum_request:amount:29100
    sum_request:currency:USD
    operations:0:id:45712154
    operations:0:type:sale
    operations:0:status:awaiting redirect result
    operations:0:date:2019-10-09T07:13:36+0000
    operations:0:processing_time:
    operations:0:request_id:3bd75dc1977cc8c05b50855b
    operations:0:sum:amount:29100
    operations:0:sum:currency:USD
    operations:0:code:9999
    operations:0:message:Awaiting processing
    
  3. Sort the strings in alphabetical order:
    account:number:79879496816
    description:TEST_1543831735980
    general:payment_id:457822332658
    general:project_id:123
    operations:0:code:9999
    operations:0:date:2019-10-09T07:13:36+0000
    operations:0:id:45712154
    operations:0:message:Awaiting processing
    operations:0:processing_time:
    operations:0:request_id:3bd75dc1977cc8c05b50855b
    operations:0:status:awaiting redirect result
    operations:0:sum:amount:29100
    operations:0:sum:currency:USD
    operations:0:type:sale
    payment:attempts_timeout:0
    payment:cascading_with_redirect:0
    payment:date:2019-10-09T07:13:36+0000
    payment:id:123456789
    payment:is_new_attempts_available:0
    payment:method:webmoney
    payment:provider_id:1234
    payment:result_code:9999
    payment:result_message:Awaiting processing
    payment:status:awaiting redirect result
    request_id:17cd0535c5ffecf5-335e5b5e
    return_url:body:failUrl:https://mysite.com/process/failure
    return_url:body:iframe:true
    return_url:body:shop:1234567
    return_url:body:successUrl:https://mysite.com/process/success
    return_url:body:target:iframe
    return_url:body:transaction:45712154
    return_url:method:GET
    rrn:
    sum_real:amount:29100
    sum_real:currency:USD
    sum_request:amount:29100
    sum_request:currency:USD
    transaction:date:2019-10-09T07:13:36+0000
    transaction:id:82452138542211
    transaction:type:purchase
    
  4. Join all the strings in a single string by using semicolon (;) as a delimiter:
    account:number:79879496816;description:TEST_1543831735980;general:payment_id:457822332658;general:project_id:123;operations:0:code:9999;operations:0:date:2019-10-09T07:13:36+0000;operations:0:id:45712154;operations:0:message:Awaiting processing;operations:0:processing_time:;operations:0:request_id:3bd75dc1977cc8c05b50855b-544f7f6af3d989dd42ef8e6ff02df56eef7c5f4e-521457;operations:0:status:awaiting redirect result;operations:0:sum:amount:29100;operations:0:sum:currency:USD;operations:0:type:sale;payment:attempts_timeout:0;payment:cascading_with_redirect:0;payment:date:2019-10-09T07:13:36+0000;payment:id:123456789;payment:is_new_attempts_available:0;payment:method:webmoney;payment:provider_id:1234;payment:result_code:9999;payment:result_message:Awaiting processing;payment:status:awaiting redirect result;request_id:17cd0535c5ffecf5-335e5b5e;return_url:body:failUrl:https://mysite.com/process/failure;return_url:body:iframe:true;return_url:body:shop:1234567;return_url:body:successUrl:https://mysite.com/process/success;return_url:body:target:iframe;return_url:body:transaction:45712154;return_url:method:GET;rrn:;sum_real:amount:29100;sum_real:currency:USD;sum_request:amount:29100;sum_request:currency:USD;transaction:date:2019-10-09T07:13:36+0000;transaction:id:82452138542211;transaction:type:purchase
  5. Calculate the HMAC code for the string by using the SHA-512 hash function and secret key, and then encode the HMAC code by using the Base64 scheme:
    rnv1OS3PJUKEJ5kw5wqoK0ftZGSd4Q6LX5A5NxK6d5alpND4sQTRFt7/9aFV+m3SRwNB8ba98GMsOY91yTVhEQ==
  6. Compare the generated signature and the one included in the callback.

    In our case, the signature differ which means that the callback is invalid and must be ignored.

Signature verification form