Quickstart

Figure: Example of PHP code for working with data signing (using the basic parameter set for card purchases)

*/
class Signer
{
    const ITEMS_DELIMITER = ';';
    const ALGORITHM = 'sha512';
    const IGNORED_KEYS = ['frame_mode'];

    /**
     * Secret key
     *
     * @var string
     */
    private $secretKey;

    /**
     * __construct
     *
     * @param string $secretKey
     */
    public function __construct(string $secretKey)
    {
        $this->secretKey = $secretKey;
    }

    /**
     * Check signature
     *
     * @param array $params
     * @param string $signature
     * @return boolean
     */
    public function check(array $params, string $signature): bool
    {
        return $this->sign($params) === $signature;
    }

    /**
     * Return signature
     *
     * @param array $params
     * @return string
     */
    public function sign(array $params): string
    {
        $stringToSign = implode(self::ITEMS_DELIMITER, $this->getParamsToSign($params, self::IGNORED_KEYS));
        return base64_encode(hash_hmac(self::ALGORITHM, $stringToSign, $this->secretKey, true));
    }

    /**
     * Get parameters to sign
     *
     * @param array $params
     * @param array $ignoreParamKeys
     * @param string $prefix
     * @param bool $sort
     * @return array
     */
    private function getParamsToSign(
        array $params,
        array $ignoreParamKeys = [],
        string $prefix = '',
        bool $sort = true
    ): array {
        $projectId = 42;
        $paymentId = '12345';
        $customerId = '123';
        $ip = '192.168.1.1';
        $paymentAmount = '1000';
        $paymentCurrency = 'USD';
        $cardPan = '*4567';
        $cardYear = '2029';
        $cardMonth = '09';
        $cardHolder = 'SONYA KOVALEVSKY';
        $cardCvv = '123';


        $paramsToSign = [
            'general'  => [
            'project_id' => $projectId,
            'payment_id' => $paymentId,
            ],
            'customer'  => [
            'id' => $customerId,
            'ip_address' => $ip,
            ],
            'payment'  => [
            'payment_amount' => $paymentAmount,
            'payment_currency' => $paymentCurrency,
            ],
            'card'  => [
            'pan' => $cardPan,
            'year' => $cardYear,
            'month' => $cardMonth,
            'card_holder' => $cardHolder,
            'cvv' => $cardCvv,
            ],
        ];

        foreach ($params as $key => $value) {
            if (in_array($key, $ignoreParamKeys, true)) {
                continue;
            }

            $paramKey = ($prefix ? $prefix . ':' : '') . $key;
            if (is_array($value)) {
                $subArray = $this->getParamsToSign($value, $ignoreParamKeys, $paramKey, false);
                $paramsToSign = array_merge($paramsToSign, $subArray);
            } else {
                if (is_bool($value)) {
                    $value = $value ? '1' : '0';
                } else {
                    $value = (string)$value;
                }

                $paramsToSign[$paramKey] = $paramKey . ':' . $value;
            }
        }

        if ($sort) {
            ksort($paramsToSign, SORT_NATURAL);
        }

        return $paramsToSign;
    }
}

Figure: Example of Go code for working with data signing (using the basic parameter set for card purchases)

package main

import (
	"crypto/hmac"
	"crypto/sha512"
	"encoding/base64"
	"sort"
)

const itemsDelimiter = ";"

var ignoredKeys = map[string]struct{}{"frame_mode": struct{}{}}

var secretKey string

func SetSecretKey(key string) {
	secretKey = key
}

func Check(params map[string]map[string]string, signature string) bool {
	return Sign(params) == signature
}

func Sign(params map[string]map[string]string) string {
	var stringToSign string

	paramsToSign := getParamsToSign(params, ignoredKeys, "", true)
	for _, value := range paramsToSign {
		for _, v := range value {
			stringToSign = stringToSign + itemsDelimiter + v
		}
	}

	mac := hmac.New(sha512.New, []byte(secretKey))
	mac.Write([]byte(stringToSign))

	return base64.StdEncoding.EncodeToString(mac.Sum(nil))
}

func getParamsToSign(params map[string]map[string]string, ignoreParamKeys map[string]struct{},
	prefix string, sorted bool) map[string]map[string]string {
	var paymentId, customerId, ip, amount, currency, cardPan, cardYear, cardMonth, cardHolder, cardCvv string

	paramsToSign := map[string]map[string]string{
		"general": {
			"project_id": projectId,
			"payment_id": paymentId,
		},
		"customer": {
			"id":         customerId,
			"ip_address": ip,
		},
		"payment": {
			"payment_amount":   amount,
			"payment_currency": currency,
		},
		"card": {
			"pan":         cardPan,
			"year":        cardYear,
			"month":       cardMonth,
			"card_holder": cardHolder,
			"cvv":         cardCvv,
		},
	}

	for key, value := range params {
		for k, v := range value {
			if _, ok := ignoreParamKeys[k]; ok {
				continue
			}

			paramKey := k
			if prefix != "" {
				paramKey = prefix + ":" + k
			}

			paramsToSign[key][paramKey] = paramKey + ":" + v
		}
	}

	if sorted == true {
		return sortParams(paramsToSign)
	}

	return paramsToSign
}

