Язык:
< Главная

Финансовые операции

Данный раздел описывает функции и структуры данных использующиеся при совершении финансовых операций в платежной платформе Velespay.

Запросы осуществляется с помощью GET/POST/PUT/DELETE запросов в кодировке UTF-8 к URL https://api.velespay.com/v1/money/<Название функции>.

Ответ от сервера является JSON объект.


Успешный ответ будет содержать поле result.
Пример:

{
	"result": [Массив или Объект]
}

Ошибка будет содержать поле error с кодом и сообщением.
Пример:

{
	"error": {
		"code": цифровой код ошибки,
		"message": текстовое сообщение об ошибке
	}
}

Аутентификация

Все запросы к API должны содержать заголовки для авторизации, параметры передаются в формате JSON и кодировке UTF-8. Каждый запрос вашего сервера к API Velespay должен содержать следующие заголовки и информацию аутентификации:

Заголовки запроса:

Content-Type: application/json; charset=UTF-8
Authorization: Basic Base64(<Ваш Ключ>:<hash всех передаваемых параметров>)

Вы должны создать hash с помощью следующего алгоритма:

  • Сгенерировать URL-кодированную строку из всех передаваемых параметров запроса;
  • Декодировать URL-кодированную строку;
  • Сгенерировать хеш-код на основе <Вашего Пароля>, используя метод HMAC с алгоритмом sha512;
  • <Ваш Ключ от API>:<Полученный результат hash> закодировать в формат Base64;

Пример на PHP: 

$url = "https://api.velespay.com/v1/money/<Название функции>";
$http_method = "POST";//HTTP метод запроса - GET/POST/PUT/DELETE
$user_agent = "Velespay API Client";//Ваш юзер клиент

$accessKey = "Ваш Ключ от API";
$secretKey = "Ваш Пароль от API";

$params = array(
	"lang"=>"en"
);

$headers[] = 'Accept: application/json';
$headers[] = 'Content-Type: application/json; charset=UTF-8';
$headers[] = 'Accept-Encoding: UTF-8';

$hash = hash_hmac('sha512', urldecode(http_build_query($params)), $secretKey);
$headers[] = 'Authorization: Basic '.base64_encode($accessKey.':'. $hash);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_FAILONERROR, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERAGENT, $user_agent);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $http_method);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
curl_close($ch);

$res = json_decode($res);

Проверка баланса кошелька

HTTP метод: GET

Функция: Balance

URL: https://api.velespay.com/v1/money/Balance

Доступные необязательные параметры запроса: 

lang = Код языка ISO 639-1 (для вывода ошибок), по умолчанию en
currency = Цифровой код валюты по стандарту ISO 4217

Результат выполнения успешного запроса = структура данных Balance.

Выставление счета-фактуры покупателю

Создать счет на оплату для покупателя и автоматически отправить на электронную почту пользователя, от которого вы хотите получить платеж. Пользователь сможет получить информацию о вас, заплатить по выставленному счету, отложить или отклонить оплату.

HTTP метод: GET (Валидация выставления счета-фактуры)

HTTP метод: POST (Выставить счет-фактуру)

Функция: Send_Invoice

URL: https://api.velespay.com/v1/money/Send_Invoice

Параметры запроса: 

invoice = номер счета-фактуры, в соответствии с вашей системой ведения учета, максимум 100 символов (обязательный)

buyer = покупатель. Телефон: +6531588872, E-mail: [email protected], Wallet: VM123456789, ID Account: 123456789 (обязательный)
	ВАЖНО!!! Если счет-фактура выставляется клиенту который не зарегистрирован в системе Velespay, указывается E-mail.

currency = Цифровой или строковый код валюты по стандарту ISO 4217, Пример: 840 или USD (обязательный)

who_fee = кто платит комиссию true - продавец, false - покупатель (по умолчанию) (необязательный)

