Payment solution RU 4

Payment Methods Overview

Creating payments via our form (card details)
Creating payments via H2H (getting card details via API)
Creating payments via H2H (getting phone number via API)
Creating payments via H2H (SberPay)
Creating payments via form (Payment account)
Creating payments via H2H (Payment account)
Creating payouts via "SBP" method
Creating payouts via "Payment account" method

Certificate Setup

To generate API certificate for payment, visit: https://merchant.alikassa.com/cabinet/form/setting-api-certs

Save the archive and unpack to get:

password.txt
private.pem
public.pem

We keep only public.pem for signature verification.

Signature Generation

$data = json_encode($data);

$privateKey = openssl_pkey_get_private(
    file_get_contents('private.pem'),
    file_get_contents('password.txt')
);

if ($privateKey === false) {
    throw new \Exception('Error cert.');
}

openssl_sign($data, $sign, $privateKey);
$sign = base64_encode($sign);

import { readFileSync } from 'fs';
import { createSign } from 'crypto';

const dataStr = JSON.stringify(data);
const key = readFileSync('private.pem', 'utf8');
const passphrase = readFileSync('password.txt', 'utf8').trim();
const signer = createSign('SHA256');
signer.update(dataStr);
signer.end();
const sign = signer.sign({ key, passphrase }, 'base64');

import json, base64
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

data_bytes = json.dumps(data).encode()
with open('password.txt','rb') as f:
    password = f.read().strip()
with open('private.pem','rb') as f:
    private_key = serialization.load_pem_private_key(f.read(), password=password)
signature = private_key.sign(data_bytes, padding.PKCS1v15(), hashes.SHA256())
sign = base64.b64encode(signature).decode()

import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.Signature;
import java.util.Base64;
import org.bouncycastle.openssl.PEMEncryptedKeyPair;
import org.bouncycastle.openssl.PEMParser;
import org.bouncycastle.openssl.jcajce.JcePEMDecryptorProviderBuilder;
import org.bouncycastle.openssl.jcajce.JcaPEMKeyConverter;

byte[] dataBytes = new com.fasterxml.jackson.databind.ObjectMapper().writeValueAsBytes(data);
char[] pass = Files.readString(Paths.get("password.txt")).toCharArray();
PEMParser parser = new PEMParser(Files.newBufferedReader(Paths.get("private.pem")));
PEMEncryptedKeyPair ckp = (PEMEncryptedKeyPair) parser.readObject();
var privateKey = new JcaPEMKeyConverter()
    .getKeyPair(ckp.decryptKeyPair(new JcePEMDecryptorProviderBuilder().build(pass)))
    .getPrivate();
Signature sig = Signature.getInstance("SHA256withRSA");
sig.initSign(privateKey);
sig.update(dataBytes);
String sign = Base64.getEncoder().encodeToString(sig.sign());

import (
    "crypto"
    "crypto/rand"
    "crypto/rsa"
    "crypto/sha256"
    "crypto/x509"
    "encoding/base64"
    "encoding/json"
    "encoding/pem"
    "io/ioutil"
)

dataBytes, _ := json.Marshal(data)
pemBytes, _ := ioutil.ReadFile("private.pem")
passBytes, _ := ioutil.ReadFile("password.txt")
block, _ := pem.Decode(pemBytes)
der, _ := x509.DecryptPEMBlock(block, passBytes)
priv, _ := x509.ParsePKCS1PrivateKey(der)
hash := sha256.Sum256(dataBytes)
sigBytes, _ := rsa.SignPKCS1v15(rand.Reader, priv, crypto.SHA256, hash[:])
sign := base64.StdEncoding.EncodeToString(sigBytes)

Creating payments via our form

Endpoint

POSThttps://api-merchant.alikassa.com/v1/payment📋

Headers

Header	Value
Content-Type	application/json
Account	Your account uuid, you can find in Accounts
Sign	Request signature

Parameters

* - Required fields

Name	Type	Description
amount*	decimal (11.2)	Amount
order_id*	string (128)	Your id must be unique
service*	string (100)	payment_card_number_rub_hpp
customer_ip*	ip	Payer's IP address
customer_user_id*	string (100)	Customer ID in your system
success_redirect_id	int	Id of redirect upon successful payment
fail_redirect_id	int	Id of redirect in case of unsuccessful payment
notification_endpoint_id	int	Notification id
success_redirect_url	string\|max:255	Link to redirect after successful payment
fail_redirect_url	string\|max:255	Link to redirect after unsuccessful payment
notification_endpoint_url	string\|max:255	Link to send a callback after the statuses are finalized

