Create a payout

Endpoint

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

Headers

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

Certificate Setup

To generate API certificate for payouts, 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

Wrap all POST data in JSON (in the same order) and sign:

$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 privateKeyPem = readFileSync('private.pem', 'utf8');
const passphrase = readFileSync('password.txt', 'utf8').trim();

const signer = createSign('SHA1');
signer.update(dataStr);
signer.end();

const sign = signer.sign({ key: privateKeyPem, passphrase }, 'base64');

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

data_bytes = json.dumps(data).encode('utf-8')

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.SHA1()
)
sign = base64.b64encode(signature).decode('utf-8')

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("SHA1withRSA");
sig.initSign(privateKey);
sig.update(dataBytes);

String sign = Base64.getEncoder().encodeToString(sig.sign());

import (
    "crypto"
    "crypto/rand"
    "crypto/rsa"
    "crypto/sha1"
    "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 := sha1.Sum(dataBytes)
sigBytes, _ := rsa.SignPKCS1v15(rand.Reader, priv, crypto.SHA1, hash[:])

sign := base64.StdEncoding.EncodeToString(sigBytes)

Pass the received $sign in the Sign header.

Request Parameters

* - Required fields
** - When creating a payout to an account in EUR currency - required

Name	Type	Description	Example
amount*	string	Amount	"1000.44"
number*	string	Account number, card
order_id*	string (128)	Your id must be unique
service*	string (100)	Service (Account, Acceptance Methods)	payment_card_rub
notification_endpoint_id	int	Notification id
notification_endpoint_url	string\|max:255	Link to send a callback after the statuses are finalized
extra**	array	Accepts optional parameters to increase conversion
extra["card_exp_year"]**	string (2)	Bank card expiration date (year)	"24"
extra["card_exp_month"]**	string (2)	Bank card expiration date (month)	"01"
extra["card_holder"]**	string (100)	Cardholder's Name	"CARDHOLDER NAME"
extra["card_country"]**	string (2) Alpha-2 ISO 3166-1	Bank card country	"UA"
extra["card_recipient_birth_date"]**	string	Cardholder's birthday	"1999-12-15"
customer_phone	string	Customer phone	"79001112233"
customer_email	string\|email	Customer email	"[email protected]"
customer_code	string	Customer code	"sberbank"
customer_first_name	string	Customer first name	"IVAN"
customer_last_name	string	Customer last name	"IVANOV"
customer_country	string	Customer country	"DEU"
project_url	string	Url to the project (for aggregators)	"https://example.com"

Extra Parameters Example

[
   "card_exp_year" => "24",
   "card_exp_month" => "01",
   "card_holder" => "CARDHOLDER NAME",
   "card_country" => "UA",
   "card_recipient_birth_date" => "1999-12-15",
]

Response

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

Important

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

Response Examples

Successful Response (HTTP CODE 200)

{
  "payment_status": "wait",
  "id": 100001524
}

Error Response (HTTP CODE 400)

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

Note: Possible values of payment_status, see the documentation "Payout status".

Important Notes

caution

If you received another status code (not 200) - do not cancel such payments on your side. Check the status of payouts with support in the chat.

caution

If you passed notification_endpoint_id, then you will receive a notification about the change in the payout status.

Example Implementation

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

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

    $privateKey = openssl_pkey_get_private(
        file_get_contents(__DIR__ . '/cert/payout/private.pem'),
        file_get_contents(__DIR__ . '/cert/payout/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);
}

$payout = requestPayout('v1/payout', '93d5df06-996c-48c3-9847-348d6b580b80', [
    'order_id' => (string)time(),
    'amount' => 500,
    'number' => '79005554455',
    'notification_endpoint_id' => 5,
    'service' => 'qiwi_rub',
]);

var_dump($payout);

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

async function requestPayout(method, account, data) {
  const dataStr = JSON.stringify(data);
  const privateKeyPem = readFileSync('cert/payout/private.pem', 'utf8');
  const passphrase = readFileSync('cert/payout/password.txt', 'utf8').trim();
  const signer = createSign('SHA1');
  signer.update(dataStr);
  signer.end();
  const sign = signer.sign({ key: privateKeyPem, passphrase }, '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 body = '';
      res.on('data', (chunk) => (body += chunk));
      res.on('end', () => resolve(JSON.parse(body)));
    });
    req.on('error', reject);
    req.write(dataStr);
    req.end();
  });
}