fiscalization = Объект с параметрами фискализации (необязательный)
	fiscalization.enabled = Печатать фискальные чеки, true - да (по умолчанию), false - нет.
	
	fiscalization.cashbox = Идентификатор вашей кассы для отправки чеков, если у вас имеется несколько касс.
	
	fiscalization.agent = Признак агента, true - Включает, false - Выключает параметры агента в настройках кассы. Параметры агента должны быть заполнены в настройках кассы. По умолчанию в настройках кассы можно отключить операции агента и при такой операции передать true, тем самым активировать.
ВАЖНО!!! Отправка в ККМ / Онлайн-кассу осуществляется после настройки и подключения Услуги «чеки».

internal = false - Если счет-фактура выставляется клиенту который не зарегистрирован в системе Velespay, true - клиент зарегистрирован в системе Velespay (необязательный)

lifetime = до какого времени возможно оплатить счет, по умолчанию 15 дней. (необязательный)
	Формат: yyyy-mm-dd'T'HH:MM:ss'Z'
	Часовой пояс: UTC

description = Дополнительная информация которую увидит покупатель (необязательный)

payment_method = массив с кодами электронных валют с помощью которых возможно оплатить счет-фактуру (необязательный)
	поле ps_code по ссылке.	Если не указано, то оплатить покупатель сможет любым доступным способом

buyer_lang = Код языка ISO 639-1 (На каком языке отправлять сообщения покупателю или отображать страницу оплаты), по умолчанию en (необязательный)

lang = Код языка ISO 639-1 (для вывода ошибок), по умолчанию en (необязательный)

send_email = false - без отправки сообщения на почту плательщика, true с отправкой (по умолчанию) (необязательный)

product = массив объектов в котором перечисляется Товары/Услуги за которые выставляется счет-фактура (обязательный)
	product.0.name = Наименование Товара или Услуги (обязательный)

	product.0.quantity = Количество, по умолчанию 1 (необязательный)

	product.0.price = Конечная цена за единицу Товара/Услуги, включая НДС и другие сборы (обязательный)
		ВАЖНО!!! Должен быть положительным числом.

	product.0.img = Полный URL к небольшой картинке в формате JPG, JPEG, GIF, BMP, PNG (необязательный)

	product.0.vat = Объект  (необязательный)
	product.0.vat.code = Код ставки НДС (обязательный)
		none - Без НДС
		composite - Составная/Комбинированная
		vat0 - НДС по ставке 0%
		vat10 - НДС по ставке 10%
		vat20 - НДС по ставке 20%
		vat110 - НДС по ставке 10/110 (расчетная ставка)
		vat120 - НДС по ставке 20/120 (расчетная ставка)
		vatчисло - иная ставка. Пример:
			1) vat18 = 18%
			2) vat118 = 18/118 (расчетная ставка)
	product.0.vat.value = Сумма налога позиции, рассчитывается автоматически (необязательный)
		ВАЖНО!!! Если указан product.0.vat.code = composite - параметр обязательный

	product.0.measure = Единица измерения количества предмета расчета, по умолчанию piece (необязательный)
		piece - поштучно или единицы
		gram - Грамм
		kilogram - Килограмм
		ton - Тонна
		centimeter - Сантиметр
		decimeter - Дециметр
		meter - Метр
		square_centimeter - Квадратный сантиметр
		square_decimeter - Квадратный дециметр
		square_meter - Квадратный метр
		milliliter - Миллилитр
		liter - Литр
		cubic_meter - Кубический метр
		kilowatt_hour - Киловатт час
		gigacalorie - Гигакалория
		day - Сутки (день)
		hour - Час
		minute - Минута
		second - Секунда
		kilobyte - Килобайт
		megabyte - Мегабайт
		gigabyte - Гигабайт
		terabyte - Терабайт
		other - иная единица измерения

	product.0.payment_method = Признак способа расчета, по умолчанию full_payment (необязательный)
		full_prepayment - Полная предоплата
		partial_prepayment - Частичная предоплата
		advance - Аванс
		full_payment - Полный расчет
		partial_payment - Частичный расчет и кредит
		credit - Кредит
		credit_payment - Оплата кредита

	product.0.payment_object = Признак предмета расчета, по умолчанию payment (необязательный)
		commodity - Товар
		excise - Подакцизный товар
		job - Работа
		service - Услуга
		gambling_bet - Ставка в азартной игре
		gambling_prize - Выигрыш в азартной игре
		lottery - Лотерейный билет
		lottery_prize - Выигрыш в лотерею
		intellectual_activity - Результаты интеллектуальной деятельности
		payment - Платеж
		agent_commission - Агентское вознаграждение
		property_right - Имущественные права
		non_operating_gain - Внереализационный доход
		insurance_premium - Страховой сбор
		sales_tax - Торговый сбор
		resort_fee - Курортный сбор
		composite - Несколько вариантов
		another - Другое

	product.0.excise = Сумма акциза, по умолчанию 0 (необязательный)
	
	product.0.country = Трехзначный код страны происхождения товара, например: 156 = Китай или 643 = Россия (необязательный)
	
	product.0.declaration_number = Номер таможенной декларации. Не более 32 символов (необязательный)
	
	product.0.marking_code = Маркировка товара (необязательный)
		ВАЖНО!!! передаётся в том виде, как она напечатана на упаковке товара.
		Параметр является обязательным только для тех магазинов, которые продают товары подлежащие обязательной маркировке.
		Код маркировки расположен на упаковке товара, рядом со штрих-кодом или в виде QR-кода.
	