Response

Name	Description
url	Link to payment
payment_status	Payment status wait — in the process of payment
id	AliKassa payment id
uuid	AliKassa payment uuid
success_redirect_url	Link to your page for client redirect after successful payment

Important

When creating, always wait, check the payment status via the API or wait for a notification!

Success Response Example (HTTP CODE 200)

{
  "url": "https://pay-merchant.alikassa.com/bd291fe1-5c19-4113-ae62-a2d3c4d01d20",
  "payment_status": "wait",
  "id": 108465371,
  "uuid": "bd291fe1-5c19-4113-ae62-a2d3c4d01d20",
  "success_redirect_url": null
}

After receiving the url, redirect the client to the link.

Creating payments via H2H (getting card details via API)

Parameters

* - Required fields

Name	Type	Description
amount*	decimal (11.2)	Amount
order_id*	string (128)	Your id must be unique
service*	string (100)	payment_card_number_card
customer_ip*	ip	Payer's IP address
customer_user_id*	string (100)	Customer ID in your system
customer_code*	string (100)	Full list of banks. Example: "100000000111"
notification_endpoint_id	int	Notification id
notification_endpoint_url	string\|max:255	Link to send a callback after the statuses are finalized

Response

Name	Description
url	null
payment_status	Payment status wait — in the process of payment
id	AliKassa payment id
uuid	AliKassa payment uuid
success_redirect_url	Link to your page for client redirect after successful payment
cardNumber	Card details in format "1111111111110019"
cardHolderName	Cardholder data in format "Name Patronymic L."

Success Response Example (HTTP CODE 200)

{
  "url": null,
  "payment_status": "wait",
  "id": 108465371,
  "uuid": "bd291fe1-5c19-4113-ae62-a2d3c4d01d20",
  "success_redirect_url": null,
  "cardNumber": "1111111111110019",
  "cardHolderName": "Name Patronymic L."
}

After receiving the details, show them on your form.

Creating payments via H2H (getting phone number via API)

Parameters

* - Required fields

Name	Type	Description
amount*	decimal (11.2)	Amount
order_id*	string (128)	Your id must be unique
service*	string (100)	payment_card_sbp_rub_card
customer_ip*	ip	Payer's IP address
customer_user_id*	string (100)	Customer ID in your system
notification_endpoint_id	int	Notification id
notification_endpoint_url	string\|max:255	Link to send a callback after the statuses are finalized

Response

Name	Description
url	null
payment_status	Payment status wait — in the process of payment
id	AliKassa payment id
uuid	AliKassa payment uuid
success_redirect_url	Link to your page for client redirect after successful payment
cardNumber	Phone number in format "79031112233"
cardHolderName	Cardholder data in format "Name Patronymic L."

Success Response Example (HTTP CODE 200)

{
  "url": null,
  "payment_status": "wait",
  "id": 108465371,
  "uuid": "5e628a85-b94a-3678-a63b-a9511e80e60b",
  "success_redirect_url": null,
  "cardNumber": "79031112233",
  "cardHolderName": "Name Patronymic L."
}

Creating payments via H2H (SberPay)

Parameters

* - Required fields

Name	Type	Description
amount*	decimal (11.2)	Amount
order_id*	string (128)	Your id must be unique
service*	string (100)	payment_card_sberpay_rub_card
customer_ip*	ip	Payer's IP address
customer_user_id*	string (100)	Customer ID in your system
notification_endpoint_id	int	Notification id
notification_endpoint_url	string\|max:255	Link to send a callback after the statuses are finalized

Response

Name	Description
url	Client redirect link, https://p2p.cloudpaypro.com/5e628a85-b94a-3678-a63b-a9511e80e60b
payment_status	Payment status wait — in the process of payment
id	AliKassa payment id
uuid	AliKassa payment uuid
success_redirect_url	Link to your page for client redirect after successful payment
cardNumber	Phone number in format "79031112233"
cardHolderName	Cardholder data in format "Name Patronymic L."

Success Response Example (HTTP CODE 200)

{
  "url": "https://p2p.cloudpaypro.com/5e628a85-b94a-3678-a63b-a9511e80e60b",
  "payment_status": "wait",
  "id": 108465371,
  "uuid": "5e628a85-b94a-3678-a63b-a9511e80e60b",
  "success_redirect_url": null,
  "cardNumber": "79031112233",
  "cardHolderName": "Name Patronymic L."
}

