CoinyPay API
Начало работы с CoinyPay
Обновлено 2 сентября 2017 г
Внимание: API CoinyPay находится в тестовом режиме. Если у Вас возникают проблемы с подключением просим сразу обращаться в поддержку через форму обратной связи.
Возможности интеграции
CoinyPay предоставляет уникальный платежный интерфейс в Facebook Messenger для оплаты заказов и счетов конечным пользователям Вашего веб-сайта или гостям заведения. Счет может быть создан как прямо из Facebook-чата (например, официантом в ресторане) или POS-терминала, так и с интернет-магазина с помощью нашей платежной кнопки через наше API.

Вы можете использовать наше API для:
  1. Создания плагина для Вашего POS-терминала чтобы официанты смогли напрямую выставлять счета гостям с использованием меню заведения, системы чаевых, встроенной отчетности.
  2. Интеграции нашей платежной кнопки "CoinyPay - Оплата через Facebook Messenger" для удобной и простой оплаты онлайн-заказов Вашего сайта
Запуск
Для того чтобы начать использовать CoinyPay и получать платежи Вам необходимо будет запустить чат-бота по ссылке https://m.me/coinypay и выбрать карточку "Подключить компанию". Во время процесса регистрации Вас спросят:

  • Название компании
  • Данные авторизации в платежной системе (Merchant Login и Secret Key)
  • Callback URL для уведомлений (webhook)
Если у Вас уже есть необходимые данные, то Вы можете приступить к запуску прямо сейчас и сразу переходить к подразделу "Настройка работы CoinyPay". Если нет, то переходите в следующий подраздел "Аккаунт в платежной системе".
Аккаунт в платежной системе
Интегрируйте Ваш расчетный счет с платежной системой WayForPay. Для этого необходимо выслать нам заполненный договор и документы из списка на почту [email protected] и мы сообщим Вам как только Ваш мерчант будет активен для оплаты. Если у Вас у же есть существующий мерчант аккаунт WayForPay, то присоедините его к CoinyPay боту как описано в пункте "Запуск" выше.
Настройка работы CoinyPay
Мы также вышлем Вам:

1) Специальный код для подключения продавцов или официантов к Вашему мерчанту, которые смогут выставлять счета гостям или клиентам прямо через чат-бота CoinyPay в Facebook Messenger
2) Secret key и seller id, которые понадобятся для выставления счетов через API для чекаута на веб-сайтах

Для выставления счета просто введите в чат-бот CoinyPay команду в формате:
coiny_id amount
где:
coiny_id - уникальны ID, который есть у каждого клиента (запросите его у гостя в заведении)
amount - сумма для оплаты

Например, команда 123 500 выставит счет клиенту с CoinyID 123 на сумму 500 грн и он сможет оплатить его в один клик.

Вот и все! Вы готовы к выставлению счетов через Facebook Messenger! Подробнее про технические нюансы интеграции смотрите разделы "Платежная кнопка" и "Плагин для POS".
Помощь
Нужна помощь? Напишите на [email protected] или свяжитесь с нами через форму обратной связи.
CoinyPay API v 1.1
Инструкция по подключению платежной кнопки CoinyPay и оплаты в вашем чат-боте
Обновлено 16 февраля 2018 года
Краткое описание
Используя платежную кнопку CoinyPay Ваш веб-сайт или чат-бот сможет поддерживать оплату заказа или счета с помощью Facebook Messenger.
Помимо технической реализации, необходимо создать мерчант-аккаунт в платежной системе WayForPay, получить ключ и использовать его для подключения своего веб-сайта. Подробнее описано в разделе Начало работы.
Список команд
Для оплаты через CoinyPay в интернет магазине по кнопке убедитесь, что веб-сайт удовлетворяет следующим требованиям:

1. Возможность динамически формировать страницу на стороне сервера
2. Принимать callback по результатам оплаты
3. Возможность сделать на сервере endpoint для запроса состояния оплаты
Сценарий работы
1. После создания мерчанта WayForPay, магазин подключается к CoinyPay через Facebook Messenger (из главного меню, для этого нужно привязать карту), вводит все необходимые данные и получает секретный ключ для подписи счетов
2. Магазин генерирует форму с кнопкой (состоящую из формы с подписью и статической картинки + JS) и показывает пользователю ф3. Клиент нажимает кнопку (отправляет форму) и разрешает ФБ-приложению CoinyPay взаимодействовать с ним
4. Если клиент не зарегистрирован в CoinyPay - ему предлагают сделать это. В этом случае ему повторно надо будет нажать на кнопку оплаты.
5. Клиент получает счет в месседжер и подтверджает его.
6. В случае успешной оплаты на указанный при регистрации callback URL отправляются данные об оплате, а если сервер магазина возвращает состояние оплаты - веб-страница отреагирует на факт оплаты.
Пример использования
Вы можете попробовать сделать тестовую оплату здесь. Для этого Вам сначала необходимо активировать CoinyPay в Facebook Messenger и привязать платежную карту.
Помощь
Есть вопросы? Напишите нам на [email protected] или свяжитесь с нами через форму обратной связи.
Код платежной кнопки
Нужные поля необходимо сгенерировать. См. подсказки под кодом.
Endpoint:
https://zed.coinypay.com/webbutton/ordercreate

