Начало работы

API для оплаты услуг и переводов от имени партнёра (агентские платежи).

Как это работает

Полный поток исходящего платежа от начала до подтверждения:

1. Вы запрашиваете список услуг и узнаёте обязательные поля (requiredFields).
2. Проверяете получателя — Finik возвращает его имя.
3. Создаёте платёж со своего счёта с уникальным transactionId.
4. Finik списывает средства и проводит платёж в сторону поставщика услуг.
5. Вы получаете webhook с финальным статусом (SUCCEEDED или FAILED) или проверяете статус через GET /v2/payments/{paymentId}.

Введение

Эта документация поможет вам интегрировать Finik Payments Gateway API в ваше приложение, чтобы вы могли совершать платежи от своего имени: оплачивать мобильную связь, интернет, коммунальные и другие услуги, а также отправлять переводы пользователям Finik — напрямую со своего корпоративного счёта в сторону сотен поставщиков услуг Кыргызстана.

Интеграция состоит из следующих шагов:

1. Сгенерируйте пару ключей RSA — приватный и публичный. Они нужны для авторизации ваших запросов.
2. Получите API-ключ — передайте публичный ключ представителям Finik и получите ApiKey для работы с API.
3. Настройте подпись запросов — каждый запрос подписывается вашим приватным ключом.
4. Получите список услуг — запросите каталог доступных услуг и их обязательные поля через POST /v2/services.
5. Проверьте получателя — перед платежом убедитесь, что получатель существует, через POST /v2/recipient.
6. Создавайте платежи — отправляйте подписанные запросы на POST /v2/payment и отслеживайте статус.
7. Обрабатывайте webhook — принимайте уведомления о финальном статусе платежа и проверяйте их подпись.

Быстрый старт

1. Получите ApiKey у представителей Finik.
2. Сгенерируйте пару RSA-ключей:

openssl genrsa -out finik_private.pem 2048
openssl rsa -in finik_private.pem -pubout > finik_public.pem

3. Отправьте публичный ключ (finik_public.pem) представителям Finik. Приватный ключ храните в секрете — тот, кто им завладеет, сможет отправлять запросы от вашего имени.
4. Подключите библиотеку подписи:
   • Node.js — @mancho.devs/authorizer (NPM)
   • Python — mancho-devs/python-authorizer
   • Другие языки — см. алгоритм подписи
5. Сделайте первый запрос в бета-среде — начните с POST /v2/services.

Окружения

Аутентификация

Каждый запрос подписывается вашим приватным ключом. Подпись передаётся в HTTP-заголовках:

Алгоритм формирования строки для подписи

data  = lowercase(HTTP-метод) + "\n"          // "post" или "get"
data += URI-путь + "\n"                        // например "/v2/payment"
data += заголовки + "\n"                       // см. правила ниже
data += query-параметры + "\n"                 // если query-параметров нет — "\n" НЕ добавляется
data += JSON тела запроса                      // ключи отсортированы, см. ниже

Правила для заголовков:

1. Взять Host и все заголовки, начинающиеся с x-api-*.
2. Отсортировать по имени заголовка в алфавитном порядке.
3. Склеить через & в формате имя:значение (имена в нижнем регистре):

host:api.paymentsgateway.averspay.kg&x-api-key:ВАШ_КЛЮЧ&x-api-timestamp:1719900000000

Правила для query-параметров:

1. Отсортировать по имени параметра в алфавитном порядке.
2. Склеить через & в формате URiEncode(имя)=URiEncode(значение).
3. Если у параметра нет значения (например ?acl) — использовать пустую строку: acl=.

Правила для тела запроса:

Тело сериализуется в JSON с ключами, отсортированными в алфавитном порядке.

Подпись

Собранная строка data подписывается алгоритмом SHA256withRSA приватным ключом, результат кодируется в Base64 и передаётся в заголовке signature.

Пример на Java:

public String sign(String payload, String privatePath) {
  try {
    Signature signature = Signature.getInstance("SHA256withRSA");
    String privateKeyFile = new String(Files.readAllBytes(Paths.get(privatePath)));
    RSAKey rsaKey = (RSAKey) JWK.parseFromPEMEncodedObjects(privateKeyFile);
    PrivateKey privateKey = rsaKey.toPrivateKey();
    signature.initSign(privateKey);
    signature.update(payload.getBytes(StandardCharsets.UTF_8));
    return Base64.encodeBase64String(signature.sign());
  } catch (Exception e) {
    throw new AppException(e.getMessage());
  }
}

Готовые библиотеки