Creating payments via form (Payment account)

Parameters

* - Required fields

Name	Type	Description
amount*	decimal (11.2)	Amount
order_id*	string (128)	Your id must be unique
service*	string (100)	virtual_account_rub_hpp
customer_ip*	ip	Payer's IP address
customer_user_id*	string (100)	Customer ID in your system
notification_endpoint_id	int	Notification id
notification_endpoint_url	string\|max:255	Link to send a callback after the statuses are finalized

Response

Name	Description
url	Client redirect link
payment_status	Payment status wait — in the process of payment
id	AliKassa payment id
uuid	AliKassa payment uuid
success_redirect_url	Link to your page for client redirect after successful payment
cardNumber	Payment account
cardHolderName	Cardholder data in format "Name Patronymic L."

Creating payments via H2H (Payment account)

Parameters

* - Required fields

Name	Type	Description
amount*	decimal (11.2)	Amount
order_id*	string (128)	Your id must be unique
service*	string (100)	virtual_account_rub_card
customer_ip*	ip	Payer's IP address
customer_user_id*	string (100)	Customer ID in your system
notification_endpoint_id	int	Notification id
notification_endpoint_url	string\|max:255	Link to send a callback after the statuses are finalized

Response

Name	Description
payment_status	Payment status wait — in the process of payment
id	AliKassa payment id
uuid	AliKassa payment uuid
success_redirect_url	Link to your page for client redirect after successful payment
cardNumber	Payment account
cardHolderName	Cardholder data in format "Name Patronymic L."

Creating payouts via SBP method

Endpoint

POSThttps://api-merchant.alikassa.com/v1/payout📋

Parameters

* - Required fields

Name	Type	Description	Example
amount*	decimal (11.2)	Amount	"3000.00"
order_id*	string (128)	Your id must be unique	"1234"
service*	string (100)	payment_card_sbp_rub	"payment_card_sbp_rub"
number*	phone	Client phone	"79031112233"
customer_code*	string (100)	Full list of banks	"100000000111"
notification_endpoint_id	int	Notification id	100
notification_endpoint_url	string\|max:255	Link to send a callback after the statuses are finalized	"https://google.com"

Response

Name	Description
id	AliKassa payment id
payment_status	Payment status wait — in the process of payment

Creating payouts via Payment account method

Parameters

* - Required fields

Name	Type	Description	Example
amount*	decimal (11.2)	Amount	"3000.00"
order_id*	string (128)	Your id must be unique	"1234"
service*	string (100)	virtual_account_rub	"virtual_account_rub"
number*	string (100)	Payment account	"40817120273018899310"
customer_code*	string (100)	Full list of banks	"100000000111"
bik_bank*	string (100)	Recipient bank BIC	"041351902"
notification_endpoint_id	int	Notification id	100
notification_endpoint_url	string\|max:255	Link to send a callback after the statuses are finalized	"https://google.com"

Response

Name	Description
id	AliKassa payment id
payment_status	Payment status wait — in the process of payment

Error Response (HTTP CODE 400)

{
  "message": "The given data was invalid.",
  "errors": {
    // ...
  }
}

Important Notes

Possible values of payment_status, see the documentation "Payment status"
If you passed notification_endpoint_id or notification_endpoint_url, you will receive a notification about the payment status change

Example Implementation

Unpack the downloaded archive into the folder "path to script/cert/payment/"

function requestPayment(string $method, string $account, array $data)
{
    $data = json_encode($data);

    $privateKey = openssl_pkey_get_private(
        file_get_contents(__DIR__ . '/cert/payment/private.pem'),
        file_get_contents(__DIR__ . '/cert/payment/password.txt')
    );

    if ($privateKey === false) {
        throw new \Exception('Error cert.');
    }

    openssl_sign($data, $sign, $privateKey);
    $sign = base64_encode($sign);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://api-merchant.alikassa.com/' . $method);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Account: ' . $account,
        'Sign: ' . $sign,
    ]);
    curl_setopt($ch, CURLOPT_HEADER, 0);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($ch, CURLOPT_USERAGENT, 'AliKassa2.0 API');
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);

    $response = curl_exec($ch);

    return json_decode($response, true);
}

$payment = requestPayment('v1/payment', '93d5df06-996c-48c3-9847-348d6b580b80', [
    'order_id' => (string)time(),
    'amount' => 500,
    'customer_browser_user_agent' => 'Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:84.0) Gecko/20100101 Firefox/84.0',
    'customer_ip' => '18.191.80.10',
    'success_redirect_id' => 1,
    'fail_redirect_id' => 1,
    'notification_endpoint_id' => 5,
    'service' => 'payment_card_rub_hpp',
]);