sci = Объект с данными редиректов и уведомлений для переопределения значений в личном кабинете (необязательный)
	sci.success = объект содержащий информацию куда перенаправлять плательщика после удачной оплаты (необязательный)
		sci.success.url = URL для редиректа (необязательный)
		sci.success.method = Метод передачи параметров - POST или GET (по умолчанию) (необязательный)
	sci.fail = объект содержащий информацию куда перенаправлять плательщика после неудачной оплаты (необязательный)
		sci.fail.url = URL для редиректа (необязательный)
		sci.fail.method = Метод передачи параметров - POST или GET (по умолчанию) (необязательный)
	sci.ipn = объект содержащий информацию куда отправлять уведомление об удачной оплате (необязательный)
		sci.ipn.url = URL для уведомления (необязательный)
		sci.ipn.method = Метод передачи параметров - POST или GET (по умолчанию) (необязательный)

ВАЖНО!!! При использовании Услуги «чеки» (Решение «чеки», Решение «Кассовое», Решение «Облачное») параметры product передаются на фискализацию (в ваш ККМ или онлайн-кассу) в таком виде как они поступили от вас.
Информация передается в ОФД, налоговую, а также отображается в фискальном чеке покупателя.
Будьте внимательны, ответственность за неправильную передачу параметров несете ВЫ.

Результат выполнения успешного запроса = структура данных TxnInfo.

Отмена выставленного счета-фактуры

HTTP метод: DELETE

Функция: Send_Invoice

URL: https://api.velespay.com/v1/money/Send_Invoice/<ID транзакции>

Необязательные параметры запроса: 

lang = Код языка ISO 639-1 (для вывода ошибок), по умолчанию en

Результат выполнения успешного запроса = структура данных TxnInfo.

Внутрисистемный перевод

Отправка или проверка отправки (предварительный просмотр) средств внутри системы Velespay другому пользователю или между своими кошельками.

HTTP метод: GET (Валидация перевода)

HTTP метод: POST (Отправка средств)

Функция: Send_Money

URL: https://api.velespay.com/v1/money/Send_Money

Обязательные параметры запроса: 

receiver = получатель. Телефон: +6531588872, E-mail: [email protected], Wallet: VM123456789, ID Account: 123456789
currency = Цифровой код валюты по стандарту ISO 4217
amount = сумма перевода

Необязательные параметры запроса: 

who_fee = кто платит комиссию false = отправитель, true = получатель
invoice = идентифицирующий номер, в соответствии с вашей системой ведения учета, максимум 100 символов
period = если перевод с кодом протекции, период протекции: от 1 до 30 дней, по умолчанию 0
code = если перевод с кодом протекции, код активации перевода, максимум 20 символов
description = Примечание к транзакции
lang = Код языка ISO 639-1 (для вывода ошибок), по умолчанию en