<form action ="https://zed.coinypay.com/webbutton/ordercreate" method="POST" id="frm" name="frm">
<input type="hidden" id="amount_cp" name="amount" value = "13.4">
<input type="hidden" id="currency_cp" name="currency" value = "UAH"><!--Only! -->
<input type="hidden" id="innerid_cp" name="innerid" value = "YOUR_ORDER_ID_FOR_REFERENCE / RANDOM NUMBER">
<input type="hidden" id="description" name="description" value="DESCRIPTION OF THE PURCHASE" />
<input type="hidden" id="content" name="content" value = "CONTENT LINE 1 - optional">
<input type="hidden" id="content" name="content" value = "CONTENT LINE 2 - optional">
<input type="hidden" id="content" name="content" value = "CONTENT LINE 3 - optional">
<input type="hidden" name="seller" value="YOUR_SELLER_ID (obtained from CoinyPay)"><br>
<input type="hidden" name="signature" value="FORM_DATA_SIGNATURE">
<input type="image" src="http://coinypay.ingenia.nz/images/CoinyPay_button1_small.png" onclick="submitForm();">
</form>

<script>
   var cp = {}; cp.tmp_key = null;
   function submitForm() {
   document.frm.target = "myActionWin";
   window.open("","myActionWin","width=500,height=300,toolbar=0");
   document.frm.submit();
   cp.tmp_key = setInterval(updateBill, 5000);
   return true;
}

function updateBill () { // Use your payment status function here
   $.post('/payments/coinypaystatus', {innerid: document.frm.innerid.value, signature:''}, 
   function(response){
      result.innerHTML = JSON.stringify(unescape(response));
      if (['paid', 'cancelled'].includes (response.status)) {
      result.innerHTML = 'Payment status: ' + response.status;
      clearInterval (cp.tmp_key);
// Proceed with payment result here: redirect or whatever else
// ie. window.location('/success.html?innerid='+innerid);
      }
},'json');
}