var_dump($payment);

import { readFileSync } from 'fs';
import { createSign } from 'crypto';
import https from 'https';

async function requestPayment(method, account, data) {
  const body = JSON.stringify(data);
  const key = readFileSync('cert/payment/private.pem', 'utf8');
  const pass = readFileSync('cert/payment/password.txt', 'utf8').trim();
  const signer = createSign('SHA256');
  signer.update(body);
  signer.end();
  const sign = signer.sign({ key, passphrase: pass }, 'base64');
  const options = {
    hostname: 'api-merchant.alikassa.com',
    path: `/${method}`,
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Account: account,
      Sign: sign,
      'User-Agent': 'AliKassa2.0 API',
    },
    timeout: 30000,
  };
  return new Promise((resolve, reject) => {
    const req = https.request(options, (res) => {
      let data = '';
      res.on('data', (chunk) => (data += chunk));
      res.on('end', () => resolve(JSON.parse(data)));
    });
    req.on('error', reject);
    req.write(body);
    req.end();
  });
}

(async () => {
  const payment = await requestPayment(
    'v1/payment',
    '93d5df06-996c-48c3-9847-348d6b580b80',
    {
      order_id: String(Date.now()),
      amount: 500,
      customer_browser_user_agent:
        'Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:84.0) Gecko/20100101 Firefox/84.0',
      customer_ip: '18.191.80.10',
      success_redirect_id: 1,
      fail_redirect_id: 1,
      notification_endpoint_id: 5,
      service: 'payment_card_rub_hpp',
    }
  );
  console.log(payment);
})();

import json
import base64
import requests
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

def request_payment(method: str, account: str, data: dict):
    payload = json.dumps(data).encode()
    password = open('cert/payment/password.txt','rb').read().strip()
    private_key = serialization.load_pem_private_key(
        open('cert/payment/private.pem','rb').read(),
        password=password
    )
    signature = private_key.sign(payload, padding.PKCS1v15(), hashes.SHA256())
    sign = base64.b64encode(signature).decode()
    headers = {
        'Content-Type': 'application/json',
        'Account': account,
        'Sign': sign,
        'User-Agent': 'AliKassa2.0 API'
    }
    resp = requests.post(f'https://api-merchant.alikassa.com/{method}', data=payload, headers=headers, timeout=30)
    return resp.json()

payment = request_payment('v1/payment', '93d5df06-996c-48c3-9847-348d6b580b80', {
    'order_id': str(int(__import__('time').time())),
    'amount': 500,
    'customer_browser_user_agent': 'Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:84.0) Gecko/20100101 Firefox/84.0',
    'customer_ip': '18.191.80.10',
    'success_redirect_id': 1,
    'fail_redirect_id': 1,
    'notification_endpoint_id': 5,
    'service': 'payment_card_rub_hpp',
})
print(payment)

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.Signature;
import java.util.Base64;
import java.util.Map;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.bouncycastle.openssl.PEMEncryptedKeyPair;
import org.bouncycastle.openssl.PEMParser;
import org.bouncycastle.openssl.jcajce.JcePEMDecryptorProviderBuilder;
import org.bouncycastle.openssl.jcajce.JcaPEMKeyConverter;

public class Example {
    public static void main(String[] args) throws Exception {
        ObjectMapper mapper = new ObjectMapper();
        Map<String,Object> data = Map.of(
            "order_id", String.valueOf(System.currentTimeMillis()),
            "amount", 500,
            "customer_browser_user_agent", "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:84.0) Gecko/20100101 Firefox/84.0",
            "customer_ip", "18.191.80.10",
            "success_redirect_id", 1,
            "fail_redirect_id", 1,
            "notification_endpoint_id", 5,
            "service", "payment_card_rub_hpp"
        );
        byte[] jsonBytes = mapper.writeValueAsBytes(data);
        char[] pass = Files.readString(Paths.get("cert/payment/password.txt")).toCharArray();
        PEMParser parser = new PEMParser(Files.newBufferedReader(Paths.get("cert/payment/private.pem")));
        PEMEncryptedKeyPair ckp = (PEMEncryptedKeyPair) parser.readObject();
        var privateKey = new JcaPEMKeyConverter()
            .getKeyPair(ckp.decryptKeyPair(new JcePEMDecryptorProviderBuilder().build(pass)))
            .getPrivate();
        Signature sig = Signature.getInstance("SHA256withRSA");
        sig.initSign(privateKey);
        sig.update(jsonBytes);
        String sign = Base64.getEncoder().encodeToString(sig.sign());
        HttpRequest req = HttpRequest.newBuilder()
            .uri(java.net.URI.create("https://api-merchant.alikassa.com/v1/payment"))
            .header("Content-Type","application/json")
            .header("Account","93d5df06-996c-48c3-9847-348d6b580b80")
            .header("Sign",sign)
            .header("User-Agent","AliKassa2.0 API")
            .POST(HttpRequest.BodyPublishers.ofString(new String(jsonBytes, StandardCharsets.UTF_8)))
            .build();
        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(mapper.readValue(res.body(), Map.class));
    }
}

