Руководство по подключению интернет-магазина к системе Cryptexy

Для начала, в том месте, где в Вашем интернет-магазине, покупатель выбирает способ оплаты нужно добавить кнопку “Bitcoin accepted here”: Данная кнопка должна вести на скрипт, который будет взаимодействовать с Cryptexy API.

1. Взаимодействие с Cryptexy API

1.1. Через SDK

На текущий момент SDK (software development kit) доступен только для PHP. Для других языков следует использовать вариант без SDK (см. 1.2. часть).
SDK можно установить двумя способами:

• Composer (https://packagist.org/packages/cryptexy/cryptexy-sdk): composer require cryptexy/cryptexy-sdk
• Скачать репозиторий: https://bitbucket.org/GinGin/cryptexy-sdk/downloads/?tab=tags
  Слева в списке показаны версии, а справа ссылки для скачивания в определённом формате.

Первый вариант подходит если в Вашем проекте уже используется Сomposer, например если Вы используете такие PHP фреймворки, как Symfony или Laravel.

Если Вам неудобно использовать Composer, то можно воспользоваться вторым вариантом. В папке src находится файл с классом CryptexySDK - его нужно подключить через require (http://php.net/manual/ru/function.require.php) или use (http://php.net/manual/ru/language.namespaces.importing.php).

Следует учитывать, что используя второй вариант, для того чтобы обновить версию SDK, старую версию нужно будет заменить на новую, скачав её по выше указанной ссылке. При использование Composer, достаточно будет написать: composer update cryptexy/cryptexy-sdk.

После того, как класс подключен, можно создать его объект:

$cryptexySDK = new CryptexySDK(my_api_key)

1. customerEmail (обязательный, максимум 150 символов) - емайл покупателя. На этот емайл будет отправляться информация об изменении статуса квитанции. Следует учитывать, что Cryptexy системой будет проверена правильность написания емайла, т.е., например, валидным емайлом будет “example@gmail.com”, а не правильным - “example@gmail” или “example.com”.
2. totalPrice (обязательный, максимум 100 символов, должно быть численным) - цена квитанции в рублях - либо целое число, либо число с точкой с точностью до сотых. Число с большой точностью будет округлено до сотых. Пример правильных значений - 34212, 2333.47, 3453.4
3. customId (необязательный, максимум 100 символов) - в кабинете в списке заказов и на странице заказа, отмечается как “Доп. ID”, т.е. дополнительный ID. Благодаря этому параметру можно связать сгенерированную квитанцию с определенным заказом в Вашей системе.
4. items (необязательный) - массив товаров, которые покупает покупатель. Переданный список товаров будет отображён в кабинете на странице заказа. Каждый товар это ассоциативный массив, который состоит из следующих свойств (все - обязательны):
   • item_id - ID товара;
   • item_name - имя товара;
   • item_price - цена товара в рублях;
   • item_amount - количество товара.
   Максимальное количество товаров в массиве 150. Максимальная длина каждого значения свойства товара - 100 символов, кроме item_name - 255 символов.
5. extra (необязательный, максимальное количество свойств - 20, максимальная длина названия свойства 100 символов, максимальная длина значения 255 символов) - ассоциативный массив с любыми дополнительными свойствами квитанции, которые будут видны на странице заказа в кабинете. Пример массива: [ ‘customer_name’ => ‘Johan’, ‘'customer_phone' => '+328 3423423', payment_method => cash]. В кабинете будет выглядеть следующим образом:
6. comebackUrl (необязательный, максимальная длина 255 символов) - URL адрес, на который будет перекинут покупатель после нажатия кнопки “Обратно на сайт продавца” на странице квитанции. URL может содержать любые параметры, например, можно добавить ‘customId’: http://myshop.ru/comeback.php?custom_id=304
7. paidCallback (необязательный, максимальная длина 255 символов) - URL адрес, на который система Cryptexy пошлёт POST запрос (как форму) после того, как оплата квитанции будет подтверждена. URL может содержать любые параметры. POST запрос содержит следующие параметры:
   
   a) verification_code - Код верификации коллбэков, см. ниже.
   b) custom_id - "Доп. ID”
   c) code - Код квитанции
   d) created_at - Дата и время создания
   e) customer_email - E-mail покупателя
   f) totalPrice - Сумма в квитанции, руб.
   g) is_paid - Оплачена ли квитанция (всегда true)
   h) paid - Сумма оплаты, руб.
   i) deviation - Разница, руб.
   
   Ответ на запрос должен быть просто текст - ‘ok’ (без кавычек). Если ответ будет каким либо другим, то на указанный URL с интервалом 12 часов, будет посылаться повторный запрос, пока не будет получен ответ ‘ok’. Максимальное количество повторных запросов равняется пяти - 5.

Если всё прошло успешно, то метод generateInvoice вернёт объект класса stdClass, со следующими свойствами:

• message - сообщение о результате запроса;
• status - success (успех) или error (ошибка);
• code - код ответа (подробнее см. 2 часть);
• data - объект stdClass со свойством invoice_code. В случае ошибки (status: error), data будет пустым.
• invoice_code - код квитанции;
• verification_code - код верификации коллбэков. Для большей безопасности, в каждый URL коллбэк, в качестве параметра, система Cryptexy будет передавать код верификации, чтобы потом продавец мог бы удостоверится, что коллбэк вызывает именно Cryptexy.

Если на стороне API произошла ошибка, то будет возвращён null.

Таким образом, если метод generateInvoice вернул не null и status: “success” , можно перенаправить покупателя на страницу квитанции. Получить URL квитанции можно с помощью метода CryptexySDK::getInvoiceUrl, передав туда invoice_code из ответа API. Пример кода:

if ($invoice && $invoice->status =='success')
{
    return  $this->redirect($cryptexySDK->getInvoiceUrl($invoice->data->invoice_code));
}
else
{
 // ...
}

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

1.2. Без SDK

Прежде чем читать далее, пожалуйста, ознакомьтесь с 1.1. частью, так как там описан основной принцип работы с Cryptexy API.

Сгенерировать квитанцию можно и без SDK. Для этого достаточно послать обычный POST запрос с указанными в 1.1. часте параметрами на URL: http://cryptops.art/app_dev.php/api/v1/invoice/generate

Пример запроса со всеми доступными параметрами приведён ниже:

Следует обратить внимание, что используется PHP-ный вариант изображения индексных и ассоциативных массивов (http://php.net/manual/ru/language.types.array.php) т.е. с помощью квадратных скобок “[]” и символа “=>”.

Ответ будет получен в формате JSON:

{
   "message":"Invoice is generated successfully",
   "status":"success",
   "code":"31",
   "data":{
      "invoice_code":"67eb7176ea36bc63e21aa80ec446a80f"
   }
}

2. Коды ответа Cryptexy API

Каждый ответ от API содержит:

• message - что произошло.
• status - error/success.
• code - код ответа.
• data - данные, ради которых посылался запрос. Поле будет пустым в случае ошибки.

Код ошибки всегда начинается с 7, а код успеха с 3.

2.1. Авторизация

2.2. Генерация квитанции

Все ошибки начинаются с 73* кода