API

API Документация

  1. Описание запросов
  2. Формат ответа
  3. Методы
    1. Приём платежа
    2. Приём платежа host-to-host
    3. Токенизация
    4. Создание выплаты
    5. Выплата с обменом
    6. Получение статуса ордера
    7. История транзакций
    8. Балансы
    9. Способы оплаты
    10. Курсы обменов
  4. Callbacks
  5. Примеры статусов/ ошибок
    1. Возможные статусы ордеров
    2. Примеры ошибок
  6. Terminal-API Partners
  7. Общая структура
  8. Типы запросов от терминала
    1. Проверка пользователя
    2. Создание заказа
    3. Подтверждение заказа
    4. Отмена заказа (not use)
  9. Цифровая подпись
    1. Примеры формирования
  10. Тестовая система

Описание запросов 

Для использования API нужно отправлять POST запрос на URL
https://api2.crosspay.net/api/v2/{method{/method}} с обязательными заголовками:


'Accept: application/json',
'Content-Type: application/json',
'Authorization: ' {public_key},
'Signature: ' {signature_for_data},

Параметры запроса передаются в формате JSON

Заголовок Authorization должен содержать публичный ключ пользователя (public_key) для авторизации запроса.

Цифровая подпись для заголовка Signature формируется методом HMAC на основе

алгоритма “sha256” з использованием секретного ключа пользователя

(secret_key).

 

Пример генерации подписи:


$json_data = json_encode($data);
$signature = hash_hmac("sha256", $json_data, $secret_key);

Ответ API также содержит заголовок Signature с цифровой подписью для верификации.

Пример полного запроса через curl с последующим отделением в ответе заголовка с подписью и проверкой подписи:


// Create a callback to capture HTTP headers for the response
$rheaders = [];
$headerCallback = function ($curl, $header_line) use (&$rheaders) {
	// Ignore the HTTP request line (HTTP/1.1 200 OK)
	if (strpos($header_line, ":") === false) {
		return strlen($header_line);
	}
	list($key, $value) = explode(":", trim($header_line), 2);
	$rheaders[strtolower(trim($key))] = trim($value);
	return strlen($header_line);
};

$json_data = json_encode($data);

$config = [
	CURLOPT_USERAGENT => 'CrossPay user',
	CURLOPT_URL => ' https://api2.crosspay.net/api/v2/balances', 
	CURLOPT_RETURNTRANSFER => true,
	CURLOPT_HEADER => true,
	CURLOPT_HEADERFUNCTION => $headerCallback,
	CURLOPT_HTTPHEADER => [
			'Accept: application/json',
			'Content-Type: application/json',
			'Authorization: '. $public_key,
			'Signature: '. hash_hmac("sha256", $json_data, $secret_key),
	],
	CURLOPT_AUTOREFERER => true,
	CURLOPT_POSTFIELDS => json_encode($data),
];

$curl = curl_init();
curl_setopt_array($curl, $config);

$response = curl_exec($curl);
$header_size = curl_getinfo($curl, CURLINFO_HEADER_SIZE);
/// get response body without headers
$response = substr($response, $header_size);

curl_close($curl);

/// do verification of $response
$response_signature = $rheaders['signature'];
$check_signature = hash_hmac("sha256", $response, $secret_key);

If (  hash_equals($check_signature, $response_signature) ){

   /// response is verified
   $response = json_decode($response, true);

}

Формат ответа

В ответ на запрос отправляется JSON строка со статусом запроса (поле status – успешно или не успешно принят запрос в API), описанием ошибки в случае не успешного запроса (message), а также данными результата (data) в случае успешной обработки запроса:


{
   "status": "success", // success || error
   "message": String,
   "data": {
	  "field_1": " value_1",
	  "field_2": " value_2",
	...
   }
}

Для запросов создания ордеров на оплату строка data также будет содержать поле status со статусом данного ордера (см. раздел Возможные статусы ордеров ).

new-guide

Приём платежа (payin)