func sortParams(params map[string]map[string]string) map[string]map[string]string {
	var sortedParams map[string]map[string]string
	keys := make([]string, 0, len(params))

	for kp := range params {
		keys = append(keys, kp)
	}
	sort.Strings(keys)

	for _, ks := range keys {
		sortedParams[ks] = params[ks]
	}

	return sortedParams
}

Figure: Example of PHP code for sending requests and accepting responses

$headers        = [];
$headerCallback = function ($curl, $header_line) use (&$headers) {
    if (strpos($header_line, ":") === false) {
        return strlen($header_line);
    }
    list($key, $value) = explode(":", trim($header_line), 2);
    $headers[trim($key)] = trim($value);

    return strlen($header_line);
};

$absUrl = 'https://abs.url';
$curl = curl_init();

$opts[CURLOPT_URL]            = $absUrl;
$opts[CURLOPT_RETURNTRANSFER] = true;
$opts[CURLOPT_CONNECTTIMEOUT] = $this->connectTimeout;
$opts[CURLOPT_TIMEOUT]        = $this->timeout;
$opts[CURLOPT_HEADERFUNCTION] = $headerCallback;
curl_setopt_array($curl, $opts);
$rbody = curl_exec($curl);
$errno = curl_errno($curl);
if ($rbody === false) {
    $errno   = curl_errno($curl);
    $message = curl_error($curl);
    curl_close($curl);
    $this->handleCurlError($absUrl, $errno, $message);
}
$rcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo "http code = ".$rcode."\n";
echo "http response = ".$rbody."\n";

Figure: Example of Go code for sending requests and accepting responses

package main

import (
	"fmt"
	"net/http"
	"time"
)

type conf struct {
	connectTimeout, timeout time.Duration
	returnTransfer          bool
}

func main() {
	absUrl := "https://abs.url"
	var cf = conf{10 * time.Second, 20 * time.Second, true}

	req, err := http.NewRequest(http.MethodGet, absUrl, nil)
	if err != nil {
		fmt.Printf("client: could not create request: %s\n", err)

		return
	}

	client := http.Client{
		Timeout: cf.timeout,
	}

	res, err := client.Do(req)
	if err != nil {
		fmt.Printf("client: error making http request: %s\n", err)
		handleError(err)

		return
	}

	fmt.Printf("http code = %d\n", res.StatusCode)
	fmt.Printf("http response = %s\n", res.Body)
}

Figure: Example of data in a final callback

{
    "account": {
        "number": "424242******4243",
        "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654",
        "type": "visa",
        "card_holder": "SONYA KOVALEVSKY",
        "id": 45678,
        "expiry_month": "05",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "17008",
    },
    "payment": {
        "date": "2023-01-11T13:02:42+0000",
        "id": "Cosmoshop_purchase_2025-01-01_000001",
        "method": "card",
        "status": "success",
        "sum": {
            "amount": 8855,
            "currency": "USD"
        },
        "type": "purchase",
        "description": ""
    },
    "project_id": 42,
    "operation": {
        "id": 969000002636,
        "type": "sale",
        "status": "success",
        "date": "2023-01-11T13:02:42+0000",
        "created_date": "2023-01-11T13:01:45+0000",
        "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
        "sum_initial": {
            "amount": 8855,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 8855,
            "currency": "USD"
        },
        "provider": {
            "id": 408,
            "payment_id": "330157196",
            "date": "2023-01-11T13:02:32+0000",
            "auth_code": "",
            "endpoint_id": "612266625"
        },
        "code": "0",
        "message": "Success",
        "eci": "07"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}

Figure: Example of PHP code for receiving callbacks

require_once __DIR__ . 'signature.php';

//@todo net set to merchant project https://api.merchant.com/callback.php

//@todo set projectId
$projectId = null;
//@todo set paymentId 
$paymentId = '';
//@todo set secretKey
$secretKey = '';


$response = json_decode(file_get_contents('php://input'), true);

$rsignature = $response['signature'];

unset($response['signature']);


if ((new Signer($secretKey))->check($response, $rsignature)) {
    header('HTTP/1.1 200 OK');
    header('Status: 200 OK');
    echo "signature is correct\n";

    $projectId = $response['project_id'];
    $paymentId = $response['payment']['id'];

    //@todo save necessary info to merchant system
} else {
    header('Status: 400 Bad Request');
    header('HTTP/1.1 400 Bad Request');
    echo "signature is invalid\n";
}

Figure: Example of Go code for receiving callbacks

package main

import (
	"encoding/json"
	"io/ioutil"
	"log"
	"net/http"
)

//@todo net set to merchant project https://api.merchant.com/callback.go

//@todo set project
type project struct{}

type request struct {
	Signature string `json:"signature"`
}

var prj project

//@todo set secretKey
var secretKey string

//@todo set paymentId
var paymentId string

//@todo get request
var r *http.Request

func main() {
	body, err := ioutil.ReadAll(r.Body)
	if err != nil {
		log.Printf("Error reading body: %v", err)
	}

	var req request

	err = json.Unmarshal(body, &req)
	if err != nil {
		log.Printf("Error parsing request: %v", err)
	}

	var w http.ResponseWriter

	if checkSignature(req, secretKey, req.Signature) {
		w.WriteHeader(http.StatusOK)
		w.Write([]byte("signature is correct\n"))
	} else {
		w.WriteHeader(http.StatusBadRequest)
		w.Write([]byte("signature is invalid\n"))
	}
}

func checkSignature(req request, secretKey string, signature interface{}) bool {
}