Результат выполнения успешного запроса = структура данных TxnInfo.

Активация платежа

Если внутрисистемный перевод был отправлен с кодом протекции

HTTP метод: PUT

Функция: Send_Money

URL: https://api.velespay.com/v1/money/Send_Money/<ID транзакции>

Обязательные параметры запроса: 

code = код активации перевода, максимум 20 символов

Необязательные параметры запроса: 

lang = Код языка ISO 639-1 (для вывода ошибок), по умолчанию en

Результат выполнения успешного запроса = структура данных TxnInfo.

Отмена платежа

Если внутрисистемный перевод был отправлен с кодом протекции

HTTP метод: DELETE

Функция: Send_Money

URL: https://api.velespay.com/v1/money/Send_Money/<ID транзакции>

Необязательные параметры запроса: 

lang = Код языка ISO 639-1 (для вывода ошибок), по умолчанию en

Результат выполнения успешного запроса = структура данных TxnInfo.

Внутрисистемный обмен валюты.

HTTP метод: GET (Валидация обмена валюты)

HTTP метод: POST (Обмен валюты)

Функция: Currency_Exchange

URL: https://api.velespay.com/v1/money/Currency_Exchange

Обязательные параметры запроса: 

currency_from = Отдаваемая валюта (Цифровой код валюты по стандарту ISO 4217)
currency_to = Получаемая валюта (Цифровой код валюты по стандарту ISO 4217)
action = Принимает два значение:
	sell - продажа amount (будет продана сумма в валюте currency_from)
	buy - покупка amount (будет куплена сумма в валюте currency_to)
amount = сумма

Необязательные параметры запроса: 

lang = Код языка ISO 639-1 (для вывода ошибок), по умолчанию en

Результат выполнения успешного запроса GET = структура данных CurrencyExchange.

Результат выполнения успешного запроса POST = структура данных TxnInfo.

Вывод средств

Вывод средств в стороннюю платежную систему, на банковский счет или дебетовую карту.

HTTP метод: POST

Функция: Withdraw

URL: https://api.velespay.com/v1/money/Withdraw

Обязательные параметры запроса: 

ps = код электронной валюты. поле ps_code по ссылке https://api.velespay.com/v1/info/Withdraw?visible=true
amount = сумма
в зависимости от выбранной валюты:
	payee = объект с данными получателя, зависит от платежной системы/банка и т.д.
	payee[wallet] = Номер кошелька или номер дебетовой карты (Пример: VM123xxx, U123xxx, P123xxx и т.п.)
	payee[email] = Если в сторонней ПС доступна отправка средств по E-mail значит используется данное поле
	payee[phone] = Если в сторонней ПС доступна отправка средств по номеру телефона значит используется данное поле (международный формат, Пример: +6531588872)
		для вывода в Qiwi используется данное поле
	payee[account] = Если указан данный параметр, он будет преобразован в payee[wallet] или payee[email] или payee[phone]

Необязательные параметры запроса: 

invoice = идентифицирующий номер, в соответствии с вашей системой ведения учета, максимум 100 символов
description = Комментарий который увидит сотрудник финансового отдела. Используется в основном для банковских переводов
who_fee = true - комиссия с получаемой суммы, false - комиссия с отправляемой суммы
send_email = false - без отправки уведомлений, true с отправкой
lang = Код языка ISO 639-1 (для вывода ошибок), по умолчанию en

Параметры вывода с помощью SWIFT/SEPA (на банковский счет): 

