Руководство по подключению интернет-магазина к системе 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)В конструктор необходимо передать API key, который можно получить в кабинете: http://merchants.cryptexy.com/merchant_admin/settings во вкладке API Теперь можно сгенерировать квитанцию. Для этого следует использовать метод CryptexySDK::generateInvoice. Данный метод принимает 5 параметров:
- customerEmail (обязательный, максимум 150 символов) - емайл покупателя. На этот емайл будет отправляться информация об изменении статуса квитанции. Следует учитывать, что Cryptexy системой будет проверена правильность написания емайла, т.е., например, валидным емайлом будет “example@gmail.com”, а не правильным - “example@gmail” или “example.com”.
- totalPrice (обязательный, максимум 100 символов, должно быть численным) - цена квитанции в рублях - либо целое число, либо число с точкой с точностью до сотых. Число с большой точностью будет округлено до сотых. Пример правильных значений - 34212, 2333.47, 3453.4
- customId (необязательный, максимум 100 символов) - в кабинете в списке заказов и на странице заказа, отмечается как “Доп. ID”, т.е. дополнительный ID. Благодаря этому параметру можно связать сгенерированную квитанцию с определенным заказом в Вашей системе.
- items (необязательный) - массив товаров, которые покупает покупатель.
Переданный список товаров будет отображён в кабинете на странице заказа.
Каждый товар это ассоциативный массив, который состоит из следующих свойств (все - обязательны):
- item_id - ID товара;
- item_name - имя товара;
- item_price - цена товара в рублях;
- item_amount - количество товара.
-
extra (необязательный, максимальное количество свойств - 20, максимальная длина названия свойства 100 символов,
максимальная длина значения 255 символов) - ассоциативный массив с любыми дополнительными свойствами квитанции, которые будут видны на
странице заказа в кабинете. Пример массива: [ ‘customer_name’ => ‘Johan’, ‘'customer_phone' => '+328
3423423', payment_method => cash]. В кабинете будет выглядеть следующим образом:
- comebackUrl (необязательный, максимальная длина 255 символов) - URL адрес, на который будет перекинут покупатель после нажатия кнопки “Обратно на сайт продавца” на странице квитанции. URL может содержать любые параметры, например, можно добавить ‘customId’: http://myshop.ru/comeback.php?custom_id=304
- 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. Авторизация
Code | Message | Пояснение |
---|---|---|
71 | Authentication Required | Если запрашивается URL, который требует авторизации |
72 | An authentication failed | Если пользователь не найден по предоставленному API key |
74 | API is disabled for provided API key | Если API сервиса для пользователя выключен |
75 | API is currently disabled | Если API сервиса отключен для всех пользователей |
2.2. Генерация квитанции
Все ошибки начинаются с 73* кода
Code | Message | Пояснение |
---|---|---|
731 | "customer_email" parameter is required | Параметр "customer_email" является обязательным |
732 | Max size of "customer_email" is 150 characters | Максимальная длина параметра "customer_email" 255 символов |
733 | Invalid "customer_email" parameter. Email must be like "example@gmail.com" | Неправильное написание емайла. |
734 | "total_price" parameter is required | Параметр "total_price" является обязательным |
734 | "total_price" parameter is required | Параметр "total_price" является обязательным |
735 | "total_price" parameter value can't be empty | Параметр "total_price" не может быть пустым |
736 | Max size of "total_price" is 100 characters | Максимальная длина параметра "total_price" 100 символов |
737 | "total_price" parameter must be numeric | Параметр "total_price" должен быть численным. |
738 | Max size of "custom_id" parameter is 100 characters | Максимальная длина параметра "custom_id" 100 символов |
739 | "items" parameter must be an array | Параметр “items” должен быть массивом |
7310 | Max size of "items" array is 150 | Максимальная длина массива “items” 150 элементов |
7311 | Every "item" in "items" parameter requires "item_id" parameter | Каждый “item” в массиве “items” должен иметь свойство “item_id” |
7312 | Parameter "item_id" in "item" (inside "items" parameter) can't be empty | Свойство “item_id” в массиве “item” (внутри массива “items”) не может быть пустым |
7313 | Max size of "item_id" in "item" (inside "items" parameter) is 100 characters | Максимальная длина свойства “item_id” в массиве “item” (внутри массива “items”) 100 символов |
7314 | Every "item" in "items" parameter requires "item_name" parameter | Каждый “item” в массиве “items” должен иметь свойство “item_name” |
7315 | Parameter "item_name" in "item" (inside "items" parameter) can't be empty | Свойство “item_name” в массиве “item” (внутри массива “items”) не может быть пустым |
7316 | Max size of "item_name" in "item" (inside "items" parameter) is 255 characters | Максимальная длина свойства “item_name” в массиве “item” (внутри массива “items”) 255 |
7317 | Every "item" in "items" parameter requires "item_price" parameter | Каждый “item” в массиве “items” должен иметь свойство “item_price” |
7318 | Parameter "item_price" in "item" (inside "items" parameter) can't be empty | Свойство “item_price” в массиве “item” (внутри массива “items”) не может быть пустым |
7319 | Max size of "item_price" in "item" (inside "items" parameter) is 100 characters | Максимальная длина свойства “item_price” в массиве “item” (внутри массива “items”) 100 символов |
7320 | Every "item" in "items" parameter requires "item_amount" parameter | Каждый “item” в массиве “items” должен иметь свойство “item_amount” |
7321 | Parameter "item_amount" in "item" (inside "items" parameter) can't be empty | Свойство “item_amount” в массиве “item” (внутри массива “items”) не может быть пустым |
7322 | Max size of "item_amount" in "item" (inside "items" parameter) is 100 characters | Максимальная длина свойства “item_amount” в массиве “item” (внутри массива “items”) 100 символов |
7323 | "extra" parameter can have max 20 elements | Массив “extra” может содержать максимум 20 элементов |
7324 | Max size of "extra" item key is 100 characters | Максимальная длина свойства в массиве “extra” - 100 символов |
7325 | Max size of "extra" item value is 255 characters | Максимальная длина значения в массиве “extra” - 255 символов |
7326 | "extra" parameter must be an array | Параметр “extra” должен быть массивом |
7327 | Max size of "comeback_url" parameter is 255 characters | Максимальная длина значения параметра “comeback_url” - 255 символов |
7328 | Max size of "paid_callback" parameter is 255 characters | Максимальная длина значения параметра “paid_callback” - 255 символов |