(async () => {
  const payout = await requestPayout(
    'v1/payout',
    '93d5df06-996c-48c3-9847-348d6b580b80',
    {
      order_id: String(Date.now()),
      amount: 500,
      number: '79005554455',
      notification_endpoint_id: 5,
      service: 'qiwi_rub',
    }
  );
  console.log(payout);
})();

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

def request_payout(method: str, account: str, data: dict):
    data_bytes = json.dumps(data).encode('utf-8')
    with open('cert/payout/password.txt', 'rb') as f:
        password = f.read().strip()
    with open('cert/payout/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.SHA1())
    sign = base64.b64encode(signature).decode('utf-8')
    headers = {
        'Content-Type': 'application/json',
        'Account': account,
        'Sign': sign,
        'User-Agent': 'AliKassa2.0 API',
    }
    resp = requests.post(f'https://api-merchant.alikassa.com/{method}', json=data, headers=headers, timeout=30)
    return resp.json()

payout = request_payout('v1/payout', '93d5df06-996c-48c3-9847-348d6b580b80', {
    'order_id':                str(int(__import__('time').time())),
    'amount':                  500,
    'number':                  '79005554455',
    'notification_endpoint_id':5,
    'service':                 'qiwi_rub',
})
print(payout)

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,
            "number",                  "79005554455",
            "notification_endpoint_id",5,
            "service",                 "qiwi_rub"
        );
        byte[] dataBytes = mapper.writeValueAsBytes(data);
        char[] pass = Files.readString(Paths.get("cert/payout/password.txt")).toCharArray();
        PEMParser parser = new PEMParser(Files.newBufferedReader(Paths.get("cert/payout/private.pem")));
        PEMEncryptedKeyPair ckp = (PEMEncryptedKeyPair) parser.readObject();
        var kp = new JcaPEMKeyConverter().getKeyPair(
            ckp.decryptKeyPair(new JcePEMDecryptorProviderBuilder().build(pass))
        );
        Signature sig = Signature.getInstance("SHA1withRSA");
        sig.initSign(kp.getPrivate());
        sig.update(dataBytes);
        String sign = Base64.getEncoder().encodeToString(sig.sign());
        HttpRequest request = HttpRequest.newBuilder()
            .uri(java.net.URI.create("https://api-merchant.alikassa.com/v1/payout"))
            .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(dataBytes, StandardCharsets.UTF_8)))
            .build();
        var client = HttpClient.newHttpClient();
        var response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(mapper.readValue(response.body(), Object.class));
    }
}

package main

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

func signData(data interface{}) string {
    dataBytes, _ := json.Marshal(data)
    pemBytes, _ := ioutil.ReadFile("cert/payout/private.pem")
    passBytes, _ := ioutil.ReadFile("cert/payout/password.txt")
    block, _ := pem.Decode(pemBytes)
    der, _ := x509.DecryptPEMBlock(block, passBytes)
    priv, _ := x509.ParsePKCS1PrivateKey(der)
    hash := sha1.Sum(dataBytes)
    sigBytes, _ := rsa.SignPKCS1v15(rand.Reader, priv, crypto.SHA1, hash[:])
    return base64.StdEncoding.EncodeToString(sigBytes)
}

func requestPayout(method, account string, data map[string]interface{}) (map[string]interface{}, error) {
    sign := signData(data)
    body, _ := json.Marshal(data)
    req, _ := http.NewRequest("POST", "https://api-merchant.alikassa.com/"+method, bytes.NewReader(body))
    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() {
    payout, _ := requestPayout("v1/payout", "93d5df06-996c-48c3-9847-348d6b580b80", map[string]interface{}{
        "order_id":                 time.Now().Unix(),
        "amount":                   500,
        "number":                   "79005554455",
        "notification_endpoint_id": 5,
        "service":                  "qiwi_rub",
    })
    fmt.Println(payout)
}

Endpoint​

Headers​

Certificate Setup​

Signature Generation​

Request Parameters​

Extra Parameters Example​

Response​

Response Examples​

Successful Response (HTTP CODE 200)​

Error Response (HTTP CODE 400)​

Important Notes​

Example Implementation​