</script>
<div id="result">
<!--  Payment results will appear here -->
</div>`
Поле signature:
"signature" = HmacMD5 строка, которая состоит из
seller, innerid соединенных через точку с запятой (;) , без пробелов.

Например:
Строка для подписи: SLR444;12345
С ключом SecretKey подпись будет d026e43b6154bf1c41f916c5d76284fc
При регистрации мерчанта у него будет запрошен Callback URL (webhook), на который будет отправлено уведомление об оплате.
Формат данных уведомления:
{"innerid":"YOR_ORDER_ID", "coinypay_bill_id":"Coiny pay Bill identificator", "amount:13.4, "status":"PAID | CANCELLED | FAILED", "signature":"SIGNATURE"}
"signature" = HmacMD5 строки, которая состоит из
seller, innerid, coinypay_bill_id, amount, status соединенных через точку с запятой (;), без пробелов.

Например:
Строка для подписи: SLR444;12345;C888;13.4;PAID
С ключом SecretKey подпись будет 39bdf94c6ebecd276f56e0515a728d41
Эту подпись важно проверять, чтобы убедиться, что уведомление вам присылает именно CoinyPay.
JSON API
Этот запрос удобен для выставления счета в CoinyPay бота прямо из вашего чат-бота
Альтернативно, вы можете использовать JSON API для отправки запроса на выставления счета:

{
 "amount": 13.4,
 "currency": "UAH",
 "innerid": "YOUR_ORDER_ID_FOR_REFERENCE / RANDOM NUMBER",
 "description": "DESCRIPTION OF THE PURCHASE",
 "content": [
    "CONTENT LINE 1 - optional",
    "CONTENT LINE 2 - optional",
    "CONTENT LINE 3 - optional"
    ],
 "seller": "YOUR_SELLER_ID (obtained from CoinyPay)",
 "signature": "FORM_DATA_SIGNATURE"
}

content-type: application/json заголовок HTTP
CoinyPay API 1.0
Инструкция по созданию плагина CoinyPay для POS-терминалов
Обновлено 19 сентября 2017 г
Внимание: Данное API находится в процессе разработки. Доступные к работе команды отмечены в скобках - (реализовано).
Краткое описание
Заведения могут выставлять счета используя Facebook Messenger, либо делать это через наше API, которые Вы можете реализовать в Вашем POS-терминале, расширив его платежную функциональность.
Помимо технической реализации, необходимо создать мерчант-аккаунт в платежной системе WayForPay, получить ключ и использовать его для подключения своего веб-сайта. Подробнее описано в разделе Начало работы.
Список команд
Команды:
1) Выставление счета (реализовано)
2) Отмена счета
3) Запрос статуса заказа
3) Запросить карты официанта
4) Добавить/удалить карту официанта
5) Запрос общей суммы чаевых для официанта
6) Установить карту по умолчанию

Callbacks:
1) Подтверждение оплаты пользователем (реализовано)
2) Получение чаевых
3) Смена статуса заказа
Процедура использования команд
Процесс выставления, оплаты и отмены счета

  1. Под каждым заказом гостя официант должен иметь поле для ввода CoinyID и кнопку отправки счета гостю
  2. Когда официанта нажал на кнопку отправляется запрос на сервер CoinyPay со следующими данными:
    1. Общая сумма заказа
    2. Позиции меню в формате наименование и цена
    3. Имя официанта
  3. Если у гостя возникла ошибка в момент подтверждения счета, то она возвращается в терминал и официант получает уведомление что счет подтвердить не удалось со всеми подробностями ошибки (см. Возможные ошибки). При этом официант может повторно выставить счет на этот или новый CoinyID
  4. Если счет выставлен успешно запускаем поток ожидания подтверждения заказа (до 30 минут)
  5. Когда гость подтвердил обновляем статус заказа на подтвержденный
  6. В течении 30 минут после подтверждения у заказа доступна кнопка отмены, при нажатии на которую пользователь получает уведомления что его счет отменен
  7. После 30 минут статус заказа помечается как оплаченный

Чаевая карта официанту


  1. В профилях официанта появляется меню с возможностью добавить, удалить и выбрать карту (через эквайринг WayForPay) для чаевых
  2. Если карта добавлена, то гость может оставить чаевые, которые перейдут напрямую на карту официанту
  3. Общая сумма полученных через CoinyPay чаевых может быть также отображена в этом меню

Возможные ошибки


  1. Не существующий CoinyID
  2. Недостаточно средств на карте
  3. Превышен интернет лимит
  4. Превышена частота оплат
  5. Не удалось провести операцию на стороне банка

Помощь
Есть вопросы? Напишите нам на [email protected] или свяжитесь с нами через форму обратной связи.
Выставление счета
Endpoint:
https://zed.coinypay.com/payapi

POST Payload:
{“seller”:”SLR444”, “coiny_id”:”00000”, “innerid”:”unique_id_at_your_side e.g. 12345”, ”amount”:43.11, “currency”:”UAH”, “description”:”General description of the sale”, “content”:[“Item 1”, “Item 2”, “item 3”], “signature”:”the_signature”}
Callback
Когда (если) оплата выполнена, придет следующий ответ:

{"innerid":"YOR_ORDER_ID", "coinypay_bill_id":"Coiny pay Bill identificator", "amount”:13.4, "status":"PAID | CANCELLED | FAILED", "signature":"SIGNATURE"}

Имейте ввиду, что колбека может не быть, в случае, если клиент не нажал "Оплатить".
Поле signature:
"signature" = HmacMD5 строка, которая состоит из
seller, innerid соединенных через точку с запятой (;) , без пробелов.

Например:
Строка для подписи: SLR444;12345
С ключом SecretKey подпись будет d026e43b6154bf1c41f916c5d76284fc
При регистрации мерчанта у него будет запрошен Callback URL (webhook), на который будет отправлено уведомление об оплате.
Формат данных уведомления:
{"innerid":"YOR_ORDER_ID", "coinypay_bill_id":"Coiny pay Bill identificator", "amount:13.4, "status":"PAID | CANCELLED | FAILED", "signature":"SIGNATURE"}
"signature" = HmacMD5 строки, которая состоит из
seller, innerid, coinypay_bill_id, amount, status соединенных через точку с запятой (;), без пробелов.

Например:
Строка для подписи: SLR444;12345;C888;13.4;PAID
С ключом SecretKey подпись будет 39bdf94c6ebecd276f56e0515a728d41
Эту подпись важно проверять, чтобы убедиться, что уведомление вам присылает именно CoinyPay.
Закажите CoinyPay
Напишите нам для интеграции автоматических Facebook-платежей в ваш ресторан или интернет-магазин прямо сейчас
Журналист? Ознакомьтесь с нашим пресс-китом.
Разработчик? Посетите наш раздел для разработчиков.
Подключаете самостоятельно? Начните с инструкции.