package main

import (
    "bytes"
    "crypto"
    "crypto/rand"
    "crypto/rsa"
    "crypto/sha256"
    "crypto/x509"
    "encoding/base64"
    "encoding/json"
    "encoding/pem"
    "io/ioutil"
    "net/http"
    "time"
    "fmt"
)

func signData(data []byte) string {
    pemBytes, _ := ioutil.ReadFile("cert/payment/private.pem")
    passBytes, _ := ioutil.ReadFile("cert/payment/password.txt")
    block, _ := pem.Decode(pemBytes)
    der, _ := x509.DecryptPEMBlock(block, passBytes)
    priv, _ := x509.ParsePKCS1PrivateKey(der)
    hash := sha256.Sum256(data)
    sigBytes, _ := rsa.SignPKCS1v15(rand.Reader, priv, crypto.SHA256, hash[:])
    return base64.StdEncoding.EncodeToString(sigBytes)
}

func requestPayment(method, account string, data interface{}) (map[string]interface{}, error) {
    jsonBytes, _ := json.Marshal(data)
    sign := signData(jsonBytes)
    req, _ := http.NewRequest("POST", "https://api-merchant.alikassa.com/"+method, bytes.NewReader(jsonBytes))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Account", account)
    req.Header.Set("Sign", sign)
    req.Header.Set("User-Agent", "AliKassa2.0 API")
    client := &http.Client{Timeout: 30 * time.Second}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    return result, nil
}

func main() {
    payment, _ := requestPayment("v1/payment", "93d5df06-996c-48c3-9847-348d6b580b80", map[string]interface{}{
        "order_id":                   time.Now().Unix(),
        "amount":                     500,
        "customer_browser_user_agent":"Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:84.0) Gecko/20100101 Firefox/84.0",
        "customer_ip":                "18.191.80.10",
        "success_redirect_id":        1,
        "fail_redirect_id":           1,
        "notification_endpoint_id":   5,
        "service":                    "payment_card_rub_hpp",
    })
    fmt.Println(payment)
}

Payment Methods Overview​

Certificate Setup​

Signature Generation​

Creating payments via our form​

Endpoint​

Headers​

Parameters​

Response​

Success Response Example (HTTP CODE 200)​

Creating payments via H2H (getting card details via API)​

Parameters​

Response​

Success Response Example (HTTP CODE 200)​

Creating payments via H2H (getting phone number via API)​

Parameters​

Response​

Success Response Example (HTTP CODE 200)​

Creating payments via H2H (SberPay)​

Parameters​

Response​

Success Response Example (HTTP CODE 200)​

Creating payments via form (Payment account)​

Parameters​

Response​

Creating payments via H2H (Payment account)​

Parameters​

Response​

Creating payouts via SBP method​

Endpoint​

Parameters​

Response​

Creating payouts via Payment account method​

Parameters​

Response​

Error Response (HTTP CODE 400)​

Example Implementation​

Payment Methods Overview

Certificate Setup

Signature Generation

Creating payments via our form

Endpoint

Headers

Parameters

Response

Success Response Example (HTTP CODE 200)

Creating payments via H2H (getting card details via API)

Parameters

Response

Success Response Example (HTTP CODE 200)

Creating payments via H2H (getting phone number via API)

Parameters

Response

Success Response Example (HTTP CODE 200)

Creating payments via H2H (SberPay)

Parameters

Response

Success Response Example (HTTP CODE 200)

Creating payments via form (Payment account)

Parameters

Response

Creating payments via H2H (Payment account)

Parameters

Response

Creating payouts via SBP method

Endpoint

Parameters

Response

Creating payouts via Payment account method

Parameters

Response

Error Response (HTTP CODE 400)

Example Implementation