2014 - INTERKASSA · 2020-05-15 · Сторінка 5 CO — Checkout - Точка прийому платежів на сайті мерчанта. XSS — Сross Site Sсriрting

2014

www.interkassa.com Сторінка 2

Зміст 1. Введення ................................................................................................................................................. 4

1.1. Що таке SCI? .................................................................................................................................. 4

1.2. Опис даного документу.................................................................................................................. 4

1.3. Цільова аудиторія .......................................................................................................................... 4

1.4. Термінологія ....................................................................................................................................... 4

1.5. Скорочення ..................................................................................................................................... 4

2. Опис ........................................................................................................................................................ 5

2.1. Основні відомості ........................................................................................................................... 5

2.2. Підключення ................................................................................................................................... 5

2.3. Взаємодія ......................................................................................................................................... 5

2.4. Схема роботи .................................................................................................................................. 6

2.5. Приклад процесу оплати ............................................................................................................... 8

3. Протокол ................................................................................................................................................ 9

3.1. Налаштування каси ....................................................................................................................... 9

3.2. Форма запиту платежу ................................................................................................................ 11

3.3. Сторінки повернення клієнта ..................................................................................................... 14

3.4. Сповіщення про платіж ............................................................................................................... 15

3.4.1. Перевірка інформації щодо платіжу .................................................................................... 16

3.5. Формування цифрового підпису ............................................................................................... 17

4. Розширені можливості ........................................................................................................................ 18

4.1. Прихований режим SCI ............................................................................................................... 18

4.1.1. Опис ......................................................................................................................................... 18

4.1.2. Отримання доступного для каси переліку платіжних напрямків ................................... 18

4.1.3. Отримання даних щодо вартості платежу на платіжному шлюзі ................................... 19

4.1.4. Отримання форми платежу платіжного шлюзу ................................................................ 20

5. Тестування ............................................................................................................................................... 20

5.1. Створення форми запиту платежу ............................................................................................ 20

5.2. Процес оплати та проведення платежу. ................................................................................... 20

6. Довідник ............................................................................................................................................... 22


6.1. Коди валют .................................................................................................................................... 22

6.2. Коди помилок ................................................................................................................................. 22

6.3. Коди платіжних напрямків ........................................................................................................... 23

7. Примітки .............................................................................................................................................. 23

8. Посилання ............................................................................................................................................ 23

9. Перелік змін ......................................................................................................................................... 23


1. Введення 1.1. Що таке SCI? SCI (Shop Cart Interface) — це програмний інтерфейс, який надає можливість будь-якому мерчанту

автоматично приймати платежі у режимі онлайн.

Демонстрація - https://www.interkassa.com/sci/?test

1.2. Опис даного документу У даному документі запропонована вичерпна інформація щодо протоколу взаємодії із платіжним

шлюзом SCI. Також в ньому Ви знайдете типові рішення, приклади реалізації та всю необхідну

інформацію для інтеграції даного шлюзу з Вашим сайтом.

1.3. Цільова аудиторія Даний документ призначений для технічних фахівців, веб-майстрів та розробників, які

працюють у компанії, що хоче приймати та обробляти дані платежів в Інтернеті.

Для використання даного протоколу необхідно володіти базовими знаннями у веб-розробці.

Протокол надає різні за складністю типові рішення підключення

1.4. Термінологія SCI (Shop Cart Interface) - це програмний інтерфейс, який надає можливість будь-

якому мерчанту автоматично приймати платежі у режимі онлайн.

Мерчант (Merchant) - власник рахунку, який приймає платежі на свій рахунок через SCI, як

правило, за продукти або послуги, що пропонуються в його інтернет-магазині.

Клієнт (Client) - покупець, який купує продукти або послуги від мерчанта. Покупець

перенаправляється на SCI для здійснення оплати.

Каса (Checkout) - Точка прийому платежів на сайті мерчанта.

1.5. Скорочення IK — Interkassa SCI — Shop Cart Interface

https://www.interkassa.com/sci/?test


CO — Checkout - Точка прийому платежів на сайті мерчанта.

XSS — Сross Site Sсriрting

ЕЦП — Електроний цифровий підпис

URL — Uniform Resource Locator

WWW — World Wide Web

2. Опис 2.1. Основні відомості

SCI - програмний інтерфейс для прийому платежів через інтернет. Основна суть шлюзу прийому

платежів зводиться до єдиної точки входу клієнта на оплату і повернення його на сайт після оплати.

Вона дозволяє, незалежно від способу оплати, одночасно взаємодіяти з клієнтом та обробляти платежі.

Як і будь-який програмний інтерфейс, він має свій протокол взаємодії, свою функціональність, перелік

вимог і обмежень. Залежно від ступеня інтеграції, протокол дозволяє гнучко реалізовувати різні схеми

взаємодії між Вами і Вашим клієнтом.

2.2. Підключення

Все що Вам необхідно для прийому платежів онлайн:

1. Зареєструватися у системі Інтеркаса. 2. Створити новий (або використовувати існуючий) бізнес-аккаунт. 3. Створити нову касу та налаштувати її (параметри налаштувань наведені нижче).

4. Перенаправити клієнта на оплату за допомогою HTML - форми запиту платежу.

