SCI


1.Введение

1.1.Что такое SCI?

SCI (Shop Cart Interface) — это программный интерфейс, который позволяет любому мерчанту автоматически принимать платежи в режиме онлайн.

Демонстрация - https://sci.interkassa.com/?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
  • 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, который позволит Вашему сайту в скрытом для клиента режиме получать все необходимые данные для процессинга.


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. При нажатии на кнопку "Оплатить" в системе Интеркасса создается новый счет (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.Настройки кассы

Свойство Название Примечание
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 обратно на сайт кассы, если платеж является непроведенным. По умолчанию POST.
Fail Method Override Возможность переопределить метод запроса страницы непроведенного платежа Указывает на возможность переопределения свойства "Метод запроса страницы непроведенного платежа" параметром "ik_fal_m" на SCI. По умолчанию включено.
Pending Url URL страницы ожидания проведения платежа Используется при перенаправления клиента с SCI обратно на сайт кассы, если платеж ожидает проведение.
Pending Url Override Возможность переопределить URL страницы ожидания проведения платежа Указывает на возможность переопределения свойства "URL страницы ожидания проведения платежа" параметром "ik_pnd_u" на SCI. По умолчанию включено.
Pending Method Метод запроса страницы ожидания проведения платежа Используется при перенаправления клиента с SCI обратно на сайт кассы, если платеж ожидает проведение. По умолчанию POST.
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_cur" value="uah"/>
       <input type="hidden" name="ik_desc" value="Payment Description"/>
       <input type="submit" value="Pay">
   </form>


Так же, платежная форма может содержать дополнительные параметры, которые влияют на доступные способы оплаты, срок действия заказа, язык торгового интерфейса и т.п. Полный перечень параметров платежной формы приведен ниже:

Ключ Имя Формат Пример Описание
Платеж        
ik_co_id * Checkout ID /^[\w\-]{1,36}$/D 4f269503a1da92c807000002 Идентификатор кассы. Обязательный параметр. См. настройки кассы.
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_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_merchant Отключенные способы оплаты. Позволяет указывать недоступные способы оплаты для клиента. Опциональный параметр.
ik_pw_via Payway Via /^[\w]{0,62}$/ visa_liqpay_merchant_usd Выбранный способ оплаты. Позволяет указать точный способ оплаты для клиента. Параметр работает только с параметром действия (ik_act) установленного в "process" или "payway". см. действие (ik_act). Опциональный параметр.
Система        
ik_sign Signature /^.{0,128}$/ oVAOevI3mWrcvrjB4j/ySg== Цифровая подпись. См. формирования цифровой подписи. Обязательный параметр, если в настройках кассы установлен параметр "Проверять подпись в форме запроса платежа" (Sign Co Required).
ik_loc Locale /^.{5}$/' ru; en; ua;   Локаль. Позволяет явно указать язык и регион установленные для клиента. Формируется по шаблону: [language[_territory]. По умолчанию определяется автоматически.
ik_enc Encoding /^.{0,16}$/ utf-8; ISO-8859-1; cp1251 Кодировка. По умолчанию используется кодировка UTF-8.
Взаимо-
действие
       
ik_ia_u Interaction Url URL http://www.site.com
/interaction.script
URL страницы взаимодействия. Опциональный параметр.
ik_ia_m Interaction Method /get|post/i POST, GET Метод запроса страницы взаимодействия. Опциональный параметр.
ik_suc_u Success Url URL http://www.site.com
/success.script
URL страницы проведенного платежа. Опциональный параметр.
ik_suc_m Success Method /get|post/i POST, GET Метод запроса страницы проведенного платежа. Опциональный параметр.
ik_pnd_u Pending Url URL http://www.site.com
/pending.script
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 Метод запроса страницы непроведенного платежа. Опциональный параметр.
Протокол        
ik_act Action /process
|payways
|payways_calc
|payway/
process; payways Действие. Позволяет переопределить начальное состояние процесса оплаты. Опциональный параметр. process — обработать; payways — способы оплаты; payways_calc — расчет способов оплаты; payway — платежное направление.
ik_int Interface /web|json/ web; json   Интерфейс. Позволяет указать формат интерфейса SCI как "web" или "json". По умолчанию "web".
ik_x_[name] 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_cur Currency USD; EUR; UAH Валюта платежа.
ik_am Amount 1.43; 43 Сумма платежа.
ik_desc Description Payment Description; Cool stuff Описание платежа.
ik_pw_via Payway Via visa_liqpay_merchant_usd Выбранный способ оплаты.
ik_x_[name] X Prefix ik_x_field1 = somedata; ik_x_baggage1 = code123; Префикс дополнительных полей.
Дополнительные      
ik_inv_crt Invoice Created 2013-03-17 17:30:33 Время создания платежа.
ik_inv_prc Invoice Processed 2013-03-20 15:46:58 Время проведения платежа.
ik_inv_st Invoice State success; fail Состояние платежа. Возможные значения: waitAccept —ожидает оплаты, process —обрабатывается, success —успешно проведен, canceled—отменен, fail—не проведен.
ik_ps_price Paysystem Price 25.32 Сумма платежа в платежной системе.
ik_co_rfn Checkout Refund 24.94 Сумма зачисления на счет кассы.

Внимание! Так как, форма возврата клиента (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.

 

Проверка информации о платеже
Для исключения возможности компрометации оповещения о платеже на странице взаимодействия, вам необходимо реализовать его проверку, которая приведена ниже. Кроме того, рекомендуется проводить дополнительную сверку данных оповещения о платеже по API. Проверка источника данных В данной проверке, Вам необходимо удостовериться, что оповещение о платеже отправлено непосредственно Интеркассой и не скомпрометировано. Для этого, необходимо проверять IP адрес сервера отправителя (SCI). Диапазон адресов которые использует SCI: 151.80.190.97-104. Для аутентификации источника отправителя и целостности данных используется цифровая подпись (см. Формирование цифровой подписи).

 

Проверка данных
Несмотря на то, что уведомление формируется на стороне SCI, ВСЕГДА проверяйте такую информацию в уведомлении о платеже, как: Идентификатор кассы (параметр "ik_co_id"). Должен соответствовать Вашему идентификатору кассы. Сумма платежа (параметр "ik_am"). Должна соответствовать сумме Вашего заказа для которого был выставлен счет. Состояние платежа (параметр "ik_inv_st"). Должно соответствовать значению "process" (проведен). Цифровая подпись (параметр "ik_sign"). см.

3.5.Формирование цифровой подписи

Цифровая подпись формируется путем объединения значений всех параметров формы с префиксом "ik_" в алфавитном порядке их имен (без учета регистра), с добавлением в конец «секретного ключа» кассы. Конкатенация идет через символ ":". Если форма содержит несколько полей с одинаковыми именами, такие поля сортируются в алфавитном порядке их значений. Полученное после объединения параметров и «секретного ключа» значение хешируется выбранным методом формирования ЭЦП, и его байтовое представление кодируется в Base64. ik_sign = Base64(MD5(Implode(Sort(Params) + SecretKey, ':'))));

Внимание! Убедитесь, что ваша хэш-функция возвращает массив байт, а не их представление в HEX. Если все сделано верно, длина параметра ik_sign составляет ровно 24 символа, при хэш-функции MD5.

Внимание! При создании подписи на Интеркассу, вы данные должны подписывать только секретным ключом.

Внимание! Если платежное направление, которым оплачен счет является Тестовым (ik_pw_via = ‘test_interkassa_test_xts’), то при формировании цифровой подписи используется «Тестовый секретный ключ». Это распространяется на уведомление о платеже См. Тестирование.

Внимание! При получении данных на урл взаимодействия, вы должны удалять из данных поле ik_sign, и только после этого формировать подпись для сверки.

Пример алгоритма формирования ЭЦП на языке PHP: https://github.com/CMSInterkassa

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">
</fom>
Пример ответа:
{
    "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"/v>
    <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.Процесс оплаты и проведения платежа

Для тестирования процесса оплаты и проведения платежа существует "Тестовая платежная система". В новой кассе она отключена по умолчанию, как возможный способ оплаты в Вашей кассе. Для включения данной платежной системы перейдите в Настройки кассы -> Платежные системы и включите «Тестовая платежная система».
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