Получатель:
	payee['beneficiary_number'] = Номер паспорта, для компаний регистрационный номер
	payee['beneficiary_name'] = Полное имя на английском, как в паспорте или регистрационных документах компании
	payee['beneficiary_name_cyr'] = Имя на кириллице, как в паспорте (ФИО) или регистрационных документах компании (если вывод в страны СНГ)
	payee['beneficiary_inn'] = ИНН/ИИН/БИН
	payee['beneficiary_kpp'] = КПП для компаний в России
	payee['beneficiary_country'] = Страна (гражданство)
	payee['beneficiary_address'] = Улица, дом, квартира (адрес регистрации)
	payee['beneficiary_city'] = Город (населенный пункт)
	payee['beneficiary_region'] = Регион (область, край, республика, и т.п.)
	payee['beneficiary_zip_code'] = Индекс
Банковский счет:
	payee['bank_currency'] = Валюта счета
	payee['bank_iban'] = IBAN/Номер счета
	payee['bank_code_type'] = Тип национального банковского кода, по умолчанию 1 (SWIFT), список смотрите в "Информационные данные" -> "Банковские коды"
	payee['bank_code'] = Код банка или SWIFT код банка
	payee['bank_name'] = Название банка
	payee['bank_country'] = Страна банка
	payee['bank_city'] = Город банка
	payee['bank_address'] = Адрес филиала
	payee['bank_bik'] = БИК для Российских банков
	payee['bank_correspondent_account'] = Корреспондентский счет для Российских банков
	payee['bank_sort_code'] = Сорт код или Рутинг номер

Параметры отправки денежного перевода с помощью системы CONTACT (наличные): 

Получатель:
	payee['lang'] = Код языка ISO 639-1 (На каком языке отправлять сообщение/уведомление получателю перевода), по умолчанию en
	payee[email] = E-mail получателя перевода. Будет отправляться уведомление с данными перевода.
	payee[phone] = Телефон получателя перевода, необязательное
	payee[contact_trnPickupPoint] = Код точки выплаты, 4 символа.
	payee[contact_bName] = ФАМИЛИЯ получателя перевода.
	payee[contact_bLastName] = ИМЯ получателя перевода.
	payee[contact_bSurName] = Отчество получателя перевода, необязательное
	
Некоторые страны/точки имеют особенности выплаты перевода и требуют дополнительные параметры:
	payee[contact_bCity] = Город получателя на английском.
	payee[contact_bAddress] = Полный адрес получателя на английском.

Результат выполнения успешного запроса = структура данных TxnInfo.

Отмена вывода средств

Отменить возможно только если заявка не завершена или не принята в обработку

HTTP метод: DELETE

Функция: Withdraw

URL: https://api.velespay.com/v1/money/Withdraw/<ID транзакции>

Необязательные параметры запроса: 

lang = Код языка ISO 639-1 (для вывода ошибок), по умолчанию en

Результат выполнения успешного запроса = структура данных TxnInfo.

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

Получение списка операций или поиск определенной операции

HTTP метод: GET

Функция: Transaction_History

URL: https://api.velespay.com/v1/money/Transaction_History

или

URL: https://api.velespay.com/v1/money/Transaction_History/<ID транзакции>

Необязательные параметры запроса: 

receiver = получатель. Телефон: +6531588872, E-mail: [email protected], Wallet: VM123456789, ID Account: 123456789
type = значение или массив типа транзакций (цифровой), список смотрите в "Информационные данные" -> "Типы транзакций"
status = значение или массив статуса транзакций (цифровой), список смотрите в "Информационные данные" -> "Статусы транзакций"
currency = значение или массив валют (Цифровой код валюты по стандарту ISO 4217), список смотрите в "Информационные данные" -> "Валюты"
begin = Начальная дата для выборки транзакций (формат yyyy-mm-dd, пример: 2015-01-10, или UTC формат)
end = Конечная дата для выборки транзакций (формат yyyy-mm-dd, пример: 2015-01-10, или UTC формат)
page_size = Количество возвращенных транзакций на страницу. Максимальное значение - 50.
page_number = Страница, по умолчанию 1
view = all (все), in (входящие), out (исходящие)
lang = Код языка ISO 639-1 (для вывода ошибок), по умолчанию en

Результат выполнения успешного запроса = структура данных HistoryInfo.