2.3. Взаємодія З точки зору інтеграції, SCI являє собою веб-сторінку (https://sci.interkassa.com/), яка приймає HTTP-запит з GET або POST параметрами, і залежно від типу дії (ik_act) та інтерфейсу (ik_int: web / json) відповідає належним результатом. Беручи до уваги, що сервіс надає можливість гнучкої інтеграції, нижче ми пропонуємо типові рішення для різних завдань і рівнів складності виконання.

Залежно від типу вашого бізнесу, SCI можна використовувати різними способами:

Якщо Ви не маєте власного сайту або продаєте на Вашому ресурсі товари чи послуги у

невеликому обсязі, а замовлення обробляєте в ручному режимі, у такому випадку, Вам

достатньо перенаправити клієнта на оплату за допомогою HTML-форми, яку можна розмістити

як в email листі, так і на Вашому сайті. Після проведення платежу він буде доступний у Вашому

особистому кабінеті. Так само, Ви зможете отримати email або sms повідомлення при

зарахуванні цього платежу.

Якщо Ви надаєте товари або послуги, маєте власний білінг і хочете автоматично обробляти

прийняті платежі, то для цього Вам необхідно реалізувати логіку обробки сповіщення від SCI,

щодо проведеного платежу. Воно буде передаватися автоматично при зарахуванні платежу на

Ваш сайт, незалежно від способу оплати. Наприклад Visa, Mastercard, банківський переказ,

термінали самообслуговування і т.п.

Якщо Ви хочете реалізувати вибір способу оплати та перенаправлення клієнта саме на

платіжний шлюз оминаючи веб-інтерфейс SCI, то це також піддається реалізації за рахунок

підтримки протоколом інтерфейсу JSON, який дозволить Вашому сайту у прихованому для

клієнта режимі отримувати усі необхідні дані для обробки.

https://sci.interkassa.com/


2.4. Схема роботи

Checkout Page — Сторінка, на якій відображається HTML-форма запиту платежу (SCI Form).


Paysystems List — Сторінка з доступними для даної каси платіжними системами, за допомогою яких клієнт може здійснити оплату. Приклад: Payway List — Сторінка вибору способу оплати. Приклад:

Create Invoice — Скрипт створення рахунку на оплату та перенаправлення клієнта на платіжний шлюз

(Pay Form). Payment Gateway — Платіжний шлюз, за допомогою якого клієнт здійснює оплату.


Payment Processing — Скрипт проведення платежу на платіжному шлюзі. Підчас проведення

платежу, сповіщає сервер SCI (Interaction Page) про результат проведення. В свою чергу, SCI сповіщає

Interaction Page на сервері мерчанта з інформацією про рахунок та проведення платежу (Interaction

Form). Payment Result Page — Сторінка результату проведення платежу, з якої клієнт

перенаправляється на SCI.

Result Page — Сторінка SCI, на яку потрапляє клієнт після оплати, очікує отримання SCI результату

проведення платежу платіжним шлюзом, в залежності від цього перенаправляється на сторінку

Успішного проведення платежу (Success Page), Неуспішного (Fail Page) або Незавершеного (Pending

Page) відповідно. Приклад:

2.5. Приклад процесу оплати

Розглянемо типовий процес оплати на прикладі інтернет-магазину. Припустимо, що в цьому

інтернет-магазині клієнту надається можливість покупки квитка у кіно. Оплата замовлення повинна

оброблятися автоматично, а квиток надаватися клієнту відразу після оплати.

1. Клієнт обирає сеанс, який йому сподобався, та місця. Формує замовлення. Створеному

замовленню присвоюється ідентифікаційний номер і сума для оплати.

2. Клієнт переходить на сторінку оплати (Checkout Page) на сайті мерчанта, і йому відображається

кнопка для переходу на платіжний шлюз SCI. Ця кнопка прив'язана до HTML-формі (SCI Form)

і вказує на веб-інтерфейс SCI - https://sci.interkassa.com/. HTML-форма містить ряд прихованих

параметрів для SCI (див. Протокол), та дані платежу (сума, ідентифікатор замовлення та інше).

3. Натиснувши на цю кнопку, клієнт перенаправляється на веб-інтерфейс SCI із доступними

платіжними системами (Paysystems List) за допомогою яких можна здійснити оплату.

4. На сторінці вибору платіжної системи (Paysystems List) клієнту відображаються дані платежу,

сума, опис.

5. Під час вибору однієї з платіжних систем клієнту відображаються доступні способи оплати

через неї (Payway List). Також, клієнту пропонується ознайомитися з умовами оплати та

вказати свої контактні дані.

6. При натисканні на кнопку "Оплатити" в системі Інтеркаса створюється новий рахунок

https://sci.interkassa.com/


(Create Invoice) закріплений за касою, після чого клієнт перенаправляється (Pay Form) на

платіжний шлюз (Payment Gateway).

7. На платіжному шлюзі (Payment Gateway) клієнт здійснює платіж. 8. У процесі проведення платежу платіжним шлюзом (Payment Processing) SCI одержує

повідомлення про результат проведення платежу і ретранслює його в уніфікованому форматі

(Interaction Form) на сайт мерчанта (Interaction Page).

9. Після оплати платіжний шлюз перенаправляє клієнта на сторінку повернення (Result Page).

На цій сторінці, SCI, ґрунтуючись на доступних даних, визначає стан платежу, і залежно

від нього, перенаправляє клієнта на ту, чи іншу сторінку результату на сайті продавця

(Success Page, Fail Page, Pending Page) відповідно.

3. Протокол 3.1. Налаштування каси Налаштування SCI, в першу чергу, починається з налаштувань каси. Вони дозволяють задати значення

за замовчуванням, логіку роботи шлюзу і веб-інтерфейсу, налаштування безпеки, доступні способи

оплати та ін. Повний перелік властивостей каси надається нижче: Властивості Назва Примітки

MAIN

Name Ім`я Відображається на SCI.

Url URL Відображається на SCI.

Desc Опис Відображається на SCI.

Fee Rate Комісія Інтеркаси Використовується SCI при розрахунках суми платежу.

Див. Тарифи.

Fee Shift Перекладення комісії на

покупця

Використовується SCI при розрахунках суми платежу. Вказує у процентах, яка частина комісії Інтеркаси

перекладається на продавця. Наприклад: якщо встановлено 30% комісії на продавці, то 70% на

покупцеві. З розрахунку що комісія Інтеркаси,

наприклад, 3% і суми платежу 100 у.о., сума платежу в

платіжній системі складатиме 102,1 у.о., а зараховані

кошти каси - 99,1 у.о .

Payment No

Unique

Перевірка унікальності номера

платежу Використовується SCI. Ця опція дозволяє робити

перевірку перед створенням нового платежу на

унікальність за його номером. І в разі, якщо платіж з ідентичним номером знайдений в білінгу Інтеркаси

клієнту видається відповідна помилка. При перевірці

використовується параметр SCI "Помилка! Джерело

посилання не знайдено.". За замовчуванням вимкнено.

Payment Amount

Edit

Редагування суми платежу Якщо встановлено, дозволяє клієнту самостійно вказати

суму платежу на SCI. За замовчуванням вимкнено.

Payment Amount

Edit Override

Можливість перевизначити

редагування суми платежу

Вказує на можливість перевизначити властивості

"Редагування суми платежу" параметром "ik_am_ed" на

SCI. За замовчуванням вимкнено.

Payment Lifetime Термін життя платежу Вказує в секундах термін закінчення платежу після його

створення. Не використовується, якщо встановлений

термін


закінчення платежу параметром "ik_exp" на SCI. Типово

"2592000".

Payment Lifetime

Override


термін життя платежу

Вказує на можливість перевизначити властивості "Час

життя платежу" параметром "ik_ltm" на SCI. За

замовчуванням вимкнено.

Show Logo Відображення логотипу Вказує на можливість відображення логотипу каси на

веб-інтерфейсі SCI. За замовчуванням вимкнено.

SECURITY

Sign Algorithm Алгоритм формування

цифрового підпису

Використовується SCI при формуванні цифрового

підпису. Доступні алгоритми: md5, sha256, rsa. Типово

"md5".

Sign Key Ключ цифрового підпису Використовується SCI при формуванні цифрового

підпису.

Sign Test Key Ключ цифрового підпису для

тестування

Використовується SCI при формуванні цифрового

підпису, якщо платіж був здійснений через тестову

платіжну систему. Див. тестування

Sign Co Required Чи потрібен цифровий підпис від каси Використовується SCI при перевірці вхідних параметрів

від каси, якщо опція активована. за замовчуванням

вимкнене. Див. формування цифрового підпису

INTERACTION

Success Url URL сторінки проведенного

платежу

Використовується при перенаправлення клієнта з SCI

назад до сайту каси, якщо платіж проведений.

Success Url

Override

Можливість перевизначити URL

сторінки проведеного платежу

Вказує на можливість перевизначити властивості "URL

сторінки проведеного платежу" параметром "ik_suc_u" на

SCI. За замовчуванням включено.

Success Method Метод запиту сторінки

проведеного платежу Використовується під час перенаправлення клієнта з SCI

назад на сайт каси, якщо платіж є проведеним. За

замовчуванням POST.

Success Method

Override


метод запиту сторінки

проведеного платежу

Вказує на можливість перевизначити властивості "Метод

запиту сторінки проведеного платежу" параметром

"ik_suc_m" на SCI. За замовчуванням включено.

Fail Url URL сторінки непроведеного

платежу

Використовується при перенаправлення клієнта з SCI

назад на сайт каси, якщо платіж є непроведеним.

Fail Url Override Можливість перевизначити URL

сторінки непроведеного

платежу


запиту сторінки непроведеного платежу" параметром

"ik_fal_u" на SCI. За замовчуванням включено.

Fail Method Метод запиту сторінки

непроведеного платежу

Використовується під час перенаправлення клієнта з SCI

назад на сайт каси, якщо платіж є непроведеним. За


Fail Method

Override



непроведеного платежу


запиту сторінки непроведеного платежу" параметром

"ik_fal_m" на SCI. За замовчуванням включено.

Pending Url URL сторінки очікування

проведення платежу Використовується при перенаправлення клієнта з SCI назад на

сайт каси, якщо платіж очікує проведення.


Pending Url

Override

Можливість перевизначити URL

сторінки очікування проведення

платежу

Вказує на можливість перевизначити властивості "URL

сторінки очікування проведення платежу" параметром

"ik_pnd_u" на SCI. За замовчуванням включено.

Pending Method Метод запиту сторінки

очікування проведення платежу Використовується під час перенаправлення клієнта з SCI

назад до сайту каси, якщо платіж очікує проведення. За


Pending Method

Override



очікування проведення платежу


запиту сторінки очікування проведення платежу"

параметром "ik_pnd_m" на SCI. За замовчуванням

включено.

Interaction Url URL сторінки взаємодії Використовується SCI під час відправки повідомлення на

сайт каси про статус платежу. Див. Сповіщення про

статус платежу.

Interaction Url

Override

Можливість

перевизначити URL

сторінки взаємодії

Вказує на можливість перевизначення властивості "URL

сторінки взаємодії" параметром "ik_ia_u" на SCI. За

замовчуванням вимкнено.

Interaction

Method

Метод запиту сторінки взаємодії Використовується SCI при відправці повідомлення на

сайт каси про статус платежу. За замовчуванням POST.

Interaction

Method Override


метод запиту сторінки взаємодії

Вказує на можливість перевизначення властивості

"Метод запиту сторінки взаємодії" параметром "ik_ia_m"

на SCI. За замовчуванням вимкнено.

Interaction

Confirm Http

Code

http-код підтвердження

успішного отримання

повідомлення про статус

платежу

Використовується SCI при відправці

повідомлення на сайт каси про статус платежу.

Якщо при відправці повідомлення, HTTP код

відповіді від сервера каси не зберігатиметься із

вказаним значенням, то таке повідомлення буде

вважатися не доставленим і буде проведена

повторна відправка. За замовчуванням"200"

(OK).

Interaction

Confirm Text

Текст підтвердження успішного

отримання повідомлення щодо

статусу платежу

Використовується SCI при відправці повідомлення на сайт

каси про статус платежу. Якщо при відправці

повідомлення, в тілі відповіді від сервера каси не буде присутній

вказаний текст, то таке повідомлення вважатиметься

недоставленим й буде проведена повторна відправка. За

замовчуванням вимкнено

3.2. Форма запиту платежу

Дана HTML-форма (SCI Form) є ключовою у протоколі SCI. За допомогою неї, Ви можете в будь-

якій точці Вашого веб-додатку перенаправити клієнта на оплату. У ній, Ви передаєте всі необхідні

для цього параметри, такі як ідентифікатор каси, суму і валюту платежу, а також посилання на

сторінки Вашого сайту, на які буде відправлений покупець після успішної або неуспішною оплати,

наприклад:

<form name="payment" method="post" action="https://sci.interkassa.com/" accept-charset="UTF-8"> <input type="hidden" name="ik_co_id" value="51237daa8f2a2d8413000000" /> <input type="hidden" name="ik_pm_no" value="ID_4233" />

<input type="hidden" name="ik_am" value="1.44" /> <input type="hidden" name="ik_desc" value="Payment Description" /> <input type="submit" value="Pay"> </form>


Так само, платіжна форма може містити додаткові параметри, які впливають на доступні

способи оплати, термін дії замовлення, мова інтерфейсу та інше. Повний перелік параметрів

платіжної форми наведено нижче:

Ключ Ім'я Формат Приклад Опис

Платіж

ik_co_id * Checkout ID /^[\w\-]{1,36}$/D 4f269503a1da9

2c807000002 Ідентифікатор каси. Обов'язковий параметр. Див.

Налаштування каси.

ik_pm_no Payment No. /^[\w\-]{1,32}$/D 14533;

ID_4233

Номер платежу. Зберігається у білінгу Інтеркаси.

Дозволяє ідентифікувати платіж у системі та

прив'язати до замовленнями у Вашому білінгу.

Перевіряється унікальність, якщо в налаштованих

каси встановлена така опція. Опціональний

параметр.

ik_cur Currency /^.{3}$/ USD; EUR; UAH Валюта платежу. Обов'язковий параметр, якщо

до каси підключено більше за одну валюту. Див.


ik_am * Amount /^[\d]{1,15}([\.,][\d]

{1,4})?$/

1.43; 43 Сума платежу. Обов'язковий параметр.

ik_am_ed Amount Edit /0|1/ 0; 1 Редагування суми платежу. Якщо встановлено, дозволяє клієнтові самостійно вказати суму платежу. Опціональний параметр. За замовчуванням використовується властивість каси "Редагування суми платежу" (Payment Amount Edit).

ik_am_t Amount Type /invoice|payway/ invoice; payway Тип суми платежу. Дозволяє вказати стратегію розрахунку суми платежу каси й платіжної системи. Залежно від неї розрахунок йде по тій чи іншій сумі. Якщо зазначений тип суми "invoice", то сума платежу в платіжній системі розраховується від суми платежу каси. Якщо ж тип суми "payway" - то навпаки. За замовчуванням - "invoice".

ik_desc Description /^.{0,255}$/ Payment

Description;

Cool stuff

Опис платежу. Опціональний параметр.

ik_exp Expired /^.{0,30}$/ 2011-05-01;

2011-10-01

20:50:33

Термін завершення платежу. Не дозволяє клієнту оплатити платіж пізніше зазначеного терміну. Якщо ж він здійснив оплату, то кошти зараховуються йому на особовий рахунок в системі Інтеркасса. параметр використовується якщо платіж прив'язаний до замовлення, який швидко втрачає свою актуальність із закінченням часу. Наприклад: онлайн бронювання. Опціональний

параметр.

ik_ltm Lifetime /^[\d]{1,10}$/ 3600; 86400 Термін життя платежу. Вказує в секундах термін

закінчення платежу після його створення. Не

використовується, якщо встановлений термін

закінчення платежу (ik_exp). Опціональний

параметр. За замовчуванням використовується

властивість каси "Термін життя платежу"

(Payment Lifetime).


Оплата

ik_pw_on Payway On /^[\w;,\.]{0,512}$/ webmoney;

w1_merchant_

usd

Включені способи оплати. дозволяє вказувати доступні способи оплати для клієнта. Опціональний параметр.

ik_pw_off Payway Off /^[\w;,\.]{0,512}$/ webmoney_me

rchant Відключені способи оплати. дозволяє вказувати недоступні способи оплати для клієнта. Опціональний параметр

ik_pw_via Payway Via /^[\w]{0,62}$/ visa_liqpay_me

rchant_usd Обраний спосіб оплати. Дозволяє вказати точний спосіб оплати для клієнта. Параметр працює тільки з параметром дії (ik_act) встановленого в "process" або "payway". см. дію (ik_act). Опціональний параметр.

Система

ik_sign Signature /^.{0,128}$/ oVAOevI3mWrc

vrjB4j/ySg== Цифровий підпис. Див. формування цифрового

підпису. Обов’язковий параметр, якщо в

налаштуваннях каси включено "Чи потрібен

цифровий підпис від каси" (Sign Co Required).

ik_loc Locale /^.{5}$/' ru; de_us

Локаль. Дозволяє явно вказати мову і регіон встановлені для клієнта. Формується за шаблоном: [language [_territory]. За замовчуванням визначається автоматично.

ik_enc Encoding /^.{0,16}$/ utf-8; ISO-8859-

1; cp1251 Кодування. За замовчуванням використовується

кодування UTF-8.

ik_cli User /^.{0,64}$/ usermail@gmail

.com;

+380501234567

Контактна інформація клієнта. приймає значення як email або номер мобільного телефону. Опціональний параметр.

Взаємодія

ik_ia_u Interaction

Url

URL http://www.site

.com/interactio

n.script

URL сторінки взаємодії. Опціональний параметр.

ik_ia_m Interaction

Method

/get|post/i POST, GET Метод запиту сторінки взаємодії. Опціональний

параметр.

ik_suc_u Success Url URL http://www.site

.com/success.sc

ript

URL сторінки проведеного платежу. Опціональний параметр.

ik_suc_m Success

Method

/get|post/i POST, GET Метод запиту сторінки проведеного платежу. Опціональний параметр.

ik_pnd_u Pending Url URL http://www.site

.com/pending.s

cript

URL сторінки очікування проведення платежу. Опціональний параметр.

ik_pnd_m Pending

Method

/get|post/i POST, GET Метод запиту сторінки очікування проведення

платежу. Опціональний параметр.

ik_fal_u Fail Url URL http://www.site

.com/fail.script URL сторінки непроведеного платежу.

Опціональний параметр.

ik_fal_m Fail Method /get|post/i POST, GET Метод запиту сторінки непроведеного платежу.


http://www.site.com/interaction.script




Протокол

ik_act Action /process|payways|

payways_calc|payw

ay/

process;

payways Дія. Дозволяє перевизначити початковий стан

процесу оплати. Опціональний параметр.

process — обробити;

payways—способи оплати;

payways_calc — розрахунок способів оплати;

payway — платіжний напрямок.

ik_int Interface /web|json/ web; json

Інтерфейс. Дозволяє вказати формат інтерфейсу SCI як "web" або "json". За замовчуванням "web".

ik_x_[nam

e]

X Prefix ik_x_field1 =

somedata;

ik_x_baggage1

= code123;

Префікс додаткових полів. Дозволяє передавати додаткові поля на SCI, після чого ці параметри включаються до повідомлення щодо здійсненого платежу на сторінку взаємодії.

Для створення Ви можете скористатися нашим генератором платіжної форми.

3.3. Сторінки повернення клієнта Після оплати платіжний шлюз перенаправляє клієнта на сторінку повернення (Result Page). На цій

сторінці, SCI пробує визначити, ґрунтуючись на доступних даних, стан платежу, і залежно від нього,

перенаправити клієнта на ту чи іншу сторінку результату на сайті продавця (Success Page, Fail Page,

Pending Page) відповідно. Так само, у формі повернення клієнта (Return Form) на касу, SCI може

передати додаткові параметри, в залежності від налаштувань каси і параметрів платежу. Повний

перелік параметрів форми повернення наведено нижче:

Ключ Ім'я Приклад Опис

Основні

ik_co_id Checkout ID 4f269503a1da92c807000002 Ідентифікатор каси. Див. Налаштування каси.

ik_pm_no Payment No. 14533; ID_4233 Номер платежу. Зберігається в білінгу Інтеркаси.

Дозволяє ідентифікувати платіж в системі та

прив'язати до замовленнями у Вашому білінгу.

Перевіряється унікальність, якщо в

налаштуваннях каси встановлена така опція.

ik_inv_st Invoice State success; fail Стан платежу. Можливі значення:

new - новий,

waitAccept очікує на оплату,

process -в обробці,

success -успішно проведений,

canceled-скасований,

fail-непроведений.

ik_inv_id Invoice Id 12345; 5632156 Ідентифікатор платежу

Увага! Так як, форма повернення клієнта (Return Form) передається через незахищений

канал клієнта, то не може бути використана для зарахування платежу Вашим веб-додатком.


Для цього, Вам необхідно використовувати форму сповіщення про платіж (Interaction

Form).

3.4. Сповіщення про платіж При проведенні платежу, SCI створює запит із даними щодо нього на сторінку взаємодії (Interaction URL). Цей запит містить усі необхідні дані для завершення процесу оплати замовлення на Вашому сайті. Дана форма призначена, в першу чергу, для тісної інтеграції SCI із Вашим сайтом. Вона дозволяє автоматизувати процес, який ініціалізується з отримання даного повідомлення щодо здійсненого платіжу, для зарахування платежу і обробки замовлення в білінгу на Вашому сайті.

Повний перелік параметрів форми повернення наведено нижче:

Ключ Ім'я Приклад Опис

Основные

ik_co_id Checkout ID 4f269503a1da92c807000002 Ідентифікатор каси. Обов'язковий

параметр. Див. Налаштування каси.

ik_pm_no Payment

No.

14533; ID_4233 Номер платежу. Зберігається в

білінгу Інтеркаси. Дозволяє

ідентифікувати платіж в системі,

також прив'язати до замовлення у

вашому білінгу. Перевіряється

унікальність, якщо у налаштуваннях

каси встановлена така опція.


ik_desc Description Payment Description; Cool stuff Опис платежу. Опціональний

параметр.

ik_pw_via Payway Via visa_liqpay_merchant_usd Обраний спосіб оплати. Дозволяє

вказати точний спосіб оплати для

клієнта. Параметр працює тільки

з параметром дії (ik_act)

встановленого в "process" або

"payway". Див. дію (ik_act).


ik_am Amount 1.43; 43 Сума платежу. Обов'язковий

параметр.

ik_cur Currency USD; EUR; UAH Валюта платежу. обов'язковий

параметр, якщо до каси підключено

більше за одну валюта. Див.


ik_act Action process Дія. Значення "process" вказує на те,

що SCI запрошувати зарахування

платежу на стороні каси.

ik_x_[name] X Prefix ik_x_field1 = somedata; ik_x_baggage1 =

code123;

Префікс додаткових полів. Дозволяє передавати додаткові

поля на SCI, після чого ці параметри

включаються до інформації

повідомлення щодо здійсненого

платежу на сторінку взаємодії.

Додаткові


ik_inv_id Invoice Id 12345; 5632156 Ідентифікатор платежу

ik_co_prs_id Checkout

Purse Id

307447812424 Ідентифікатор гаманця каси

ik_trn_id Transaction

Id

14533; ID_4233 Ідентифікатор транзакції

ik_inv_crt Invoice

Created

2013-03-17 17:35:33 Час створення платежу

ik_inv_prc Invoice

Processed

2013-03-17 17:36:13 Час проведення

ik_inv_st Invoice

State

success; fail Стан платежу

ik_ps_price Paysystem

Price

25.00 Сума платежу в платіжній системі

ik_co_rfn Checkout

Refund

24.94 Сума зарахування на баланс

ik_sign Signature oVAOevI3mWrcvrjB4j/ySg== Цифровий підпис. Див. Формування

цифрового підпису

Увага! Дане повідомлення відправляється на сервер каси за посиланням сторінки взаємодії

(Interaction URL) до тих пір, доки SCI, за даним запитом не отримає від сервера каси HTTP-

код стану, який вказано у налаштуваннях каси (за замовчуванням - "200 OK"). Так само, див.

Налаштування каси "Текст підтвердження успішного отримання повідомлення щодо статусу

платежу".

3.4.1. Перевірка інформації щодо платіжу Для виключення можливості компрометації оповіщення про платіж на сторінці взаємодії, Вам

необхідно реалізувати його перевірку, яка наведена нижче.

Крім того, рекомендується проводити додаткову звірку даних оповіщення про платіж за API. Перевірка джерела даних У цій перевірці, Вам необхідно упевнитися, що оповіщення про платіж надіслано безпосередньо

Інтеркасою та не скомпрометовано. Для цього, необхідно перевіряти IP адресу сервера

відправника (SCI). Для аутентифікації джерела відправника і цілісності даних використовується

цифровий підпис (див. Формування цифрового підпису). Діапазон адрес які використовує SCI:

151.80.190.97-104.

Перевірка даних Незважаючи на те, що повідомлення формується на стороні SCI, ЗАВЖДИ перевіряйте таку

інформацію у повідомленні про платіж, як:

Ідентифікатор каси (параметр "ik_co_id"). Повинна відповідати Вашому

ідентифікатору каси.

Сума платежу (параметр "ik_am"). Повинна відповідати сумі Вашого замовлення для

якого був виставлений рахунок.


Стан платежу (параметр "ik_inv_st"). Для зарахування платежу має відповідати

значенню "success" (проведений).

Цифровий підпис (параметр "ik_sign"). Див. Формування цифрового підпису. Валюта платежу (параметр "ik_cur"). Якщо у Вашій касі більше за одну валюту, Ви

маєте зберігати та порівнювати валюти Вашого замовлення.

3.5. Формування цифрового підпису Цифровий підпис формується шляхом об'єднання значень всіх параметрів форми з префіксом "ik_"

в алфавітному порядку їх імен (без урахування регістра), з додаванням в кінець «секретного ключа»

каси. Конкатенація йде через символ ":". Якщо форма містить кілька полів з однаковими іменами,

такі поля сортуються в алфавітному порядку їх значень.

Отримане після об'єднання параметрів та «секретного ключа» значення хеширується обраним

методом формування ЕЦП, і його байтове уявлення кодується в Base64.

ik_sign = Base64(MD5(Implode(Sort(Params) + SecretKey, ':'))));

Увага! Переконайтеся, що ваша хеш-функція повертає масив байт, а не їх подання до HEX.

Якщо все зроблено вірно, довжина параметра ik_sign складає рівно 24 символи, при хеш-

функції MD5.

Увага! При створенні підпису на Інтеркасу, Ви маєте підписувати лише бойовим ключем.

Увага! Якщо платіжний напрямок, яким оплачено рахунок є тестовим (ik_pw_via =

'test_interkassa_test_xts'), то при формуванні цифрового підпису використовується

«Тестовий секретний ключ». Це поширюється на сповіщення про платіж Див.

Тестування.

Увага! Під час отримання даних на URL взаємодії, необхідно видаляти з даних поле ik_sign,

і тільки після цього формувати підпис для звірки.

Приклад алгоритму формування ЕЦП на мові PHP:

unset($dataSet['ik_sign']); видаляємо з даних строку підпису

ksort($dataSet, SORT_STRING); // сортуємо по ключам в алфавітному порядку елементи масиву array_push($dataSet, $key); // додаємо в кінець масиву "секретний ключ"

$signString = implode(':', $dataSet); // конкатенуємо значення через символ ":" $sign = base64_encode(md5($signString, true)); // беремо MD5 хеш в бінарному вигляді по сформованому рядку і кодуємо в BASE64

return $sign; // повертаємо результат Інші приклади реалізації на різних мовах програмування доступні на сайті у розділі

"Розробникам".


4. Розширені можливості

4.1. Прихований режим SCI

4.1.1. Опис Даний режим призначений для прийому платежів через Інтеркаса з перенаправленням клієнта під

час оплати, безпосередньо на шлюз платіжної системи. Це дозволить Вашому серверу, у фоновому

для клієнта вигляді, одержувати дані HTML-форми призначеної для оплати через вказаний

платіжний шлюз. Все що необхідно для цього - використовувати JSON інтерфейс SCI, який можна

вказати через параметр форми запиту платежу - "ik_int" зі значенням "json

4.1.2. Отримання доступного для каси переліку платіжних напрямків Для отримання платіжної форми для оплати через шлюз платіжної системи, необхідно вказати такі значення параметрів: тип дії "ik_act" - "payways. Та призвести HTTP-запит з даними форми запиту платежу на SCI методом POST або GET, а у відповідь отримати JSON- пакет з даними за доступними для оплати даного платежу платіжними напрямками.

Приклад запиту:

<form name="payment" method="post" action="https://sci.interkassa.com/" accept-charset="UTF-8">

<input type="hidden" name="ik_co_id" value="51237daa8f2a2d8413000000" />

<input type="hidden" name="ik_pm_no" value="ID_4233" /> <input type="hidden" name="ik_am" value="1.44" /> <input type="hidden" name="ik_desc" value="Payment Description" /> <input type="hidden" name="ik_act" value="payways" /> <input type="hidden" name="ik_int" value="json" />

<input type="submit" value="Pay"> </form>

Приклад відповіді:

{ "resultCode": 0, "resultMsg": "Success", "resultData": { "paywaySet": [ { "_id": "4f217ec98f2a2d4c0c0002d4", "als": "privatterm_liqpay_merchant_uah", "cur": "4e4147718f2a2d7014000467",

"curAls": "uah", "in": "4e4147718f2a2d701400046e", "inAls": "merchant", "insInId": "4f674bd0e313d0f810000154", "ps": "liqpay",

"ser": "privatterm", "srt": "25" },

{ "_id": "4f217ec98f2a2d4c0c0002d6", "als": "anelik_w1_merchant_rub", "cur": "4e4147718f2a2d701400047c", "curAls": "rub", "in": "4e4147718f2a2d7014000484", "inAls": "merchant", "insInId": "4f674bd0e313d0f81000014c",


"ps": "w1", "ser": "anelik", "srt": "36" }, ... ] }

}

4.1.3. Отримання даних щодо вартості платежу на платіжному шлюзі Для отримання платіжної форми для оплати через шлюз платіжної системи, необхідно вказати такі значення параметрів: тип дії "ik_act" - "payway", спосіб оплати "ik_pw_via" - <payway alias> (будь-який доступний для каси спосіб оплати, (див. Коди платіжних напрямів). Та призвести HTTP-запит з даними форми запиту платежу на SCI методом POST або GET, а у відповідь отримати JSON-пакет з даними по платежу. Приклад запиту:

<form name="payment" method="post" action="https://sci.interkassa.com/" accept-charset="UTF-8"> <input type="hidden" name="ik_co_id" value="51237daa8f2a2d8413000000" /> <input type="hidden" name="ik_pm_no" value="ID_4233" /> <input type="hidden" name="ik_am" value="1.44" /> <input type="hidden" name="ik_desc" value="Payment Description" /> <input type="hidden" name="ik_int" value="json" /> <input type="hidden" name="ik_act" value="payway" /> <input type="hidden" name="ik_pw_via" value="webmoney_webmoney_merchant_wmz" /> <input type="submit" value="Pay"> </form>

Приклад відповіді {

"resultCode":0, "resultMsg":"Success", "resultData": { "invoice": {

"checkoutId":"51237daa8f2a2d8413000000", "checkoutPurseId":"307447812424", "paymentNo":"218", "paywayId":"4f217ec98f2a2d4c0c000318", "paywayPurseId":"50d828d159d93cfb72000001",

"expired":1385305065, "coAmount":5, "coRefund":4.925, "ikFee":0.15, "ikFeeIn":0.075, "ikFeeOut":0.075, "ikPrice":5.075, "psAmount":0.4323,

"psFeeIn":0, "psFeeOut":3, "psPrice":0.44, "psExchRate":0.085166 } } }


4.1.4. Отримання форми платежу платіжного шлюзу Для отримання платіжної форми для оплати через шлюз платіжної системи, необхідно вказати такі значення параметрів: тип дії "ik_act" - "process", спосіб оплати "ik_pw_via" - <payway alias> (будь-який доступний для каси спосіб оплати, див. Коди платіжних напрямів). Та призвести HTTP-запит з даними форми запиту платежу на SCI методом POST або GET, а у відповідь отримати JSON-пакет з даними для форми платежу. Приклад запиту:

<form name="payment" method="post" action="https://sci.interkassa.com/" accept-charset="UTF-8"> <input type="hidden" name="ik_co_id" value="51237daa8f2a2d8413000000" /> <input type="hidden" name="ik_pm_no" value="ID_4233" /> <input type="hidden" name="ik_am" value="1.44" /> <input type="hidden" name="ik_desc" value="Payment Description" /> <input type="hidden" name="ik_int" value="json" /> <input type="hidden" name="ik_act" value="process" /> <input type="hidden" name="ik_pw_via" value="webmoney_webmoney_merchant_wmz" />

<input type="submit" value="Pay"> </form> Приклад відповіді:

{

"resultCode": 0, "resultMsg": "Success",

"resultData": { "paymentForm": { "action": "https://merchant.webmoney.ru/lmi/payment.asp", "method": "post", "parameters": {

"LMI_PAYEE_PURSE": "Z922208109129", "LMI_PAYMENT_AMOUNT": "103.10", "LMI_PAYMENT_DESC": "Payment No. IK15002746; Ноутбук Asus Z99LSeries", "LMI_PAYMENT_NO": "15002746" } } } }

5. Тестування

5.1. Створення форми запиту платежу Для спрощеного створення платіжної форми, ми пропонуємо Вам скористатися нашим

генератором платіжної HTML-форми. За допомогою нього, Ви зможете швидко створити та

налаштувати форму запиту платежу, вказати всі необхідні параметри й налаштування, а також,

протестувати її для перенаправлення клієнта на оплату через SCI.

5.2. Процес оплати та проведення платежу. Для тестування процесу оплати і проведення платежу існує "Тестова платіжна система". У новій касі вона відключена за замовчуванням, як можливий спосіб оплати у Вашій касі. Для включення перейдіть до Налаштування каси -> Платіжні системи та увімкніть "Тестова платіжна система".

https://merchant.webmoney.ru/lmi/payment.asp


Тестовий платіжний напрям:

Alias Сервіс Шлюз Спосіб Валюта

test_interkassa_test_xts Тестовая платежная система Інтеркаса Тест XTS

Увага! Якщо Ваша каса налаштована і працює в публічному відкритому режимі, Вам

необхідно відключити у налаштуваннях каси "Тестову платіжну систему".

Для здійснення тестової оплати, Вам достатньо лише, вибрати її в якості системи для оплати, і

натиснути кнопку "Оплатити" або вибрати іншу дію з платежем. Після чого, SCI перенаправить

Вас на відповідну сторінку повернення на Вашому сайті.

Увага! При проведенні платежу через "Тестову платіжну систему", транзакція не

звершується! Змінюється тільки стан виставленого Вами рахунку, без зарахування суми

платежу на Ваш баланс.

Таким чином, Ви зможете протестувати, повною мірою весь процес оплати, а також, обробку

повідомлення про платіж (Interaction Form) на Вашій касі. Для цього, використовуйте "тестовий

секретний ключ", який доступний у налаштуваннях каси. Даний ключ використовується для підпису

повідомлення про платіж тільки через "тестову платіжну систему".

Увага! Даний механізм, з "тестовим секретним ключем", не допускає ситуацію, коли Ваш

веб-додаток може зарахувати платіж, проведений через "тестову платіжну систему", за

даними, переданими на сторінку взаємодії (Interaction URL). Для цього, ЗАВЖДИ

перевіряйте цифровий підпис від SCI.


6. Довідник

6.1. Коди валют Актуальна інформація стосовно кодів валют завжди доступна на сайті Interkassa.

ID Ім'я Код символьный Код цифирный

10 Євро EUR 978

20 Долар USD 840

30 Гривня UAH 980

40 Російський рубль RUB 643

50 Білоруський рубль BYR 974

60 Золото (одна тройська унція) XAU 959

99 Тестова валюта XTS 963

6.2. Коди помилок Код Alias Повідомлення

100 E_IS_NOT_WORKING SCI is not working. Try later...

101 E_PROTOCOL_NOT_EXIST Protocol not exist

103 E_REQUEST_IS_EMPTY Request is empty

102 E_INVALID_REQUEST_METHOD Invalid request method

104 E_REQUEST_IS_NOT_SECURE Request is not secure

106 E_PARAM_IS_NOT_SET Parameter "%s" is not set

107 E_PARAM_IS_EMPTY Parameter "%s" is empty

108 E_PARAM_INCORRECT_FORMAT Parameter "%s" has incorrect format

109 E_PARAM_SET_FORBIDDEN Parameter set "%s" forbidden

120 E_CHECKOUT_NOT_FOUND Checkout is not found

121 E_CHECKOUT_UNAVAILABLE Checkout is unavailable

122 E_CHECKOUT_CURRENCY_INVALID Checkout has no purses with requested currency

115 E_REQUEST_SIGN_INVALID Request sign "%s" is invalid

110 E_PAYMENT_NO_NOT_UNIQUE Payment no "%s" must be unique

123 E_CHECKOUT_PURSE_UNAVAILABLE Checkout purse is unavailable


124 E_CHECKOUT_PAYWAY_UNAVAILABLE Payway is is unavailable for current checkout

125 E_CHECKOUT_PAYWAYS_UNAVAILABLE Checkout has not any available payway

6.3. Коди платіжних напрямків Актуальну інформацію стосовно кодів платіжних напрямків завжди можна отримати через API за

адресою - https://api.interkassa.com/v1/paysystem-input-payway.

7. Примітки

Електронний цифровий підпис ·

Білінг

Кодування Перелік кодів стану HTTP

8. Посилання Генератор хешів Документація Interkassa API

Коди валют

Довідник способів оплати Приклади реалізації підключення на різних мовах програмування

9. Перелік змін

v0.1: нова документація протоколу SCI v0.8: додано розділ "Розширені можливості" v1.0: зміни параметрів на сторінках повернення

https://api.interkassa.com/v1/paysystem-input-payway

2014 - INTERKASSA · 2020-05-15 · Сторінка 5 CO — Checkout - Точка прийому платежів на сайті мерчанта. XSS — Сross Site Sсriрting

Documents