Баштоо

Өнөктөштүн атынан кызматтарды төлөө жана которуулар үчүн API (агенттик төлөмдөр).

Кантип иштейт

Чыгуучу төлөмдүн толук агымы — башынан ырастоого чейин:

1. Сиз кызматтардын тизмесин сурап, алардын милдеттүү талааларын (requiredFields) билесиз.
2. Алуучуну текшересиз — Finik анын атын кайтарат.
3. Уникалдуу transactionId менен өз эсебиңизден төлөм түзөсүз.
4. Finik каражатты эсептен алып, төлөмдү кызмат көрсөтүүчүгө жөнөтөт.
5. Финалдык статус (SUCCEEDED же FAILED) менен вебхук аласыз же статусту GET /v2/payments/{paymentId} аркылуу текшересиз.

Киришүү

Бул документация Finik Payments Gateway API сиздин колдонмоңузга интеграциялоого жардам берет, ошону менен сиз өз атыңыздан төлөмдөрдү жасай аласыз: мобилдик байланыш, интернет, коммуналдык жана башка кызматтарды төлөп, Finik колдонуучуларына которуулар жөнөтө аласыз — түздөн-түз корпоративдик эсебиңизден Кыргызстандын жүздөгөн кызмат көрсөтүүчүлөрүнө.

Интеграция төмөнкү кадамдардан турат:

1. RSA ачкыч жубун түзүңүз — жеке жана ачык. Алар сурамдарыңызды авторизациялоо үчүн керек.
2. API ачкычын алыңыз — ачык ачкычыңызды Finik өкүлдөрүнө жөнөтүп, API менен иштөө үчүн ApiKey алыңыз.
3. Сурамдарга кол коюуну ырастаңыз — ар бир сурам жеке ачкычыңыз менен кол коюлат.
4. Кызматтардын тизмесин алыңыз — жеткиликтүү кызматтардын каталогун жана алардын милдеттүү талааларын POST /v2/services аркылуу сураңыз.
5. Алуучуну текшериңиз — төлөмдөн мурун алуучунун бар экенин POST /v2/recipient аркылуу текшериңиз.
6. Төлөмдөрдү түзүңүз — кол коюлган сурамдарды POST /v2/payment дарегине жөнөтүп, статусту көзөмөлдөңүз.
7. Вебхукту иштетиңиз — төлөмдүн финалдык статусу тууралуу билдирүүлөрдү кабыл алып, алардын колун текшериңиз.

Тез баштоо

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());
  }
}

Даяр китепканалар