Для приема оплаты с кредитной карты используется метод order/payin (https://api2.crosspay.net/api/v2/order/payin). Метод создает заявку на прием оплаты и выдает ссылку (URL) на iframe оплаты.

Запрос


{
   "order_id": String,
   "currency": String,
   "wallet_type": String,
   "amount": float,
   "payway": String,
   "card_system": String, //Необязательный
   "description": String, //Необязательный
   "callback": String, //Необязательный
   "success_url": String, //Необязательный
   "fail_url": String, //Необязательный
   "client_ip": String,
   "client_email": String,
   "client_user_agent": String, //Необязательный
   "client_id": String,
   "is_test": Boolean, //Необязательный
   "trusted_user": int, // 0 | 1 // Необязательный
}

Описание параметров:

order_id* – Внутренний номер заказа пользователя
currency* – Валюта заказа (uah, usd, …)
wallet_type* – Тип кошелька (p2p, ecom, a2c, …), по умолчанию «0». Для получения типов кошельков см. раздел Балансы (balances)
amount* – Сумма платежа, которая будет списана с карты
payway* – Способ приема платежей (см. раздел Способы оплаты (payways) )
card_system – В случае способа приема платежей card возможно ограничить прием оплаты одним типом карт: visa, mastercard, maestro, discover, diners_club, amex, jcb
description – описание платежа
callback – url адрес для сервер-сервер сообщения о результате транзакции
success_url – url адрес для переадресации клиента в случае успеха
fail_url – url адрес для переадресации клиента в случае ошибки
client_ip – IP клиента, совершающего платеж
client_email – Email клиента, совершающего платеж
client_user_agent – user agent клиента, совершающего платеж
client_id – ID клиента в системе мерчанта
is_test – Добавьте это поле со значением true или 1, если нужно совершить тестовый платеж.
trusted_user – Добавьте это поле со значением 1, если нужно принять платеж доверенного пользователя.

Ответ


{
   "status": "success",
   "message": "",
   "data": [{
      "order_id": String,
      "order_uuid": String,
      "order_type": String,
      "payway": String,
      "currency_from": String,
      "wallet_from_type": String,
      "wallet_from": String,
      "amount_from": float, 
      "currency_to": String,
      "wallet_to_type": String,
      "wallet_to": String,
      "amount_to": float,
      "currency_fee": String,
      "amount_fee": float,
      "exchange_rate": float,
      "status": String,
      "message": String,
      "error_code": integer,
      "created": String, // Y-m-d H:i:s
      "updated": String, // Y-m-d H:i:s
      "pay_url": String,
   },
   {…}
   ]
}

order_id – Внутренний номер заказа пользователя
order_uuid – Уникальный идентификатор платежа в системе CrossPay
order_type – Тип ордера: payin, payout
payway – Способ приема платежей (см. раздел Способы оплаты (payways) )
currency_from – Валюта исходящего кошелька (uah, usd, …)
wallet_from_type – Тип исходящего кошелька (p2p, ecom, a2c, …), по умолчанию «0». Для получения типов кошельков см. раздел Балансы (balances)
wallet_from – Номер исходящего кошелька: номер карты при оплате кредитной картой
amount_from – Сумма платежа, которая будет списана
currency_to – Валюта входящего кошелька (uah, usd, …)
wallet_to_type – Тип входящего кошелька (p2p, ecom, a2c, …), по умолчанию «0»
wallet_to – Номер входящего кошелька: номер внутреннего кошелька пользователя в CrossPay
amount_to – Сумма платежа, которая будет получена
currency_fee – Валюта комиссии
amount_fee – Сумма комиссии
exchange_rate – Курс обмена (для ордеров payin и payout не используется, значение «0»)
status – Статус ордера (см. раздел Возможные статусы ордеров )
message – Информация об ошибке, если ордер завершен с ошибкой
error_code – Код ошибки (см. Примеры ошибок)
created – Дата создания ордера
updated – Дата обновления ордера в системе CrossPay
pay_url – Ссылка (URL) на iframe оплаты

Приём платежа host-to-host (payin)

Для кошельков типа ecom доступен метод приема оплаты с карты host-to-host, когда
мерчант получает самостоятельно платежные данные пользователя. В этом случае
дополнительно к данным описанным на предыдущем шаге (payin), указываются
следующие данные в запросе:

Запрос:


{
   "wallet": String,
   "expire_month": String, // format MM
   "expire_year": String, // format YYYY
   "cvv": String,
}

Описание параметров:
wallet – Номер карты
expire_month – Месяц окончания срока действия карты
expire_year – Год окончания срока действия карты
cvv – CVV/CVC код

Платеж проводится с 3DS авторизацией методом redirect, либо методом отправки формы (post).

Если в ответе присутствует параметр pay_url, необходимо выполнить редирект пользователя на этот URL для завершения авторизации. После авторизации пользователь будет возвращен на страницу CrossPay с результатом платежа и перенаправлен на страницу мерчанта, указанную в запросе payin (“success_url”, “fail_url”).

Если в ответе присутствует параметр acs_url, необходимо отправить форму (post) на этот URL и результат авторизации вернуть на CrossPay методом обновления ордера. Ниже описаны используемые поля для формы и обработка результата 3DS.

Ответ c “acs_url”:


{
   "status": "success",
   "message": "",
   "data": [{
      "order_id": String,
      "order_uuid": String,
      ...
      "acs_url": String,
      "pareq": String,
      "md": float,
   }]
}

Описание параметров:

acs_url – URL для прохождения авторизации пользователем. На этот URL нужно
отправить форму (post) с полями PaReq, MD, и TermUrl (URL мерчанта для возврата
пользователя после авторизации)
pareq – параметр для отправки под именем PaReq внутри формы на acs_url
md – параметр для отправки под именем MD внутри формы на acs_url

После прохождения авторизации пользователь запросом будет возвращен обратно
мерчанту на TermUrl с передачей параметра PaRes. Это значение нужно отправить методом order/update
(https://api2.crosspay.net/api/v2/order/update) для обновления ордера со следующими параметрами:

Запрос:


{
   "status": "success",
   "message": "",
   "data": [{
      "order_id": String,
      "order_uuid": String,
      ...
      "acs_url": String,
      "pareq": String,
      "md": float,
   }]
}

Описание параметров:

order_uuid – Уникальный идентификатор платежа в системе CrossPay
md – Параметр 3DS авторизации, полученный от CrossPay
pares – значение PaRes, полученное на TermUrl

Ответ будет содержать статус обновления ( success или error ) и данные ордера,
описанные в Прием платежа (payin). После обновления ордера нужно сделать
следующий запрос для проверки статуса ордера (см. Получение статуса ордера (status)).
Статусы “completed”, “rejected” являются финальными.

Токенизация

Для упрощения приема оплаты от постоянных клиентов может использоваться токенизация карт. Схема работы:

  • первый запрос к API order/payin выполняется с дополнительным параметром для токенизации, платеж клиента проходит по обычному процессу
  • в случае успешного платежа создается токен карты
  • токен карты необходимо запросить по методу API order/cardtoken
  • в последующих платежах в запросе API order/payin передается токен карты
  • для завершения платежа от клиента необходим ввод CVV/CVC, а также прохождение 3DS

Запрос на создание токена, дополнительно к параметрам API order/payin:


{
   ..., // параметры, указанные в методе payin
   "attributes": {
      "request_card_token": true // type boolean
   }
}

Описание параметров:
attributes – Массив атрибутов
request_card_token – параметр со значением true (тип boolean) для создания токена карты

Получение токена, запрос к API order/cardtoken ((https://api2.crosspay.net/api/v2/order/cardtoken)):


{
   "order_id": String,
   ---OR---
   "order_uuid": String,
}

Используется один из двух параметров:

order_id – Внутренний номер заказа пользователя
order_uuid – Уникальный идентификатор платежа в системе CrossPay

Ответ:


{
   "status": "success",
   "message": "",
   "data": {
      "order_id": String,
      "order_uuid": String,
      "card_number": String,
      "card_token": String
   }
}

Описание параметров:
order_id – Внутренний номер заказа пользователя
order_uuid – Уникальный идентификатор платежа в системе CrossPay
card_number – Маска номера карты
card_token – Токен карты

Использование токена, дополнительно к параметрам API order/payin:


{
   ..., // параметры, указанные в методе payin
   "card_token": String
}

Описание параметров:
card_token – Токен карты.
В случае платежа host-to-host в запросе необходим также параметр cvv (параметры wallet, expire_month, expire_year не указываются)

Создание выплаты (payout)

Для создания выплаты на кредитную карту используется метод order/payout (https://api2.crosspay.net/api/v2/order/payout).

Запрос:


{
   "order_id": String,
   "currency": String,
   "wallet_type": String,
   "wallet": String,
   "amount": float,
   "payway": String,
   "description": String, //Необязательный
   "callback": String, //Необязательный
   "is_test": Boolean, //Необязательный
}

Описание параметров:

order_id* – Внутренний номер заказа пользователя
currency* – Валюта заказа (uah, usd, …)
wallet_type* – Тип кошелька (p2p, ecom, a2c, …), по умолчанию «0». Для получения типов кошельков см. раздел Балансы (balances)
wallet * – Номер кошелька (номер кредитной карты для uah и payway = card)
amount* – Сумма платежа, которая будет списана
payway* – Способ приема платежей (см. раздел Способы оплаты (payways) )
description – описание платежа
callback – url адрес для сервер-сервер сообщения о результате транзакции
is_test – Добавьте это поле со значением true или 1, если нужно совершить тестовый платеж.

Формат Ответа аналогичен методу payin, но в ответе отсутствует поле pay_url

После получения ответа нужно сделать следующий запрос для проверки статуса ордера (см. Получение статуса ордера (status)), либо дождаться уведомления на callback URL (если был указан в запросе). Статусы ордера “completed”, “rejected” являются финальными.

Выплата с обменом (exchange_payout)

Если валюта кошелька отличается от валюты карты, можно проводить выплату с автоматической конвертацией (обменом) валюты с помощью метода order/exchange_payout (https://api2.crosspay.net/api/v2/order/exchange_payout
).

Параметры запроса должны содержать данные валюты (currency_from) и типа исходящего кошелька (wallet_from_type), а также валюты карты (currency_to) и типа кошелька для отправки платежа в валюте карты (wallet_to_type, обычно равен wallet_from_type).

Должна быть указана сумма выплаты в валюте исходящего кошелька (amount_from), или сумма выплаты для зачисления на карту (amount_to). На основе указанной суммы рассчитывается вторая сумма, и пара значений amount_from amount_to возвращаются в ответе метода вместе с курсом обмена (поле exchange_rate). Для расчета amount_to на базе amount_from, или amount_from
на базе amount_to используется текущий курс обмена в системе CrossPay (метод получения exchange_rates).

Запрос:


{
   "order_id": String,
   "currency_from": String,
   "wallet_from_type": String,
   "currency_to": String,
   "wallet_to_type": String,
   "wallet": String,
   "amount_from": float, // должен быть один из amount_from amount_to
   "amount_to": float, // должен быть один из amount_from amount_to
   "payway": String,
   "description": String, //Необязательный
   "callback": String, //Необязательный
   "is_test": Boolean, //Необязательный
}

Описание параметров:

order_id* – Внутренний номер заказа пользователя
currency_from* – Валюта исходящего кошелька (uah, usd, …)
wallet_from_type* – Тип исходящего кошелька (p2p, ecom, a2c, …), по умолчанию «0». Для получения типов кошельков см. раздел Балансы (balances)
currency_to* – Валюта кошелька (карты), на который совершается платеж (uah, usd, …)
wallet_to_type* – Тип кошелька для отправки платежа в валюте карты (p2p, ecom, a2c, …), по умолчанию «0» (обычно равен wallet_from_type).
wallet * – Номер кошелька (номер кредитной карты для uah и payway = card)
amount_from – Сумма платежа, которая будет списана с кошелька
amount_to – Сумма платежа, которая будет отправлена на карту
payway* – Способ приема платежей (см. раздел Способы оплаты (payways) )
description – описание платежа
callback – url адрес для сервер-сервер сообщения о результате транзакции
is_test – Добавьте это поле со значением true или 1, если нужно совершить тестовый платеж.

Формат Ответа аналогичен методу payin, но в ответе отсутствует поле pay_url

После получения ответа нужно сделать следующий запрос для проверки статуса ордера (см. Получение статуса ордера (status)), либо дождаться уведомления на callback URL (если был указан в запросе). Статусы ордера “completed”, “rejected” являются финальными.

Получение статуса ордера (status)

Для проверки состояния ордера используется метод order/status (https://api2.crosspay.net/api/v2/order/status).

Запрос:


{
   "order_id": String,
   ---OR---
   "order_uuid": String,
}

Используется один из двух параметров:

order_id – Внутренний номер заказа пользователя
order_uuid – Уникальный идентификатор платежа в системе CrossPay

Ответ содержит в себе данные ордера и его статус в формате, описанном в разделе Прием платежа (payin).

История транзакций (transactions)

Список последних ордеров или ордеров в указанном диапазоне дат/времени можно получить методом transactions (https://api2.crosspay.net/api/v2/transactions).

Запрос:


{
   "date_from": String, //Необязательный
   "date_to": String, //Необязательный
   "limit": String, //Необязательный
}

Описание параметров:

date_from – Дата начала диапазона выборки в формате “Y-m-d H:i:s”
date_to – Дата окончания диапазона выборки в формате “Y-m-d H:i:s”
limit – Число записей в ответе (максимум 200)

Ответ содержит в себе данные ордера и его статус в формате, описанном в разделе Прием платежа (payin).

Балансы (balances)

Для получения балансов кошельков используется метод balances (https://api2.crosspay.net/api/v2/balances)

Запрос:


{}

Ответ:


{
   "status": "success",
   "data": {
         "{currency}": {
            "{wallet_type}": {
                    "wallet": String,
                    "amount": Float,
                    "amount_locked": Float,
                    "overdraft": Float, 
             },
          },
          {…}
   },
}

Описание параметров:

wallet – Номер внутреннего кошелька в системе CrossPay
amount – Сумма, доступная в кошельке
amount_locked – Заблокированные средства (зарезервированы для выполнения ордеров)
overdraft – Сумма овердрафта, которая была добавлена в amount, и должна быть погашена позже в соответствии с условиями овердрафта пользователя

Способы оплаты (payways)

Метод payways (https://api2.crosspay.net/api/v2/payways) позволяет получить доступные пользователю способы оплаты/выплаты, комиссию за проведение платежа, минимальную и максимальную сумму

Запрос:


{
   {}
}

Ответ:


{
   "status": "success",
   "data": {
       "payin": {
          "{currency}": {
            "{wallet_type}": {
               "{payway}": {
                    "limit_amount_min": Float,
                    "limit_amount_max": Float,
                    "limit_amount_day": Float,
                    "amount_fee": Float,
                    "percent_fee": Float, 
                },
             },
          },
          {…}
       },
       "payout": {[…]}
   },
}

Описание параметров:

limit_amount_min – Минимальная сумма для оплаты/выплаты
limit_amount_max – Максимальная сумма для оплаты/выплаты
limit_amount_day – Максимальная сумма для оплаты/выплаты на один кошелек в день
amount_fee – Фиксированная комиссия за совершение оплаты/выплаты (сумма)
percent_fee – Процент комиссии от суммы оплаты/выплаты

Курсы обменов (exchange_rates)

Метод exchange_rates (https://api2.crosspay.net/api/v2/exchange_rates) позволяет получить доступные пользователю курсы обмена валют, минимальную и максимальную сумму

Запрос:


{
   {}
}

Ответ:


{
   "status": "success",
   "data": {
       "{currency_from}": {
          "{wallet_from_type}": {
            "{currency_to}": {
               "{wallet_to_type}": {
                    "limit_amount_min": Float,
                    "limit_amount_max": Float,
                    "limit_amount_day": Float,
                    "rate": Float, 
                },
             },
          },
       },
       {…}
   },
}

Описание параметров:

currency_from – Валюта которую меняем (uah, usd, …)
wallet_from_type – Тип исходящего кошелька (p2p, ecom, a2c, …), по умолчанию «0». Для получения типов кошельков см. раздел Балансы (balances)
currency_to – Валюта на которую меняем (uah, usd, …)
wallet_to_type – Тип входящего кошелька (p2p, ecom, a2c, …), по умолчанию «0»
limit_amount_min – Минимальная сумма для обмена
limit_amount_max – Максимальная сумма для обмена
limit_amount_day – Максимальная сумма для обмена в день
rate – курс обмена из currency_from в currency_to, применяется по формуле amount_to = amount_from*rate

Callbacks

После смены статуса транзакции на callback URL, указанный при запросе payin|payout, отправляются данные ордера с новым статусом в формате:


{
   "status": "success",
   "message": "",
   "data": [{
      "order_id": String,
      "order_uuid": String,
      "order_type": String,
      "payway": String,
      "currency_from": String,
      "wallet_from_type": String,
      "wallet_from": String,
      "amount_from": float, 
      "currency_to": String,
      "wallet_to_type": String,
      "wallet_to": String,
      "amount_to": float,
      "currency_fee": String,
      "amount_fee": float,
      "exchange_rate": float,
      "status": String,
      "message": String,
      "error_code": integer,
      "created": String, // Y-m-d H:i:s
      "updated": String, // Y-m-d H:i:s
   }]
}

order_id – Внутренний номер заказа пользователя
order_uuid – Уникальный идентификатор платежа в системе CrossPay
order_type – Тип ордера: payin, payout
payway – Способ приема платежей (см. раздел Способы оплаты (payways) )
currency_from – Валюта исходящего кошелька (uah, usd, …)
wallet_from_type – Тип исходящего кошелька (p2p, ecom, a2c, …), по умолчанию «0». Для получения типов кошельков см. раздел Балансы (balances)
wallet_from – Номер исходящего кошелька: номер карты при оплате кредитной картой
amount_from – Сумма платежа, которая списана
currency_to – Валюта входящего кошелька (uah, usd, …)
wallet_to_type – Тип входящего кошелька (p2p, ecom, a2c, …), по умолчанию «0»
wallet_to – Номер входящего кошелька: номер внутреннего кошелька пользователя в CrossPay
amount_to – Сумма платежа, которая будет получена
currency_fee – Валюта комиссии
amount_fee – Сумма комиссии
exchange_rate – Курс обмена (для ордеров payin и payout не используется, значение «0»)
status – Статус ордера (см. раздел Возможные статусы ордеров )
message – Информация об ошибке, если ордер завершен с ошибкой
error_code – Код ошибки (см. Примеры ошибок)
created – Дата создания ордера
updated – Дата обновления ордера в системе CrossPay

Статусы «completed», «rejected», «canceled» являются финальными.

Статус 200 ответа мерчанта означает, что запрос успешно принят, иначе попытка отправки callback будет выполнена ещё два раза через 1 мин, потом через 30 мин, через 60 мин.

new-guide

Возможные статусы ордеров

Статус Описание
new Ордер создан и ожидает обработки
processing Ордер обрабатывается
completed Ордер успешно завершен
rejected В процессе выполнения заявки произошла ошибка на третьей стороне
canceled Ордер отменен пользователем, либо не завершен пользователем в установленное время

Примеры ошибок

Ошибка Описание
Requested method cannot be found Недоступный метод оплаты/выплаты
Order not found Ордер не найден
Invalid data format Некорректный формат данных в запросе
You do not have enough balance Недостаточно баланса у пользователя для совершения операции
Amount less than allowed Сумма меньше допустимой
An error occurred while creating the order Ошибка на этапе создания ордера
Service is not available Сервис не доступен
Invalid user key Неверный публичный ключ пользователя
Signature is not valid Неверная цифровая подпись в запросе

new-guide

Общая структура

Протокол взаимодействия реализован на основе интернет протокола HTTPS. Данные передаются в json-формате, используя метод POST.

Запрос:


{
  "method": string,
  "date": "yyyy-MM-dd HH:mm:ss",
  "terminal": string,
  "is_test": int,
  "partner_api_id": int,
  "data": {  },
  "sign":""
}

Описание параметров:

method – тип операции (список доступных операций приведен ниже)
date – время создания запроса(ответа)
terminal – название терминала, с которого будет производится оплата
is_test – флаг тестового запроса. Если 1, то запрос тестовый. Если 0, то боевой.
partner_api_id – Ваш партнерский ID в системе Fly-Pay Terminal
data – массив с данными операции
sign – подпись (см. раздел Формирование подписи)

Партнерский json-ответ:


{
  "status": "success",
  "data": { },
  "sign": ""
}

=== OR ===

{
  "status": "error",
  "message": string,
  "sign": ""
}

Описание параметров:

status – статус операции (принимает 2 значения success или error)
data – массив с ответными данными по операции
sign – подпись (см. раздел Формирование подписи)
message – Описание ошибки/отклонения операции

Типы запросов от терминала

Проверка пользователя

Выполняется для проверки пользователя на существование (если это требуется) и/или вхождение пользователя в черный список (если таков имеется).

Запрос:


{
  "method": "check",
  "date": "yyyy-MM-dd HH:mm:ss",
  "terminal": string,
  "is_test": int,
  "partner_api_id": int,
  "data": {
     "phone": string,
  },
  "sign":""
}

Описание параметров:

phone – номер телефона пользователя/клиента

ответ:


{
  "status": "success",
  "data": {
     "min_amount": float,
     "max_amount": float,
  },
  "sign": ""
}

Описание параметров:

min_amount – Минимальная сумма операции в грн (в формате NN.NN)
max_amount – Максимальная сумма операции в грн (в формате NN.NN)

Создание заказа

p>Выполняется во время ввода суммы пополнения в экране терминала.

Запрос:


{
  "method": "payment",
  "date": "yyyy-MM-dd HH:mm:ss",
  "terminal": string,
  "is_test": int,
  "partner_api_id": int,
  "data": {
     "phone": string,
     "order_id": int,
     "amount": float,
  },
  "sign":""
}

Описание параметров:

order_id – это наш уникальный идентификатор транзакции
amount – сумма платежа (в формате NN.NN)

Ответ:


{
  "status": "success",
  "data": {
     "payment_id": int,
     "amount": Float, 
     "currency": String,
  },
  "sign": ""
}

Описание параметров:

payment_id – номер платежа в вашей системе.
amount – Сумма грн, которая зашифрована в коде
currency – Валюта кода (всегда ГРН)

Подтверждение заказа

Выполняется после внесения пользователем средств в терминал.

Запрос:


{
  "method": "confirm",
  "date": "yyyy-MM-dd HH:mm:ss",
  "terminal": string,
  "is_test": int,
  "partner_api_id": int,
  "data": {
     "payment_id": int,
  },
  "sign":""
}

Описание параметров:

payment_id – это номер платежа в Вашей системе, полученный нами на операции payment

Ответ:


{
  "status": "success",
  "data": {
     "payment_code": String,
     "amount": Float, 
     "currency": String,
  },
  "sign": ""
}

Описание параметров:

payment_code – Код пополнения для вывода в Терминал (скорее всего на будущее эта функция) И/Или для отправки его в смс (если такая ф-ция оговорена заранее)
amount – Сумма грн, которая зашифрована в коде
currency – Валюта кода (всегда ГРН)

Отмена заказа (not use)

Выполняется при отмене платежа пользователем. В данный момент не используется!

Запрос:


{
  "method": "cancel",
  "date": "yyyy-MM-dd HH:mm:ss",
  "terminal": string,
  "is_test": int,
  "partner_api_id": int,
  "data": {
     "payment_id": int,
  },
  "sign":""
}

Описание параметров:

payment_id – это номер платежа в Вашей системе, полученный нами на операции payment

Ответ:


{
  "status": "success",
  "data": {  },
  "sign": ""
}

Описание параметров:

Цифровая подпись

Примеры формирования и проверки подписи на PHP

Генерация подписи:


$json_data = json_encode($data);

$sign = hash_hmac(
    "sha256", 
    $json_data, 
    "hT3yLbscbdksnY19bszUknSen63", 
    false
);

Верификация подписи:


$partner_sign = $data['sign']; //Отделяем полученную подпись
$data['sign'] = ''; //Подпись партнера делаем пустой

$data_without_sign = json_encode($data);

$sign = hash_hmac(   //генерируем нашу подпись
     "sha256", 
     $data_without_sign, 
     "hT3yLbscbdksnY19bszUknSen63", 
     false); 

$result = hash_equals($sign, $partner_sign); //результат сверки - boolean

Тестовая система

Для тестирования запросов используйте тест форму:

http://terminal.fly-pay.io/test_system/terminal