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

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

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

1.1. Через SDK

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

Первый вариант подходит если в Вашем проекте уже используется С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 параметров:

  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 символов.
  5. extra (необязательный, максимальное количество свойств - 20, максимальная длина свойства и значения 100 символов) - ассоциативный массив с любыми дополнительными свойствами квитанции, которые будут видны на странице заказа в кабинете. Пример массива: [ ‘customer_name’ => ‘Johan’, ‘'customer_phone' => '+328 3423423', payment_method => cash]. В кабинете будет выглядеть следующим образом:

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

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

Если на стороне 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 255 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 255 characters Максимальная длина параметра "total_price" 255 символов
737 "total_price" parameter must be numeric Параметр "total_price" должен быть численным.
738 Max size of "custom_id" parameter is 255 characters Максимальная длина параметра "custom_id" 255 символов
739 "items" parameter must be an array Параметр “items” должен быть массивом
7310 Max size of "items" array is 999 Максимальная длина массива “items” 999 элементов
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 255 characters Максимальная длина свойства “item_id” в массиве “item” (внутри массива “items”) 255 символов
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 255 characters Максимальная длина свойства “item_price” в массиве “item” (внутри массива “items”) 255 символов
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 255 characters Максимальная длина свойства “item_amount” в массиве “item” (внутри массива “items”) 255 символов
7323 "extra" parameter can have max 20 elements Массив “extra” может содержать максимум 20 элементов
7324 Max size of "extra" item key is 255 characters Максимальная длина свойства в массиве “extra” - 255 символов
7325 Max size of "extra" item value is 255 characters Максимальная длина значения в массиве “extra” - 255 символов
7326 "extra" parameter must be an array Параметр “extra” должен быть массивом