6 бизнес-инструментов от Kassa24 для успешного предпринимателя

Инструкция по интеграции собственной платежной формы и системы «Онлайн-платежи» от Kassa24 Business

Инструкция по созданию криптограммы

Получить публичный ключ для шифрования. При кэшировании ключа хранить его не более суток (кэшировать не больше, чем на сутки).

https://ecommerce.pult24.kz/payment/getcert/pem - публичный ключ в PEM-формате;

https://ecommerce.pult24.kz/payment/getcert - публичный ключ в JWK-формате.

Сформировать JSON-строку согласно структуре:

для оплаты:

1
2
3
4
5
6
7
8
9
{
  "cardholder": "iv viv",
  "month": "10",
  "pan": "5356502005228360",
  "validity": "10/21",
  "year": "2021",
  "cvv": "111",
  "ip": "192.168.0.1"
}

для выплат:

1
2
3
{
  "pan": "5356502005228360"
}

Сформированная строка должна быть зашифрована с помощью алгоритма: RSA/NONE/OAEPWITHSHA-256ANDMGF1PADDING. Хэш-функция Sha256 должна использоваться как для OAEP, так и для MGF1.
Полученная строка представляет собой байтовый массив, содержащий зашифрованные данные.
Данную строку нужно энкодировать в BASE64 (Std.Encoding).
Криптограмму необходимо поместить в запрос на создание транзакции (см. пример создания транзакции с криптограммой). Криптограмма не должна сохраняться нигде в системе мерчанта.
При успешном создании транзакции вернется URL, куда необходимо перенаправить пользователя для прохождения процедуры 3DSecure, и ожидать поступления коллбэка со статусом транзакции.

Пример создания транзакции на оплату с криптограммой

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "merchantId":"your_login",
  "amount":12500,
  "returnUrl":"https://yoursite.kz/payment/complete",
  "description":"Test payment for [email protected]",
  "callbackUrl":"hhttps://yoursite.kz/payment/callback",
  "acquiringId":15,
  "customerData":{
    "phone":"77472392990",
    “email”:[email protected],
    "cardData":"wnUx+rkFVhpaTvapu2etbfA7RKf6Hufl31p0517/jsFAS3uilcOqTy8Ir3hav9QoJSyhtG/syw8mwOIU/QNyzdL8uCDhRSJbLkT8f8KpKqrhxrT6e02zMiLrfTG8AdJGOiA9hBIVrRLyz+4URy0pgkFf03azfAedCBRwEHt7hr7zte3W69JNVWYBnSDyailC3nB9zaEEuqsS9UxlbwhMcRr+7e+O+bn1U2El3XzM9nEx/qoU2hRCHusW1s+rWDn/Ttn5eZNCwlyzOXXkGqPQZicpk2mvqE68VvXvRjVaGeIj+cp/Y74nT0jt8H355ST4Zc5A41ArSbyLRoxJUss2w/BPDovROa7chHPH3lv7Isg0UCVNzZ/nDPA+GJ/GrIw1wd12gLv9Ghg8fS2CIAXzuZV9yc+tAmBU4HWnnXKbgejQOHV42DNWGcyOkkuv6Tw7WGtAcAf8DHOOxDO74O7ffgddDypC2gFsjm1Uf+u34TsmZMoUBv/L04mqrkn2qAHfsW96mLuMhPt1fIze5fCkpFVYE5xOrI9d+4hORPs3DaVL0v/YMH41p9/9R+5VvkitZUxxpUC+UFJudnrRP2vc1KbEWcVZVcE78wu8wRo4BCUVUwVpnhHRLMG27VujxGyuVLtPxJsoT38oC7TuZeUbZbd0C9m6lZTvTJeNjYwXFNM="
  },
  "demo":true
}

Флаг demo на продакшене должен быть FALSE или отсутствовать.

В ответ на создание платежа будет возвращен номер выплаты/платежа в системе «Онлайн-платежи» и URL для перенаправления:

1
2
3
4
{
  "url":"ecommerce.pult24.kz/payment/view?id=9876543210",
  "id":"9876543210"
}

После этого приходит ответ (Callback). Пример присылаемого на callbackUrl запроса:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "orderId":"123",
  "id":"123",
  "account":"[email protected]",
  "amount":10000,
  "commission":100,
  "commissionIncluded":true,
  "attempt":1,
  "returnUrl":"https://my.site.kz/",
  "callbackUrl":"https://my.site.kz/",
  "date":"2006-01-02T15:04:05",
  "dateOut":"2006-01-02T15:04:05",
  "status":1,
  "errCode":0,
  "errMessage":"Ошибок нет",
  "metadata":{
      "session":"3135c7fe-272f-46d0-a5f8-1ab2a59ac17c"
  }
}

Пример создания транзакции на выплаты с криптограммой

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "merchantId":"your_login",
  "amount":12500,
  "returnUrl":"https://yoursite.kz/payment/complete",
  "description":"Test payment for [email protected]",
  "callbackUrl":"hhttps://yoursite.kz/payment/callback",
  "acquiringId":5,
  "type":1,
  "customerData":{
      "phone":"77472392990",
      “email”:[email protected],
      "cardData":"wnUx+rkFVhpaTvapu2etbfA7RKf6Hufl31p0517/jsFAS3uilcOqTy8Ir3hav9QoJSyhtG/syw8mwOIU/QNyzdL8uCDhRSJbLkT8f8KpKqrhxrT6e02zMiLrfTG8AdJGOiA9hBIVrRLyz+4URy0pgkFf03azfAedCBRwEHt7hr7zte3W69JNVWYBnSDyailC3nB9zaEEuqsS9UxlbwhMcRr+7e+O+bn1U2El3XzM9nEx/qoU2hRCHusW1s+rWDn/Ttn5eZNCwlyzOXXkGqPQZicpk2mvqE68VvXvRjVaGeIj+cp/Y74nT0jt8H355ST4Zc5A41ArSbyLRoxJUss2w/BPDovROa7chHPH3lv7Isg0UCVNzZ/nDPA+GJ/GrIw1wd12gLv9Ghg8fS2CIAXzuZV9yc+tAmBU4HWnnXKbgejQOHV42DNWGcyOkkuv6Tw7WGtAcAf8DHOOxDO74O7ffgddDypC2gFsjm1Uf+u34TsmZMoUBv/L04mqrkn2qAHfsW96mLuMhPt1fIze5fCkpFVYE5xOrI9d+4hORPs3DaVL0v/YMH41p9/9R+5VvkitZUxxpUC+UFJudnrRP2vc1KbEWcVZVcE78wu8wRo4BCUVUwVpnhHRLMG27VujxGyuVLtPxJsoT38oC7TuZeUbZbd0C9m6lZTvTJeNjYwXFNM="
  },
  "demo":true
}

Флаг demo на продакшене должен быть false или отсутствовать.

1
2
3
4
{
  "url":"ecommerce.pult24.kz/payment/view?id=9876543210",
  "id":"9876543210"
}

После этого приходит ответ (Callback).

Пример присылаемого на callbackUrl запроса:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "orderId":"123",
  "id":"123",
  "account":"[email protected]",
  "amount":10000,
  "commission":100,
  "commissionIncluded":true,
  "attempt":1,
  "returnUrl":"https://my.site.kz/",
  "callbackUrl":"https://my.site.kz/",
  "date":"2006-01-02T15:04:05",
  "dateOut":"2006-01-02T15:04:05",
  "status":1,
  "errCode":0,
  "errMessage":"Ошибок нет",
  "metadata":{
    "session":"3135c7fe-272f-46d0-a5f8-1ab2a59ac17c"
  }
}

Пример кода на PHP

1
2
3
4
5
6
7
8
9
10
11
12
$string = '{"pan":"4111111111112222"}';
$key = [
  'e' => 'AQAB',
  'kty' => 'RSA',
  'n' => '2xt9VX-l0Dbm3hEX-47M_M1_s7IEhChG2rIlUvq2i1RBMpuB4TmUuCAfHvzs40alLSRIcvjUs6CnzwkJkx1g4USqmXdtxRo7u7EeItGiqmV8sMu6IJ9oCTAzUjbZeKluiY81tJrc9b8-6q4RfKXpyXhj2oByyLAbVwc-_vx19UoJ-P36CIyBaBf5Ri_-drUvKkz2Xt-ixffv5B8bNDjGbIXIhpaz_7nheflgMU4PsNa82DOkfmYZvfxXDTcOqATr0QDmTLsvLs_Tj9ttOeoHhDlckdOGXeAzwEzGBGAAsGhBwdIQ6Usx0RQMHZ5gpR251HtrxSOPgM1q5_NbAUG1R5WrURAmdkIYztAXjuPuZniSPGoBqumDw7b1r_W-NPAwBFJiQ2KnCYrMucitpVB07YNiVFSQ9egc8hKl1DzMzNehCAiKVLCzec_hyGEObYgUiQKqXTevdttPrWrEwFIHfv5QM0Ae9M7WhywbPS--k_rIj8K3jmKMh5sevrYNF6o68kK1nv2tuWSOVQfXqvQ-Kv2UhtNt6RXDsH1GgKNYYblAWCAN_wXVoNa2zcJVI6xN_-pqcfv2vGg7ZCc0Aoe4Zv1fz7gOD1BQ8PUSazP_UDVbjA4ehhhDXWr00PbbJioufP1M454gJfmGgVJ4Xcs_C_ueyp1w-8Kg-m1MHklFTN0',
];

$jwk = new JWK($key);
$rsa_oaep_256 = new RSAOAEP256();
$h =[];
$encrypted = $rsa_oaep_256->encryptKey($jwk, $string, [], $h);
echo base64_encode($encrypted);

Использовалась библиотека https://packagist.org/packages/web-token/jwt-encryption-algorithm-rsa