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

Оглавление

Описание API

API предназначен для обеспечения взаимодействия производителей услуг с программно-техническим комплексом «Экспресс Платежи». Конфиденциальность передаваемых данных обеспечивается протоколом не менее TLS 1.2. Аутентификация производителя услуг осуществляется по уникальному API-ключу (токену). Целостность передаваемых данных (защита от MITM-атак) обеспечивается с помощью цифровой подписи алгоритмом HMAC-SHA1, который описан в стандарте RFC 2104. Дополнительная защита выполняется путем разграничения доступа ip-адресам программного комплекса производителя услуг.

Взаимодействие производителей услуг с программно-техническим комплексом «Экспресс Платежи» осуществляется на клиент-серверной технологии RESTful. Производитель услуг выступает в роли клиента, отправляет HTTP-запросы на сервер API. Возможно использование методов GET, POST, DELETE в HTTP-запросе. Данные передаются в кодировке UTF-8. В ответ на HTTP-запрос сервер отправляет HTTP-ответ клиенту в JSON-формате.

Формат запроса

Во всех запросах передаются обязательные параметры:

  • {version} – версия API;
  • token={token} – API-ключ (токен) доступа к серверу, который задается в личном кабинете;
  • signature={hash} – цифровая подпись запроса, которая формируется на основании секретного слова (задается в личном кабинете) и передаваемых данных. Данное поле является опциональным.
  • Параметр token должен передаваться в строке запроса. Входные параметры должны передаваться в URL encoded виде.

Возможные коды валют:

  • 933 – BYN;
  • 978 – EUR;
  • 840 – USD;
  • 643 – RUB (в международных расчётах);

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

Любой ответ от сервера представлен в JSON-формате. В случае успешного выполнения запроса возвращается необходимый набор ключей и значений, предназначенный для конкретного ответа на запрос.

Пример ответа при успешном выполнении операции получения списка счетов:
{"Items":[{
        "InvoiceNo":7,
        "AccountNo":"70",
        "Status":1,
        "Created":"20150101120000",
        "Expiration":"20150201",
        "Amount":100000.0,
        "Currency":933
    },{
        "InvoiceNo":8,
        "AccountNo":"80",
        "Status":3,
        "Created":"20150201120000",
        "Expiration":"20150301",
        "Amount":110000.0,
        "Currency":933
    }
]}

В случае выполнения операции с ошибкой возвращается JSON-узел Error, содержащий:

  • Code – код ошибки выполнения операции;
  • Msg – сообщение об ошибке;
  • MsgCode – код сообщения об ошибке.

Пример ответа при ошибки выполнения запроса представлен ниже:
"Error": {
	"Code": 500,
	"Msg": "Отменить можно только тот счет, который находится в статусе \"Ожидание\"",
	"MsgCode": 5000000
}
Возможные коды ошибок о выполнении операций:
  • 400 – некорректный запрос;
  • 404 – ресурс не найден;
  • 500 – внутренняя ошибка севера.

Возможные коды сообщений выполнения операции:
  • 4000003 – Некорректный запрос
  • 4040001 – Платеж не найден
  • 4040002 – Счет на оплату не найден
  • 5000000 – Внутренняя ошибка по умолчанию

Включение API

Для работы программного комплекса производителя услуг через API «Экспресс Платежи» необходимо в личном кабинете разрешить использование API.

Для этого необходимо в личном кабинете:
  1. Перейти в раздел настройки (пункт меню “Настройка”);
  2. Перейти на вкладку “Услуги”
  3. В списке услуг для нужной услуги перейти к настройкам API;
  4. Разрешить использование API для услуги (см. рисунок).
Разрешение использования API для услуги

Разрешение использования API для услуги

Система ЕРИП

Просмотр списка счетов по параметрам

Метод возвращает список выставленных счетов. Если входные параметры не заданы, то метод возвращает выставленные счета на последние 30 дней.

Метод: GET

URL: https://api.express-pay.by/v1/invoices?token={Token}


Входные параметры

Поле Тип Описание
Token String(32) API-ключ производителя услуг
From String(8) - yyyyMMdd Дата оплаты с – начало периода
To String(8) - yyyyMMdd Дата оплаты по – конец периода
AccountNo String(30) Номер лицевого счета.
Status Integer Статус счета на оплату:
  • 1 - Ожидает оплату
  • 2 - Просрочен
  • 3 - Оплачен
  • 4 - Оплачен частично
  • 5 - Отменен
  • 6 - Оплачен с помощью банковской карты
  • 7 - Платеж возращен

- обязательные поля

Выходные параметры

Поле Тип Описание
InvoiceNo Integer Номер счета на оплату
AccountNo String(30) Номер лицевого счета
Status Integer Статус счета на оплату:
  • 1 - Ожидает оплату
  • 2 - Просрочен
  • 3 - Оплачен
  • 4 - Оплачен частично
  • 5 - Отменен
  • 6 - Оплачен с помощью банковской карты
  • 7 - Платеж возращен
Created String(14) Дата выставления счета. Формат - yyyyMMddHHmmss
Expiration String(12) Дата истечения срока действия выставления счета на оплату.
Форматы – yyyyMMdd, yyyyMMddHHmm
Amount Decimal(19,2) Сумма счета на оплату
Currency Integer Код валюты
CardInvoiceNo Integer Номер счета по карте (не обязательное. Возвращается только в случае, если выполнялась оплата счета по карте.)

Пример


public static async Task<string> GetListInvoiceAsync(string token, bool useSignature, bool isTest, string secretWord)
{
	string url;
	if (!isTest)
	{
		url = "https://api.express-pay.by/v1/invoices?";
	}
	else
	{
		url = "https://sandbox-api.express-pay.by/v1/invoices?";
	}

	var requestParams = new Dictionary<string, string>
	{
		{"Token", token},
		//Параметры фильтра являются опциональными, по умолчанию возврщает значения за последние 30 дней
		{"AccountNo", ""},
		{"From", "" },
		{"To", "" },
		{"Status", "" }
	};

	if (useSignature)
	{
		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
	}

	foreach (var rp in requestParams)
	{
		url += string.Format("&{0}={1}", rp.Key, rp.Value);
	}

	var response = await client.GetAsync(url);

	var responseString = await response.Content.ReadAsStringAsync();

	return responseString;
}

public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
{
	StringBuilder sb = new StringBuilder();
	Encoding HashEncoding = Encoding.UTF8;
	foreach (var item in requestParams)
		sb.Append(item.Value);

	HMACSHA1 hmac;
	if (string.IsNullOrWhiteSpace(secretWord))
	{
		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
		// что нам не подходит
		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
	}
	else
	{
		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
	}

	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
	var result = new StringBuilder();
	foreach (var item in hash) result.Append(item.ToString("X2"));

	return result.ToString();
}
                    

Выставление счета

Метод выставляет новый счет.

Метод: POST

URL: https://api.express-pay.by/v1/invoices?token={Token}


Входные параметры

Поле Тип Описание
Token String(32) API-ключ производителя услуг
AccountNo String(30) Номер лицевого счета. Разрешенные символы: цифры, буквы(латиница, кириллица), тире(-), точка(.), правый слэш(/), левый слэш(\), двоеточие(:) и нижнее подчеркивание(_). Для способа оплаты EPOS длинна - 22 символа.
Amount Decimal(19,2) Сумма счета на оплату.
Разделителем дробной и целой части является символ запятой
Currency Integer Код валюты
Expiration String(12) Дата истечения срока действия выставления счета на оплату.
Форматы – yyyyMMdd, yyyyMMddHHmm.
Данный параметр не может одновременно использоваться с параметром LifeTime.
Info String(1024) Назначение платежа
Surname String(30) Фамилия
FirstName String(30) Имя
Patronymic String(30) Отчество
City String(30) Город
Street String(30) Улица
House String(10) Дом
Building String(10) Корпус
Apartment String(10) Квартира
IsNameEditable Integer При оплате разрешено изменять ФИО плательщика
0 – нет, 1 – да
IsAddressEditable Integer При оплате разрешено изменять адрес плательщика
0 – нет, 1 – да
IsAmountEditable Integer При оплате разрешено изменять сумму оплаты
0 – нет, 1 – да
EmailNotification String(255) Адрес электронной почты, на который будет
отправлено уведомление о выставлении счета
SmsPhone String(13) Номер мобильного телефона, на который будет
отправлено SMS-сообщение о выставлении счета
ReturnInvoiceUrl Integer Вернуть в ответе публичную ссылку на счет
0 – нет, 1 – да (0 - по умолчанию)
LifeTime Unsigned Integer Время действия счета в секундах с момента получения сервером API запроса.
Данный параметр не может одновременно использоваться с параметром Expiration.

- обязательные поля

При выставлении счетов с 1-го июля 2016 года необходимо передавать новый код валюты 933 (BYN). Выставление счетов со старым кодом валюты 974 (BYR) будет завершаться с ошибкой.


Выходные параметры

Поле Тип Описание
InvoiceNo Integer Номер счета
InvoiceUrl String(64) Публичная ссылка на счет. Отсутствует, если входной параметр ReturnInvoiceUrl установлен в 0 (нет) или не задан

Пример


public static async Task <string> AddInvoiceAsync(string token, bool useSignature, bool isTest, string secretWord)
{
	string url;
	if (!isTest)
	{
		url = string.Format("https://api.express-pay.by/v1/invoices?token={0}", token);
	}
	else
	{
		url = string.Format("https://sandbox-api.express-pay.by/v1/invoices?token={0}", token);
	}

	var requestParams = new Dictionary<string, string>
	{
		{"Token", token},
		{"AccountNo", "123"},
		{"Amount", "123,01" },
		{"Currency", "933" },
		{"Expiration", "20210321" },
		{"Info", "Оплата счёта" },
		{"Surname", "Иванов" },
		{"FirstName", "Иван" },
		{"Patronymic", "Иванович"},
		{"City", "Город"},
		{"Street", "Улица"},
		{"House", "Дом"},
		{"Building", "Корпус"},
		{"Apartment", "Квартира"},
		{"IsNameEditable", "0"},
		{"IsAddressEditable", "0"},
		{"IsAmountEditable", "0"},
		{"EmailNotification", "example@example.com"},
		{"SmsPhone", "+375291234567"},
		{"ReturnInvoiceUrl", "0"}
	};

	if (useSignature)
	{
		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
	}

	var content = new FormUrlEncodedContent(requestParams);

	var response = await client.PostAsync(url, content);

	var responseString = await response.Content.ReadAsStringAsync();

	return responseString;

}

public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
{
	StringBuilder sb = new StringBuilder();
	Encoding HashEncoding = Encoding.UTF8;

	// Удаляем из запроса номер телефона т.к. он не учавствует 
	// в формировании цифровой подписи
	requestParams.Remove("SmsPhone");

	foreach (var item in requestParams)
		sb.Append(item.Value);

	HMACSHA1 hmac;
	if (string.IsNullOrWhiteSpace(secretWord))
	{
		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
		// что нам не подходит
		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
	}
	else
	{
		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
	}

	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
	var result = new StringBuilder();
	foreach (var item in hash) result.Append(item.ToString("X2"));

	return result.ToString();
}
						

Изменение счета

Метод изменяет уже выставленный счет.

Метод: PUT

URL: https://api.express-pay.by/v1/invoices?token={Token}


Входные параметры

Поле Тип Описание
Token String(32) API-ключ производителя услуг
InvoiceId Integer Номер счета который был получен при выставление счета(InvoiceNo).
Amount Decimal(19,2) Сумма счета на оплату.
Разделителем дробной и целой части является символ запятой
Currency Integer Код валюты
Expiration String(12) Дата истечения срока действия выставления счета на оплату.
Форматы – yyyyMMdd, yyyyMMddHHmm.
Info String(1024) Назначение платежа
Surname String(30) Фамилия
FirstName String(30) Имя
Patronymic String(30) Отчество
City String(30) Город
Street String(30) Улица
House String(10) Дом
Building String(10) Корпус
Apartment String(10) Квартира
IsNameEditable Integer При оплате разрешено изменять ФИО плательщика
0 – нет, 1 – да
IsAddressEditable Integer При оплате разрешено изменять адрес плательщика
0 – нет, 1 – да
IsAmountEditable Integer При оплате разрешено изменять сумму оплаты
0 – нет, 1 – да
EmailNotification String(255) Адрес электронной почты, на который будет
отправлено уведомление о выставлении счета
SmsPhone String(13) Номер мобильного телефона, на который будет
отправлено SMS-сообщение о выставлении счета

- обязательные поля

При выставлении счетов с 1-го июля 2016 года необходимо передавать новый код валюты 933 (BYN). Выставление счетов со старым кодом валюты 974 (BYR) будет завершаться с ошибкой.


Пример


public static async Task <string> UpdateInvoiceAsync(string token, bool useSignature, bool isTest, string secretWord)
{
	string url;
	if (!isTest)
	{
		url = string.Format("https://api.express-pay.by/v1/invoices?token={0}", token);
	}
	else
	{
		url = string.Format("https://sandbox-api.express-pay.by/v1/invoices?token={0}", token);
	}

	var requestParams = new Dictionary<string, string>
	{
		{"Token", token},
		{"InvoiceId", 123},
		{"Amount", "123,01" },
		{"Currency", "933" },
		{"Expiration", "20210321" },
		{"Info", "Оплата счёта" },
		{"Surname", "Иванов" },
		{"FirstName", "Иван" },
		{"Patronymic", "Иванович"},
		{"City", "Город"},
		{"Street", "Улица"},
		{"House", "Дом"},
		{"Building", "Корпус"},
		{"Apartment", "Квартира"},
		{"IsNameEditable", "0"},
		{"IsAddressEditable", "0"},
		{"IsAmountEditable", "0"},
		{"EmailNotification", "example@example.com"},
		{"SmsPhone", "+375291234567"}
	};

	if (useSignature)
	{
		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
	}

	var content = new FormUrlEncodedContent(requestParams);

	var response = await client.PutAsync(url, content);

	var responseString = await response.Content.ReadAsStringAsync();

	return responseString;

}

public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
{
	StringBuilder sb = new StringBuilder();
	Encoding HashEncoding = Encoding.UTF8;

	// Удаляем из запроса номер телефона т.к. он не учавствует 
	// в формировании цифровой подписи
	requestParams.Remove("SmsPhone");

	foreach (var item in requestParams)
		sb.Append(item.Value);

	HMACSHA1 hmac;
	if (string.IsNullOrWhiteSpace(secretWord))
	{
		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
		// что нам не подходит
		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
	}
	else
	{
		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
	}

	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
	var result = new StringBuilder();
	foreach (var item in hash) result.Append(item.ToString("X2"));

	return result.ToString();
}
						

Детальная информация о счете

Метод возвращает детальную информацию о существующем счете.

Метод: GET

URL: https://api.express-pay.by/v1/invoices/{InvoiceNo}?token={Token}


Входные параметры

Поле Тип Описание
Token String(32) API-ключ производителя услуг
InvoiceNo Integer Номер счета на оплату
ReturnInvoiceUrl Integer Вернуть в ответе публичную ссылку на счет
0 – нет, 1 – да (0 - по умолчанию)

- обязательные поля

Выходные параметры

Поле Тип Описание
AccountNo String(30) Номер лицевого счета
Status Integer Статус счета на оплату:
  • 1 - Ожидает оплату
  • 2 - Просрочен
  • 3 - Оплачен
  • 4 - Оплачен частично
  • 5 - Отменен
  • 6 - Оплачен с помощью банковской карты
  • 7 - Платеж возращен
Created String(14) Дата/Время выставления счета. Формат - yyyyMMddHHmmss
Expiration String(12) Дата истечения срока действия выставления счета на оплату.
Форматы – yyyyMMdd, yyyyMMddHHmm
Paymented String(14) Дата/Время оплаты счета. Формат - yyyyMMddHHmmss
Amount Decimal(19,2) Сумма счета на оплату
Currency Integer Код валюты
Info String(1024) Назначение платежа
Surname String(30) Фамилия
FirstName String(30) Имя
Patronymic String(30) Отчество
City String(30) Город
Street String(30) Улица
House String(10) Дом
Building String(10) Корпус
Apartment String(10) Квартира
IsNameEditable Integer При оплате разрешено изменять ФИО плательщика 0 – нет, 1 – да
IsAddressEditable Integer При оплате разрешено изменять адрес плательщика 0 – нет, 1 – да
IsAmountEditable Integer При оплате разрешено изменять сумму оплаты 0 – нет, 1 – да
InvoiceUrl String(64) Публичная ссылка на счет. Отсутствует, если входной параметр ReturnInvoiceUrl установлен в 0 (нет) или не задан

Пример


public static async Task<string> GetInvoiceDetailAsync(string invoiceNo, string token, bool useSignature, bool isTest, string secretWord)
{
	string url;
	if (!isTest)
	{
		url = string.Format("https://api.express-pay.by/v1/invoices/{0}?", invoiceNo);
	}
	else
	{
		url = string.Format("https://sandbox-api.express-pay.by/v1/invoices/{0}?", invoiceNo);
	}

	var requestParams = new Dictionary<string, string>
	{
		{"Token", token},
		{"InvoiceNo", invoiceNo},
		{"ReturnInvoiceUrl", "" }
	};

	if (useSignature)
	{
		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
	}

	foreach (var rp in requestParams)
	{
		url += string.Format("&{0}={1}", rp.Key, rp.Value);
	}

	var response = await client.GetAsync(url);

	var responseString = await response.Content.ReadAsStringAsync();

	return responseString;
}

public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
{
	StringBuilder sb = new StringBuilder();
	Encoding HashEncoding = Encoding.UTF8;
	foreach (var item in requestParams)
		sb.Append(item.Value);

	HMACSHA1 hmac;
	if (string.IsNullOrWhiteSpace(secretWord))
	{
		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
		// что нам не подходит
		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
	}
	else
	{
		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
	}

	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
	var result = new StringBuilder();
	foreach (var item in hash) result.Append(item.ToString("X2"));

	return result.ToString();
}
						

Статус счета

Метод возвращает текущий статус счета.

Метод: GET

URL: https://api.express-pay.by/v1/invoices/{InvoiceNo}/status?token={Token}


Входные параметры

Поле Тип Описание
Token String(32) API-ключ производителя услуг
InvoiceNo Integer Номер счета на оплату

- обязательные поля

Выходные параметры

Поле Тип Описание
Status Integer Статус счета на оплату:
  • 1 - Ожидает оплату
  • 2 - Просрочен
  • 3 - Оплачен
  • 4 - Оплачен частично
  • 5 - Отменен
  • 6 - Оплачен с помощью банковской карты
  • 7 - Платеж возращен

Пример


public static async Task<string> GetInvoiceStatusAsync(string invoiceNo, string token, bool useSignature, bool isTest, string secretWord)
{
	string url;
	if (!isTest)
	{
		url = string.Format("https://api.express-pay.by/v1/invoices/{0}/status?", invoiceNo);
	}
	else
	{
		url = string.Format("https://sandbox-api.express-pay.by/v1/invoices/{0}/status?", invoiceNo);
	}

	var requestParams = new Dictionary<string, string>
	{
		{"Token", token},
		{"InvoiceNo", invoiceNo}
	};

	if (useSignature)
	{
		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
	}

	foreach (var rp in requestParams)
	{
		url += string.Format("&{0}={1}", rp.Key, rp.Value);
	}

	var response = await client.GetAsync(url);

	var responseString = await response.Content.ReadAsStringAsync();

	return responseString;
}

public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
{
	StringBuilder sb = new StringBuilder();
	Encoding HashEncoding = Encoding.UTF8;
	foreach (var item in requestParams)
		sb.Append(item.Value);

	HMACSHA1 hmac;
	if (string.IsNullOrWhiteSpace(secretWord))
	{
		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
		// что нам не подходит
		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
	}
	else
	{
		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
	}

	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
	var result = new StringBuilder();
	foreach (var item in hash) result.Append(item.ToString("X2"));

	return result.ToString();
}
							

Отменить счет

Метод отменят счет к оплате. Операция возможна только для счетов со статусом “Ожидает оплату”.

Метод: DELETE

URL: https://api.express-pay.by/v1/invoices/{InvoiceNo}?token={Token}


Входные параметры

Поле Тип Описание
Token String(32) API-ключ производителя услуг
InvoiceNo Integer Номер счета на оплату

- обязательные поля

Пример


public static async Task<string> CancelInvoiceAsync(string invoiceNo, string token, bool useSignature, bool isTest, string secretWord)
{
	string url;
	if (!isTest)
	{
		url = string.Format("https://api.express-pay.by/v1/invoices/{0}?", invoiceNo);
	}
	else
	{
		url = string.Format("https://sandbox-api.express-pay.by/v1/invoices/{0}?", invoiceNo);
	}

	var requestParams = new Dictionary<string, string>
	{
		{"Token", token},
		{"InvoiceNo", invoiceNo},
	};

	if (useSignature)
	{
		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
	}

	foreach (var rp in requestParams)
	{
		url += string.Format("&{0}={1}", rp.Key, rp.Value);
	}

	var response = await client.DeleteAsync(url);

	var responseString = await response.Content.ReadAsStringAsync();

	return responseString;
}

public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
{
	StringBuilder sb = new StringBuilder();
	Encoding HashEncoding = Encoding.UTF8;
	foreach (var item in requestParams)
		sb.Append(item.Value);

	HMACSHA1 hmac;
	if (string.IsNullOrWhiteSpace(secretWord))
	{
		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
		// что нам не подходит
		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
	}
	else
	{
		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
	}

	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
	var result = new StringBuilder();
	foreach (var item in hash) result.Append(item.ToString("X2"));

	return result.ToString();
}
						

Генерация QR-кода для счета

Метод возвращает ссылку для оплаты в формате QR-кода

Метод: GET

URL: https://api.express-pay.by/v1/qrcode/getqrcode/?token={Token}&invoiceId={InvoiceId}


Входные параметры

Поле Тип Описание
Token String(32) API-ключ производителя услуг
InvoiceId Integer Идентификатор счета
ViewType String Тип возвращаемого значения. Принимает два параметра:
  1. base64 - возвращает изображение в формате base64
  2. text - возвращает ссылку
ImageWidth Integer Ширина qr-кода
ImageHeight Integer Высота qr-кода

- обязательные поля

Выходные параметры

Поле Тип Описание
QrCodeBody String QR-код счета

Пример


public static async Task<string> GetQrCodeAsync(string token, bool useSignature, bool isTest, string secretWord)
{
	string url;
	if (!isTest)
	{
		url = "https://api.express-pay.by/v1/qrcode/getqrcode/?";
	}
	else
	{
		url = "https://sandbox-api.express-pay.by/v1/qrcode/getqrcode/?";
	}

	var requestParams = new Dictionary<string, string>
	{
		{"Token", token},
		{"InvoiceId", "100"},
		{"ViewType", "base64"},
		{"ImageWidth", "" },
		{"ImageHeight", "" }
	};

	if (useSignature)
	{
		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
	}

	foreach (var rp in requestParams)
	{
		url += string.Format("&{0}={1}", rp.Key, rp.Value);
	}

	var response = await client.GetAsync(url);

	var responseString = await response.Content.ReadAsStringAsync();

	return responseString;
}

public static string ComputeSignature(Dictionaryg<string, string> requestParams, string secretWord)
{
	StringBuilder sb = new StringBuilder();
	Encoding HashEncoding = Encoding.UTF8;
	foreach (var item in requestParams)
		sb.Append(item.Value);

	HMACSHA1 hmac;
	if (string.IsNullOrWhiteSpace(secretWord))
	{
		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
		// что нам не подходит
		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
	}
	else
	{
		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
	}

	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
	var result = new StringBuilder();
	foreach (var item in hash) result.Append(item.ToString("X2"));

	return result.ToString();
}
							

Генерация QR-кода для лицевого счета

Метод возвращает ссылку для оплаты в формате QR-кода

Метод: GET

URL: https://api.express-pay.by/v1/qrcode/getqrcodebyaccountnumber/?token={Token}&accountNumber={AccountNumber}&amount={amount}&imageHeight={imageHeight}&imageWidth={imageWidth}&viewType={viewType}


Входные параметры

Поле Тип Описание
Token String(32) API-ключ производителя услуг
AccountNumber Integer Лицевой счет
Amount Decimal Сумма
ViewType String Тип возвращаемого значения. Принимает два параметра:
  1. base64 - возвращает изображение в формате base64
  2. text - возвращает ссылку
ImageWidth Integer Ширина qr-кода
ImageHeight Integer Высота qr-кода

- обязательные поля

Выходные параметры

Поле Тип Описание
QrCodeBody String QR-код счета

Пример


public static async Task<string> GetQrCodeByAccountNumberAsync(string token, bool useSignature, bool isTest, string secretWord)
            {
            	string url;
            	if (!isTest)
            	{
            		url = "https://api.express-pay.by/v1/qrcode/getqrcodebyaccountnumber/?";
            	}
            	else
            	{
            		url = "https://sandbox-api.express-pay.by/v1/qrcode/getqrcodebyaccountnumber/?";
            	}
            
            	var requestParams = new Dictionary<string, string>
            	{
            		{"Token", token},
            		{"AccountNumber", "100"},
                        {"Amount", 25,00},
            		{"ViewType", "base64"},
            		{"ImageWidth", "" },
            		{"ImageHeight", "" }
            	};
            
            	if (useSignature)
            	{
            		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
            	}
            
            	foreach (var rp in requestParams)
            	{
            		url += string.Format("&{0}={1}", rp.Key, rp.Value);
            	}
            
            	var response = await client.GetAsync(url);
            
            	var responseString = await response.Content.ReadAsStringAsync();
            
            	return responseString;
            }
            
            public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
            {
            	StringBuilder sb = new StringBuilder();
            	Encoding HashEncoding = Encoding.UTF8;
            	foreach (var item in requestParams)
            		sb.Append(item.Value);
            
            	HMACSHA1 hmac;
            	if (string.IsNullOrWhiteSpace(secretWord))
            	{
            		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
            		// что нам не подходит
            		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
            	}
            	else
            	{
            		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
            	}
            
            	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
            	var result = new StringBuilder();
            	foreach (var item in hash) result.Append(item.ToString("X2"));
            
            	return result.ToString();
            }
            							

Интернет-эквайринг

Выставление счета по карте

Метод выставляет новый счет для оплаты через банковскую карту.

Метод: POST

URL: https://api.express-pay.by/v1/cardinvoices?token={Token}


Входные параметры

Поле Тип Описание
Token String(32) API-ключ производителя услуг
AccountNo String(30) Номер лицевого счета. Для способа оплаты EPOS длинна - 22 символа. Является уникальным значением.
Expiration String(8) Дата истечения срока действия выставленного счета на оплату. Формат - yyyyMMdd
Amount Decimal(19,2) Сумма счета на оплату. Сумма счета должна быть не менее 1,00 BYN.
Разделителем дробной и целой части является символ запятой
Currency Integer Код валюты
Info String(1024) Назначение платежа
ReturnUrl String(512) Адрес для перенаправления пользователя в случае успешной оплаты
FailUrl String(512) Адрес для перенаправления пользователя в случае неуспешной оплаты
Language String(2) Язык в кодировке ISO 639-1. Если не указан, будет использован язык по умолчанию
SessionTimeoutSecs Integer Продолжительность сессии в секундах.
В случае если параметр не задан, будет использовано значение 1200 секунд (20 минут).
Если в запросе присутствует параметр ExpirationDate, то значение параметра SessionTimeoutSecs не учитывается.
Значение SessionTimeoutSecs должно находится в пределах от 60 до 1200 сек (1-20 мин).
ExpirationDate String(32) Время жизни заказа. Формат yyyyMMddHHmmss. Если этот параметр не передаётся в запросе, то для определения времени жизни сессии используется SessionTimeoutSecs.
ReturnInvoiceUrl Integer Вернуть в ответе публичную ссылку на счет
0 – нет, 1 – да (0 - по умолчанию)

- обязательные поля

Выходные параметры

Поле Тип Описание
CardInvoiceNo Integer Номер счета по карте
InvoiceUrl String(64) Публичная ссылка на счет. Отсутствует, если входной параметр ReturnInvoiceUrl установлен в 0 (нет) или задан
ErrorCode Integer Номер ошибки. Отсутствует, если ошибки нет
ErrorMessage String(512) Сообщение об ошибке. Отсутствует, если ошибки нет

Пример


public static async Task <string> AddCardInvoiceAsync(string token, bool useSignature, bool isTest, string secretWord)
{
	string url;
	if (!isTest)
	{
		url = string.Format("https://api.express-pay.by/v1/cardinvoices?token={0}", token);
	}
	else
	{
		url = string.Format("https://sandbox-api.express-pay.by/v1/cardinvoices?token={0}", token);
	}

	var requestParams = new Dictionary<string, string>
	{
		{"Token", token},
		{"AccountNo", "123"},
		{"Expiration", "20210321" },
		{"Amount", "123,01" },
		{"Currency", "933" },
		{"Info", "Оплата счёта" },
		{"ReturnUrl", "-" },
		{"FailUrl", "-" },
		{"Language", "ru" },
		{"SessionTimeoutSecs", "1200" },
		{"ExpirationDate", "1200" },
		{"ReturnInvoiceUrl", "0"}
	};

	if (useSignature)
	{
		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
	}

	var content = new FormUrlEncodedContent(requestParams);

	var response = await client.PostAsync(url, content);

	var responseString = await response.Content.ReadAsStringAsync();

	return responseString;

}

public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
{
	StringBuilder sb = new StringBuilder();
	Encoding HashEncoding = Encoding.UTF8;
	
	foreach (var item in requestParams)
		sb.Append(item.Value);

	HMACSHA1 hmac;
	if (string.IsNullOrWhiteSpace(secretWord))
	{
		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
		// что нам не подходит
		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
	}
	else
	{
		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
	}

	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
	var result = new StringBuilder();
	foreach (var item in hash) result.Append(item.ToString("X2"));

	return result.ToString();
}
							

Форма оплаты

Метод инициирует оплату по банковской карте и возвращает адрес для формы ввода данных банковской карты. Для оплаты выставленного счета необходимо передать в метод InvoiceId, полученный при вызове метода “Выставление счета по карте”.
После ввода данных банковской карты и успешного проведения платежа пользователь будет перенаправлен на адрес ReturnUrl, указанный при выставлении счета по карте. В случае ошибки проведения платежа пользователь будет перенаправлен на адрес FailUrl.

Метод: GET

URL: https://api.express-pay.by/v1/cardinvoices/{CardInvoiceNo}/payment?token={Token}


Входные параметры

Поле Тип Описание
Token String(32) API-ключ производителя услуг
CardInvoiceNo Integer Номер счета по карте, полученный с помощью метода “Выставление счета по карте”

- обязательные поля

Выходные параметры

Поле Тип Описание
FormUrl String(512) Адрес страницы ввода данных банковской карты
ErrorCode Integer Номер ошибки. Отсутствует, если ошибки нет
ErrorMessage String(512) Сообщение об ошибке. Отсутствует, если ошибки нет

Пример


public static async Task<string> GetPayFormAsync(string cardInvoiceNo, string token, bool useSignature, bool isTest, string secretWord)
{
	string url;
	if (!isTest)
	{
		url = string.Format("https://api.express-pay.by/v1/cardinvoices/{0}/payment?", cardInvoiceNo);
	}
	else
	{
		url = string.Format("https://sandbox-api.express-pay.by/v1/cardinvoices/{0}/payment?", cardInvoiceNo);
	}

	var requestParams = new Dictionary<string, string>
	{
		{"Token", token},
		{"CardInvoiceNo", cardInvoiceNo},
	};

	if (useSignature)
	{
		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
	}

	foreach (var rp in requestParams)
	{
		url += string.Format("&{0}={1}", rp.Key, rp.Value);
	}

	var response = await client.GetAsync(url);

	var responseString = await response.Content.ReadAsStringAsync();

	return responseString;
}

public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
{
	StringBuilder sb = new StringBuilder();
	Encoding HashEncoding = Encoding.UTF8;
	foreach (var item in requestParams)
		sb.Append(item.Value);

	HMACSHA1 hmac;
	if (string.IsNullOrWhiteSpace(secretWord))
	{
		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
		// что нам не подходит
		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
	}
	else
	{
		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
	}

	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
	var result = new StringBuilder();
	foreach (var item in hash) result.Append(item.ToString("X2"));

	return result.ToString();
}
							

Статус счета по карте

Метод возвращает статус счета по карте.

Метод: GET

URL: https://api.express-pay.by/v1/cardinvoices/{CardInvoiceNo}/status?token={Token}


Входные параметры

Поле Тип Описание
Token String(32) API-ключ производителя услуг
CardInvoiceNo Integer Номер счета по карте, полученный с помощью метода “Выставление счета по карте”
Language String(2) Язык в кодировке ISO 639-1. Если не указан, считается, что язык – русский. Сообщение об ошибке будет возвращено именно на этом языке.

- обязательные поля

Выходные параметры

Поле Тип Описание
Amount Integer Сумма оплаты
CardInvoiceStatus Integer Состояние оплаты:
0 - Счет зарегистрирован, но не оплачен
1 - Предавторизованная сумма захолдирована (для двухстадийных платежей)
2 - Проведена полная авторизация суммы счета
3 - Авторизация отменена
4 - По транзакции была проведена операция возврата
5 - Инициирована авторизация через ACS банка-эмитента
6 - Авторизация отклонена
ErrorCode Integer Номер ошибки. Отсутствует, если ошибки нет
ErrorMessage String(512) Сообщение об ошибке. Отсутствует, если ошибки нет

Пример


public static async Task<string> GetCardInvoiceStatusAsync(string cardInvoiceNo, string token, bool useSignature, bool isTest, string secretWord)
{
	string url;
	if (!isTest)
	{
		url = string.Format("https://api.express-pay.by/v1/cardinvoices/{0}/reverse?token={1}", cardInvoiceNo, token);
	}
	else
	{
		url = string.Format("https://sandbox-api.express-pay.by/v1/cardinvoices/{0}/reverse?token={1}", cardInvoiceNo, token);
	}

	var requestParams = new Dictionary<string, string>
	{
		{"Token", token},
		{"CardInvoiceNo", cardInvoiceNo},
	};

	if (useSignature)
	{
		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
	}

	var content = new FormUrlEncodedContent(requestParams);

	var response = await client.PostAsync(url, content);

	var responseString = await response.Content.ReadAsStringAsync();

	return responseString;
}

public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
{
	StringBuilder sb = new StringBuilder();
	Encoding HashEncoding = Encoding.UTF8;
	foreach (var item in requestParams)
		sb.Append(item.Value);

	HMACSHA1 hmac;
	if (string.IsNullOrWhiteSpace(secretWord))
	{
		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
		// что нам не подходит
		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
	}
	else
	{
		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
	}

	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
	var result = new StringBuilder();
	foreach (var item in hash) result.Append(item.ToString("X2"));

	return result.ToString();
}
							

Отмена платежа по карте

Метод отменяет оплату счета по карте. Использование операции отмены возможно до 23:59:59 дня проведения операции (не позднее). Для разрешения использования данной операции в анкете реквизитов услуги ЕРИП в разделе "Предоставление возможности плательщику отменить платеж" необходимо выставить опцию "Разрешить до перечисления денежных средств банком".

Метод: POST

URL: https://api.express-pay.by/v1/cardinvoices/{CardInvoiceNo}/reverse?token={Token}


Входные параметры

Поле Тип Описание
Token String(32) API-ключ производителя услуг
CardInvoiceNo Integer Номер счета по карте, полученный с помощью метода “Выставление счета по карте”

- обязательные поля

Выходные параметры

Поле Тип Описание
ErrorCode Integer Номер ошибки. Отсутствует, если ошибки нет
ErrorMessage String(512) Сообщение об ошибке. Отсутствует, если ошибки нет

Пример

             
private const string CardNumberInvoice = "1674";
public static void ReverseCardInvoice()
{
    var requestParams = new Dictionary
    {
        {"Token", AppSettings.Token},
        {"CardInvoiceNo", CardNumberInvoice}
    };
    var signature = SignatureHelper.Compute(requestParams, string.Empty, "reverse-card-invoice");

    var url = AppSettings.ServiceUrl + "cardinvoices/" + CardNumberInvoice + "/reverse?token=" + AppSettings.Token + "&signature=" + signature;

    using (var client = new WebClient())
    {
        client.Encoding = AppSettings.DefaultEncoding;
		var response = client.UploadValues(url, new NameValueCollection());
		var data = AppSettings.DefaultEncoding(response);
        Console.WriteLine(data);
    }
}
							

Описание API для платежных модулей

Выставление счета в системе ЕРИП

Метод выставляет новый счет. В данном методе цифровая подпись является обязательным параметром.

Метод: POST

URL: https://api.express-pay.by/v1/web_invoices


Входные параметры

Поле Тип Описание
ServiceId Integer Номер услуги
AccountNo String(30) Номер лицевого счета. Для способа оплаты EPOS длинна - 22 символа. Является уникальным значением.
Amount Decimal(19,2) Сумма счета на оплату. Разделителем дробной и целой части является символ запятой
Currency Integer Код валюты
Signature String Цифровая подпись
ReturnType String Тип ответа. Может принимать два значения:
  1. Redirect - перенаправляет пользователя по заданным адресам ReturnUrl или FailUrl. При выборе данного типа ответа
  2. Json - возвращает результат операции в формате json
ReturnUrl String Адрес, на который происходит перенаправление после успешного выставления счета
FailUrl String Адрес, на который происходит перенаправление при ошибке выставления счета
Expiration String(8) Дата истечения срока действия выставлена счета на оплату. Формат - yyyyMMdd
Info String(1024) Назначение платежа
Surname String(30) Фамилия
FirstName String(30) Имя
Patronymic String(30) Отчество
City String(30) Город
Street String(18) Улица
House String(18) Дом
Building String(10) Корпус
Apartment String(10) Квартира
IsNameEditable Integer При оплате разрешено изменять ФИО плательщика 0 – нет, 1 – да
IsAddressEditable Integer При оплате разрешено изменять адрес плательщика 0 – нет, 1 – да
IsAmountEditable Integer При оплате разрешено изменять сумму оплаты 0 – нет, 1 – да
EmailNotification String(255) Адрес электронной почты, на который будет отправлено уведомление о выставлении счета
SmsPhone String(13) Номер мобильного телефона, на который будет отправлено SMS-сообщение о выставлении счета
ReturnInvoiceUrl Integer Вернуть в ответе публичную ссылку на счет
0 – нет, 1 – да (0 - по умолчанию)
(Примечание: только для случая, когда ReturnType равен 2 (Json))

- обязательные поля


Выходные параметры при ReturnType равном json

Поле Тип Описание
InvoiceNo Integer Номер счета
InvoiceUrl String(64) Публичная ссылка на счет. Отсутствует, если входной параметр ReturnInvoiceUrl установлен в 0 (нет) или не задан, а также если ReturnType не равен 2 (Json)

Выходные параметры при ReturnType равном redirect

Поле Тип Описание
ExpressPayAccountNumber String Номер счета
ExpressPayInvoiceNo Integer Id счета
Signature String Цифровая подпись

Пример

                
 public static async Task<string> AddWebInvoiceAsync(string token, bool useSignature, bool isTest, string secretWord)
 {
 	string url;
 	if (!isTest)
 	{
 		url = "https://api.express-pay.by/v1/web_invoices";
 	}
 	else
 	{
 		url = "https://sandbox-api.express-pay.by/v1/web_invoices";
 	}
 
 	var requestParams = new Dictionary<string, string>
 	{
 		{"Token", token},
 		{"ServiceId", "4" },
 		{"AccountNo", "123"},
 		{"Amount", "123,01" },
 		{"Currency", "933" },
 		{"Expiration", "20210321" },
 		{"Info", "Оплата счёта" },
 		{"Surname", "Иванов" },
 		{"FirstName", "Иван" },
 		{"Patronymic", "Иванович"},
 		{"City", "Город"},
 		{"Street", "Улица"},
 		{"House", "Дом"},
 		{"Building", "Корпус"},
 		{"Apartment", "Квартира"},
 		{"IsNameEditable", "0"},
 		{"IsAddressEditable", "0"},
 		{"IsAmountEditable", "0"},
 		{"EmailNotification", "example@example.com"},
 		{"SmsPhone", "+375291234567"},
 		{"ReturnType", "json" },
 		{"ReturnUrl", "-" },
 		{"FailUrl", "-" },
 		{"ReturnInvoiceUrl", "0"}
 	};
 
 	if (useSignature)
 	{
 		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
 	}
 
 	// После формирования цифровой подписи удаляем API-ключ
 	// т.к он не учавствует в выставлении счета 
 	requestParams.Remove("Token");
 
 	var content = new FormUrlEncodedContent(requestParams);
 
 	var response = await client.PostAsync(url, content);
 
 	var responseString = await response.Content.ReadAsStringAsync();
 
 	return responseString;
 
 }
 
 public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
 {
 	StringBuilder sb = new StringBuilder();
 	Encoding HashEncoding = Encoding.UTF8;
 
 	foreach (var item in requestParams)
 		sb.Append(item.Value);
 
 	HMACSHA1 hmac;
 	if (string.IsNullOrWhiteSpace(secretWord))
 	{
 		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
 		// что нам не подходит
 		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
 	}
 	else
 	{
 		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
 	}
 
 	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
 	var result = new StringBuilder();
 	foreach (var item in hash) result.Append(item.ToString("X2"));
 
 	return result.ToString();
 }
                        
                    

Выставление счета по карте

Метод выставляет новый счет для оплаты через банковскую карту. В данном методе цифровая подпись является обязательным параметром.

Метод: POST

URL: https://api.express-pay.by/v1/web_cardinvoices


Входные параметры

Поле Тип Описание
ServiceId Integer Номер услуги
AccountNo String(30) Номер лицевого счета. Для способа оплаты EPOS длинна - 22 символа.
Amount Decimal(19,2) Сумма счета на оплату. Разделителем дробной и целой части является символ запятой
Currency Integer Код валюты
Signature String Цифровая подпись
ReturnType String Тип ответа. Может принимать два значения:
  1. Redirect - перенаправляет пользователя по заданным адресам ReturnUrl или FailUrl. При выборе данного типа ответа
  2. Json - возвращает результат операции в формате json
ReturnUrl String Адрес, на который происходит перенаправление после успешного выставления счета
FailUrl String Адрес, на который происходит перенаправление при ошибке выставления счета
Expiration String(8) Дата истечения срока действия выставлена счета на оплату. Формат - yyyyMMdd
Info String(1024) Назначение платежа
ReturnInvoiceUrl Integer Вернуть в ответе публичную ссылку на счет
0 – нет, 1 – да (0 - по умолчанию)
(Примечание: только для случая, когда ReturnType равен 2 (Json))
CustomerId Integer Id клиента соверщающего платёж.
Используется для использования функции "Упрощенный платеж"
(Примечание: только для случая, использования WebPay)

- обязательные поля


Выходные параметры при ReturnType равном json

Поле Тип Описание
FormUrl String(512) Адрес страницы ввода данных банковской карты
InvoiceUrl String(64) Публичная ссылка на счет. Отсутствует, если входной параметр ReturnInvoiceUrl установлен в 0 (нет) или не задан, а также если ReturnType не равен 2 (Json)

Выходные параметры при ReturnType равном redirect

Поле Тип Описание
ExpressPayAccountNumber String Номер счета
ExpressPayInvoiceNo Integer Id счета
Signature String Цифровая подпись

Пример

                
public static async Task<string> AddWebCardInvoiceAsync(string token, bool useSignature, bool isTest, string secretWord)
{
	string url;
	if (!isTest)
	{
		url = "https://api.express-pay.by/v1/web_cardinvoices";
	}
	else
	{
		url = "https://sandbox-api.express-pay.by/v1/web_cardinvoices";
	}

	var requestParams = new Dictionary<string, string>
	{
		{"Token", token},
		{"ServiceId", "4" },
		{"AccountNo", "123"},
		{"Expiration", "20210321" },
		{"Amount", "123,01" },
		{"Currency", "933" },
		{"Info", "Оплата счёта" },
		{"ReturnUrl", "-" },
		{"FailUrl", "-" },
		{"ReturnType", "json" },
		{"ReturnInvoiceUrl", "0"}
	};

	if (useSignature)
	{
		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
	}

	// После формирования цифровой подписи удаляем API-ключ
	// т.к он не учавствует в выставлении счета 
	requestParams.Remove("Token");

	var content = new FormUrlEncodedContent(requestParams);

	var response = await client.PostAsync(url, content);

	var responseString = await response.Content.ReadAsStringAsync();

	return responseString;

}

public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
{
	StringBuilder sb = new StringBuilder();
	Encoding HashEncoding = Encoding.UTF8;

	foreach (var item in requestParams)
		sb.Append(item.Value);

	HMACSHA1 hmac;
	if (string.IsNullOrWhiteSpace(secretWord))
	{
		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
		// что нам не подходит
		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
	}
	else
	{
		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
	}

	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
	var result = new StringBuilder();
	foreach (var item in hash) result.Append(item.ToString("X2"));

	return result.ToString();
}
                        
                    

Платежи

Получить список оплат

Метод возвращает список полученных оплат. Если входные параметры запроса не заданы, то метод возвращает список полученных оплат за последние 30 дней.

Метод: GET

URL: https://api.express-pay.by/v1/payments?token={Token}


Входные параметры

Поле Тип Описание
Token String(32) API-ключ производителя услуг
From String(8) - Форматы yyyyMMdd / yyyyMMddHHmm / yyyyMMddHHmmss Дата оплаты с – начало периода
To String(8) - Форматы yyyyMMdd / yyyyMMddHHmm / yyyyMMddHHmmss Дата оплаты по – конец периода
AccountNo String(30) Номер лицевого счета

- обязательные поля

Выходные параметры

Поле Тип Описание
PaymentNo Integer Номер платежа
AccountNo String(30) Номер лицевого счета
Created String(14) Дата/Время платежа. Формат - yyyyMMddHHmmss
Amount Decimal(19,2) Сумма платежа
Currency Integer Код валюты
Info String(1024) Назначение платежа
Surname String(30) Фамилия
FirstName String(30) Имя
Patronymic String(30) Отчество
City String(30) Город
Street String(30) Улица
House String(10) Дом
Building String(10) Корпус
Apartment String(10) Квартира
DocumentNumber Integer Номер платежного документа о зачислении средств на расчётный счёт (для платежей через ЕРИП)
DocumentDate String(8) Дата платежного документа о зачислении средств на расчётный счёт (для платежей через ЕРИП). Формат - yyyyMMdd
CanceledDate String(14) Дата возврата платежа. Формат - yyyyMMddHHmmss
TransferredAmount Decimal(19,2) Сумма перечисленная

Пример


public static async Task<string> GetListPaymentAsync(string token, bool useSignature, bool isTest, string secretWord)
{
	string url;
	if (!isTest)
	{
		url = "https://api.express-pay.by/v1/payments?";
	}
	else
	{
		url = "https://sandbox-api.express-pay.by/v1/payments?";
	}

	var requestParams = new Dictionary<string, string>
	{
		{"Token", token},
		//Параметры фильтра являются опциональными, по умолчанию возврщает значения за последние 30 дней
		{"AccountNo", ""},
		{"From", "" },
		{"To", "" },
		{"Status", "" }
	};

	if (useSignature)
	{
		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
	}

	foreach (var rp in requestParams)
	{
		url += string.Format("&{0}={1}", rp.Key, rp.Value);
	}

	var response = await client.GetAsync(url);

	var responseString = await response.Content.ReadAsStringAsync();

	return responseString;
}

public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
{
	StringBuilder sb = new StringBuilder();
	Encoding HashEncoding = Encoding.UTF8;
	foreach (var item in requestParams)
		sb.Append(item.Value);

	HMACSHA1 hmac;
	if (string.IsNullOrWhiteSpace(secretWord))
	{
		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
		// что нам не подходит
		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
	}
	else
	{
		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
	}

	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
	var result = new StringBuilder();
	foreach (var item in hash) result.Append(item.ToString("X2"));

	return result.ToString();
}
					

Детальная информация об оплате

Метод возвращает детальную информацию о полученной оплате

Метод: GET

URL: https://api.express-pay.by/v1/payments/{PaymentNo}?token={Token}


Входные параметры

Поле Тип Описание
Token String(32) API-ключ производителя услуг
PaymentNo Integer Номер платежа

- обязательные поля

Выходные параметры

Поле Тип Описание
AccountNo String(30) Номер лицевого счета
Created String(14) Дата/Время платежа. Формат - yyyyMMddHHmmss
Amount Decimal(19,2) Сумма платежа
Currency Integer Код валюты
Info String(1024) Назначение платежа
Surname String(30) Фамилия
FirstName String(30) Имя
Patronymic String(30) Отчество
City String(30) Город
Street String(30) Улица
House String(10) Дом
Building String(10) Корпус
Apartment String(10) Квартира
DocumentNumber String Номер платежного документа
DocumentDate String Дата платежного документа

Пример


public static async Task<string> GetPaymentDetailAsync(string paymentNo, string token, bool useSignature, bool isTest, string secretWord)
{
	string url;
	if (!isTest)
	{
		url = string.Format("https://api.express-pay.by/v1/payments/{0}?", paymentNo);
	}
	else
	{
		url = string.Format("https://sandbox-api.express-pay.by/v1/payments/{0}?", paymentNo);
	}

	var requestParams = new Dictionary<string, string>
	{
		{"Token", token},
		{"PaymentNo", paymentNo}
	};

	if (useSignature)
	{
		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
	}

	foreach (var rp in requestParams)
	{
		url += string.Format("&{0}={1}", rp.Key, rp.Value);
	}

	var response = await client.GetAsync(url);

	var responseString = await response.Content.ReadAsStringAsync();

	return responseString;
}

public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
{
	StringBuilder sb = new StringBuilder();
	Encoding HashEncoding = Encoding.UTF8;
	foreach (var item in requestParams)
		sb.Append(item.Value);

	HMACSHA1 hmac;
	if (string.IsNullOrWhiteSpace(secretWord))
	{
		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
		// что нам не подходит
		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
	}
	else
	{
		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
	}

	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
	var result = new StringBuilder();
	foreach (var item in hash) result.Append(item.ToString("X2"));

	return result.ToString();
}
		

Получить баланс по лицевому счету

Метод возвращает информацию о балансе лицевого счета

Метод: GET

URL: https://api.express-pay.by/v1/balance?token={Token}


Входные параметры

Поле Тип Описание
Token String(32) API-ключ производителя услуг
AccountNo String(30) Номер лицевого счета

- обязательные поля

Выходные параметры

Поле Тип Описание
Balance Decimal(19,2) Баланс

Пример


public static async Task<string> GetBalanceAsync(string token, bool useSignature, bool isTest, string secretWord)
{
	string url;
	if (!isTest)
	{
		url = "https://api.express-pay.by/v1/balance?";
	}
	else
	{
		url = "https://sandbox-api.express-pay.by/v1/balance?";
	}

	var requestParams = new Dictionary<string, string>
	{
		{"Token", token},
		{"AccountNo", "100"}
	};

	if (useSignature)
	{
		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
	}

	foreach (var rp in requestParams)
	{
		url += string.Format("&{0}={1}", rp.Key, rp.Value);
	}

	var response = await client.GetAsync(url);

	var responseString = await response.Content.ReadAsStringAsync();

	return responseString;
}

public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
{
	StringBuilder sb = new StringBuilder();
	Encoding HashEncoding = Encoding.UTF8;
	foreach (var item in requestParams)
		sb.Append(item.Value);

	HMACSHA1 hmac;
	if (string.IsNullOrWhiteSpace(secretWord))
	{
		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
		// что нам не подходит
		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
	}
	else
	{
		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
	}

	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
	var result = new StringBuilder();
	foreach (var item in hash) result.Append(item.ToString("X2"));

	return result.ToString();
}
                

Рекуррентные платежи

Привязка карты

Метод выполняет инициирующий платеж для привязки карты.

Метод: POST

URL: https://api.express-pay.by/v1/recurringpayment/bind


Входные параметры

Поле Тип Описание
ServiceId Integer Номер услуги
WriteOffPeriod Integer Период через который необходимо произвести следующие списание.
Возможные значения:
0 – По запросу (без периода)
1 – День
2 – Неделя
3 – Месяц
4 – 3 месяца
5 – 6 месяцев
6 – Год
Amount Decimal(19,2) Сумма счета на оплату. Разделителем дробной и целой части является символ запятой
Currency Integer Код валюты
Signature String Цифровая подпись
Info String Назначение платежа
ReturnType String Тип ответа. Может принимать два значения:
  1. Redirect - перенаправляет пользователя по заданным адресам ReturnUrl или FailUrl. При выборе данного типа ответа
  2. Json - возвращает результат операции в формате json
ReturnUrl String Адрес, на который происходит перенаправление после успешного выставления счета
FailUrl String Адрес, на который происходит перенаправление при ошибке выставления счета
Language String Язык в кодировке ISO 639-1. Если не указан, считается, что язык – русский. Сообщение об ошибке будет возвращено именно на этом языке.

- обязательные поля

При WriteOffPeriod = 0 осуществляется сброс платежа, а карта остается привязанной

Выходные параметры


Выходные параметры при ReturnType равном json

Поле Тип Описание
CustomerId Integer Номер привзяки (используется при отвязке карты)
FormUrl String(512) Адрес страницы ввода данных банковской карты

Выходные параметры при ReturnType равном redirect

Поле Тип Описание
CustomerId Integer Номер привзяки (используется при отвязке карты)
Signature String Цифровая подпись

Пример

                
public static async Task<string> BindCardAsync(string token, bool useSignature, bool isTest, string secretWord)
{
	string url;
	if (!isTest)
	{
		url = "https://api.express-pay.by/v1/recurringpayment/bind";
	}
	else
	{
		url = "https://sandbox-api.express-pay.by/v1/recurringpayment/bind";
	}

	var requestParams = new Dictionary<string, string>
	{
            {"Token", token},
            {"ServiceId", "6"},
            {"WriteOffPeriod", "1"},
            {"Amount", "6"},
            {"Currency", "933"},
            {"Info", "Оплата счёта"},
            {"ReturnUrl", "https://express-pay.by/"},
            {"FailUrl", "https://express-pay.by/"},
            {"Language", "ru"},
            {"ReturnType", "json"}
	};
    
	if (useSignature)
	{
		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
	}
    // После формирования цифровой подписи удаляем API-ключ
    requestParams.Remove("Token");
    var content = new FormUrlEncodedContent(requestParams);
	using (var client = new HttpClient())
    {
	   var response = await client.PostAsync(url, content);

	   var responseString = await response.Content.ReadAsStringAsync();

	   return responseString;
    }
}

public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
{
	StringBuilder sb = new StringBuilder();
	Encoding HashEncoding = Encoding.UTF8;
	foreach (var item in requestParams)
		sb.Append(item.Value);

	HMACSHA1 hmac;
	if (string.IsNullOrWhiteSpace(secretWord))
	{
		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
		// что нам не подходит
		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
	}
	else
	{
		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
	}

	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
	var result = new StringBuilder();
	foreach (var item in hash) result.Append(item.ToString("X2"));

	return result.ToString();
}

Оплата по привязанной карте

Метод выполняет оплату по привязанной карте.

Метод: POST

URL: https://api.express-pay.by/v1/recurringpayment/payment


Входные параметры

Поле Тип Описание
CustomerId Integer Id привязки
ServiceId Integer Номер услуги
Amount Decimal(19,2) Сумма счета на оплату. Разделителем дробной и целой части является символ запятой
Info String Назначение платежа
Signature String Цифровая подпись

- обязательные поля


Выходные параметры

Поле Тип Описание
CustomerId Integer Номер привзяки
Card String Обфусцированный номер карты (Маскированный)
Amount String Сумма платежа
Text String Текстовая информация
BatchTimestamp String Штамп времени
TransactionId String Номер транзакции

Пример

                
public static async Task<string> PaymentBindCardAsync(string token, bool useSignature, bool isTest, string secretWord)
{
	string url;
	if (!isTest)
	{
		url = "https://api.express-pay.by/v1/recurringpayment/payment";
	}
	else
	{
		url = "https://sandbox-api.express-pay.by/v1/recurringpayment/payment";
	}

	var requestParams = new Dictionary<string, string>
	{
            {"Token", token},
            {"CustomerId", "10"},
            {"ServiceId", "6"},
            {"Amount", "6"},
            {"Info", "Оплата счёта"},
	};

	if (useSignature)
	{
		requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
	}
    
    // После формирования цифровой подписи удаляем API-ключ
    requestParams.Remove("Token");
   var content = new FormUrlEncodedContent(requestParams);
   using (var client = new HttpClient())
   {
        var response = await client.PostAsync(url, content);

        var responseString = await response.Content.ReadAsStringAsync();

        return responseString;
   }
}

public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
{
	StringBuilder sb = new StringBuilder();
	Encoding HashEncoding = Encoding.UTF8;
	foreach (var item in requestParams)
		sb.Append(item.Value);

	HMACSHA1 hmac;
	if (string.IsNullOrWhiteSpace(secretWord))
	{
		// в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
		// что нам не подходит
		hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
	}
	else
	{
		hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
	}

	var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
	var result = new StringBuilder();
	foreach (var item in hash) result.Append(item.ToString("X2"));

	return result.ToString();
}

Отвязка карты

Метод выполняет отвязку карты.

Метод: DELETE

URL: https://api.express-pay.by/v1/recurringpayment/unbind/{CustomerId}


Входные параметры

Поле Тип Описание
CustomerId Integer Id привязки
ServiceId Integer Номер услуги
Signature String Цифровая подпись

- обязательные поля

Выходные параметры

Поле Тип Описание
Text String Текстовая информация

Пример


public static async Task<string> UnbindCardAsync(string customerId, string token, bool useSignature, bool isTest, string secretWord)
{
    string url;
    if (!isTest)
    {
        url = string.Format("https://api.express-pay.by/v1/recurringpayment/unbind/{0}", customerId);
    }
    else
    {
        url = string.Format("https://sandbox-api.express-pay.by/v1/recurringpayment/unbind/{0}", customerId);
    }

    var requestParams = new Dictionary<string, string>
    {
        { "Token", token},
        { "ServiceId", "6" }
    };

    if (useSignature)
    {
        requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
    }

    // После формирования цифровой подписи удаляем API-ключ
    requestParams.Remove("Token");
    url += string.Format("?{0}={1}", requestParams.FirstOrDefault().Key, requestParams.FirstOrDefault().Value);
     foreach (var rp in requestParams.Skip(1) )
     {
         url += string.Format("&{0}={1}", rp.Key, rp.Value);
     }

     using (var client = new HttpClient())
     {
         var response = await client.DeleteAsync(url);

         var responseString = await response.Content.ReadAsStringAsync();

         return responseString;
     }

}

public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
{
    StringBuilder sb = new StringBuilder();
    Encoding HashEncoding = Encoding.UTF8;

    foreach (var item in requestParams)
        sb.Append(item.Value);

    HMACSHA1 hmac;
    if (string.IsNullOrWhiteSpace(secretWord))
    {
        // в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
        // что нам не подходит
        hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
    }
    else
    {
        hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
    }

    var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
    var result = new StringBuilder();
    foreach (var item in hash) result.Append(item.ToString("X2"));

    return result.ToString();
}
					

Информация о карте

Метод получает информацию о карте.

Метод: GET

URL: https://api.express-pay.by/v1/recurringpayment/bind/{CustomerId}


Входные параметры

Поле Тип Описание
CustomerId Integer Id привязки
ServiceId Integer Номер услуги
Signature String Цифровая подпись

- обязательные поля


Выходные параметры

Поле Тип Описание
Status String Статус карты (привязана, не привязана )
Card String Обфусцированный номер карты (Маскированный)
OfferExpDate String Дата завершения привязки

Пример


public static async Task<string> GetbindCardAsync(string customerId, string token, bool useSignature, bool isTest, string secretWord)
{
    string url;
    if (!isTest)
    {
      url = string.Format("https://api.express-pay.by/v1/recurringpayment/bind/{0}", customerId);
    }
    else
    {
      url = string.Format("https://sandbox-api.express-pay.by/v1/recurringpayment/bind/{0}", customerId);
    }

    var requestParams = new Dictionary<string, string>
    {
        { "Token", token},
        { "ServiceId", "6" }
    };

    if (useSignature)
    {
        requestParams.Add("signature", ComputeSignature(requestParams, secretWord));
    }

    // После формирования цифровой подписи удаляем API-ключ
    requestParams.Remove("Token");
    url += string.Format("?{0}={1}", requestParams.FirstOrDefault().Key, requestParams.FirstOrDefault().Value);
     foreach (var rp in requestParams.Skip(1) )
     {
         url += string.Format("&{0}={1}", rp.Key, rp.Value);
     }

     using (var client = new HttpClient())
     {
         var response = await client.GetAsync(url);

         var responseString = await response.Content.ReadAsStringAsync();

         return responseString;
     }

}

public static string ComputeSignature(Dictionary<string, string> requestParams, string secretWord)
{
    StringBuilder sb = new StringBuilder();
    Encoding HashEncoding = Encoding.UTF8;

    foreach (var item in requestParams)
        sb.Append(item.Value);

    HMACSHA1 hmac;
    if (string.IsNullOrWhiteSpace(secretWord))
    {
        // в алгоритме всегда должно быть задан ключ шифрования. Если исп. конструктор по умолчанию, то ключ генерится автоматически,
        // что нам не подходит
        hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
    }
    else
    {
        hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
    }

    var hash = hmac.ComputeHash(HashEncoding.GetBytes(sb.ToString()));
    var result = new StringBuilder();
    foreach (var item in hash) result.Append(item.ToString("X2"));

    return result.ToString();
}
					

Уведомления на сайт для рекуррентных платежей

Уведомления на сайт предназначены для вызова специального адреса сайта производителя услуг. Такой способ получения уведомлений снижает нагрузку на серверы и увеличивает скорость доставки уведомлений о платежах.

Вызов адреса сайта происходит в момент совершения платежа в адрес производителя услуг или при изменении статуса привязки карты. Вызываемый адрес сайта указывается в настройках личного кабинета.

Для этого необходимо выполнить следующие операции:
  1. Перейти в раздел настройки (пункт меню “Настройка”);
  2. Перейти на вкладку “Услуги”;
  3. В списке услуг для нужной услуги перейти на “Уведомления”;
  4. Установить опцию “Получать уведомления об оплате на URL”;
  5. Указать адрес вызова сайта производителя услуг в поле “URL для уведомлений” вида https://mydomain.by/express-pay/notification (см. рисунок).
Настройка адреса адрес сайт для доставки уведомления на сайт

Настройка адреса адрес сайт для доставки уведомления на сайт


В уведомлении на сайт данные передаются POST-запросом. Во всех запросах передаются обязательные параметры:

  • Data – информация о платеже в JSON-формате (поступление нового платежа, отмена платежа, изменение статуса счета);
  • Signature={hash} – цифровая подпись запроса, которая формируется на основании секретного слова (задается в личном кабинете) и передаваемых данных. Данный параметр передается в случае установки опции “Применять цифровую подпись”.

Сайт производителя услуг должен ответить HTTP-кодом 200 в случае успешной обработки запроса. Если сайт производителя услуг вернет код ответа отличный от 200 или истечет таймаут ожидания ответа, то будет выполнена повторная попытка доставки уведомления. Для обеспечения гарантированной доставки уведомления выполняется 3 дополнительных попытки доставки уведомлений. Первая попытка доставки выполняется выполняется через 30 секунд, вторая через 3 минуты, третья через 30 минут, четвертая через 3 часа.

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

При включении опции “Применять цифровую подпись” будет формироваться цифровая подпись для передаваемых данных, которая позволяет контролировать целостность передаваемых данных (защита от MITM-атак). Цифровая подпись основана на алгоритме HMAC-SHA1, который описан в стандарте RFC 2104.

Параметр “Таймаут ожидания ответа” устанавливает время, которое сервер «Экспресс Платежи» будет ожидать ответа от сайта производителя услуг. Если в течение данного времени сервер производителя услуг не вернет ответ с HTTP-кодом 200, то попытка доставки уведомления считается неудачной.

Параметры уведомления о платежах

Поле Тип Описание
CmdType Integer Тип уведомления:
  • 6 - Изменение статуса привязки
  • 7 - Получение рекуррентного платежа
Status Integer Статус привязки карты:
  • 1 - Привязка инициализирована
  • 2 - Карта привязана
  • 3 - Ошибка привязки карты
  • 4 - Карта отвязана
  • 5 - Ошибка отвязки карты
AccountNo String(30) Номер лицевого счета
InvoiceNo String(30) Номер измененного счета в системе «Экспресс Платежи»
PaymentNo Integer Номер платежа
Amount Decimal(19,2) Сумма оплаты (разделитель между целой и дробной частью ",")
Created String(14) Дата оплаты (Формат - yyyyMMddHHmmss)
Service String(258) Название услуги
CustomerId Integer Номер привязки
Пример передаваемых данных при изменении статуса привязки:
{
    "CmdType":6,
    "Status":3,
    "AccountNo":"147221",
    "InvoiceNo":17645,
    "Amount":"16",
    "Created":"20161130125859",
    "Service":"10ballov.by",
    "CustomerId":1
}
Пример передаваемых данных при получении рекуррентного платежа:
{
    "CmdType":7,
    "PaymentNo":123456,
    "AccountNo":"147221",
    "Amount":"16",
    "Created":"20221130125859",
    "Service":"10ballov.by",
    "CustomerId":1
}

Пример исходного кода получения данных от сервера


namespace EripNotify.Models
{
    public class EripNotify
    {
        public string Data { get; set; }
        public string Signature { get; set; }
    }
}
namespace EripNotify.Controllers
{
    public class EripNotifyController : ApiController
    {
        private static readonly Encoding HashEncoding = Encoding.UTF8;
        private string _secretWord = "secretWord";
        private bool _useSignature = false;
        [HttpPost]
        public IHttpActionResult Test(Models.EripNotify model)
        {
            if (_useSignature)
            {
                // Проверяем цифровую подпись
                if (model.Signature != ComputeSignature(model.Data, _secretWord))
                {
                    // NOTE: Добавить обработку ошибки
                    // ...
                    return InternalServerError();
                }
            }
            // Преобразуем из JSON в Object
            var obj = JObject.Parse(model.Data);
            // NOTE: Выполняем действия с полученным объектом
            // ...
            return Ok();
        }
        // Функция генерации и проверки цифровой подписи
        public string ComputeSignature(string json, string secretWord)
        {
            var hmac = string.IsNullOrWhiteSpace(secretWord) ? 
                new HMACSHA1(HashEncoding.GetBytes(string.Empty)) : 
                new HMACSHA1(HashEncoding.GetBytes(secretWord));
            var hash = hmac.ComputeHash(HashEncoding.GetBytes(json));
            var result = new StringBuilder();
            foreach (var item in hash)
                result.Append(item.ToString("X2"));
            return result.ToString();
        }
    }
}

Уведомления на сайт

Уведомления на сайт предназначены для вызова специального адреса сайта производителя услуг. При использовании такого способа получения уведомлений нет необходимости постоянно опрашивать поступившие платежи через API. Такой способ получения уведомлений снижает нагрузку на серверы и увеличивает скорость доставки уведомлений о платежах.

Вызов адреса сайта происходит в момент совершения платежа в адрес производителя услуг или при изменении статуса счета на оплату. Вызываемый адрес сайта указывается в настройках личного кабинета.

Для этого необходимо выполнить следующие операции:
  1. Перейти в раздел настройки (пункт меню “Настройка”);
  2. Перейти на вкладку “Услуги”;
  3. В списке услуг для нужной услуги перейти на “Уведомления”;
  4. Установить опцию “Получать уведомления об оплате на URL”;
  5. Указать адрес вызова сайта производителя услуг в поле “URL для уведомлений” вида https://mydomain.by/express-pay/notification (см. рисунок).
Настройка адреса адрес сайт для доставки уведомления на сайт

Настройка адреса адрес сайт для доставки уведомления на сайт


В уведомлении на сайт данные передаются POST-запросом. Во всех запросах передаются обязательные параметры:

  • Data – информация о платеже в JSON-формате (поступление нового платежа, отмена платежа, изменение статуса счета);
  • Signature={hash} – цифровая подпись запроса, которая формируется на основании секретного слова (задается в личном кабинете) и передаваемых данных. Данный параметр передается в случае установки опции “Применять цифровую подпись”.

Сайт производителя услуг должен ответить HTTP-кодом 200 в случае успешной обработки запроса. Если сайт производителя услуг вернет код ответа отличный от 200 или истечет таймаут ожидания ответа, то будет выполнена повторная попытка доставки уведомления. Для обеспечения гарантированной доставки уведомления выполняется 3 дополнительных попытки доставки уведомлений. Первая попытка доставки выполняется выполняется через 30 секунд, вторая через 3 минуты, третья через 30 минут, четвертая через 3 часа.

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

При включении опции “Применять цифровую подпись” будет формироваться цифровая подпись для передаваемых данных, которая позволяет контролировать целостность передаваемых данных (защита от MITM-атак). Цифровая подпись основана на алгоритме HMAC-SHA1, который описан в стандарте RFC 2104.

Параметр “Таймаут ожидания ответа” устанавливает время, которое сервер «Экспресс Платежи» будет ожидать ответа от сайта производителя услуг. Если в течение данного времени сервер производителя услуг не вернет ответ с HTTP-кодом 200, то попытка доставки уведомления считается неудачной.

Параметры уведомления о платежах

Поле Тип Описание
CmdType Integer Тип уведомления:
  • 1 - Поступление нового платежа
  • 2 - Отмена платежа
  • 3 - Изменение статуса счета
Status Integer Статус счета на оплату:
  • 1 - Ожидает оплату
  • 2 - Просрочен
  • 3 - Оплачен
  • 4 - Оплачен частично
  • 5 - Отменен
  • 6 - Оплачен с помощью банковской карты
  • 7 - Платеж возращен
Опциональное поле. Возвращается только в уведомления типа 3.
AccountNo String(30) Номер лицевого счета
InvoiceNo String(30) Номер измененного счета в системе «Экспресс Платежи»
PaymentNo Integer Номер платежа
Amount Decimal(19,2) Сумма оплаты (разделитель между целой и дробной частью ",")
Created String(14) Дата оплаты (Формат - yyyyMMddHHmmss)
Service String(258) Название услуги
Payer String(258) ФИО плательщика
Address String(258) Адрес плательщика
CardInvoiceNo Integer Номер счета по карте (не обязательное. Возвращается только в случае, если выполнялась оплата счета по карте)
Пример передаваемых данных при получении нового платежа:
{
    "CmdType":1,
    "AccountNo":"740049794",
    "PaymentNo":8015723,
    "Amount":"46,20",
    "Currency":"BYN",
    "Created":"20240808142659",
    "Service":"Пополнение через терминалы",
    "Payer":"",
    "Address":""

}
Пример передаваемых данных при отмене платежа:
{
    "CmdType":2,
    "AccountNo":"1111",
    "PaymentNo":711139,
    "Amount":"24",
    "Currency":"BYN",
    "Created":"20240710122737",
    "Service":"Консультационные услуги",
    "Payer":"",
    "Address":""
}
Пример передаваемых данных при изменении статуса счета:
{
    "CmdType":3,
    "Status":3,
    "AccountNo":"740321905",
    "InvoiceNo":11708345,
    "Amount":"30,06",
    "Created":"20240828134829",
    "Service":"Пополнение по QR коду",
    "Payer":"",
    "Address":""
}

При нажатии кнопки “Тестовое уведомление на URL” выполняется доставка тестового уведомления о платеже на адрес производителя услуг, по которому можно проверить прием платежа сайтом производителя услуг.

Пример исходного кода получения данных от сервера


namespace EripNotify.Models
{
    public class EripNotify
    {
        public string Data { get; set; }
        public string Signature { get; set; }
    }
}
namespace EripNotify.Controllers
{
    public class EripNotifyController : ApiController
    {
        private static readonly Encoding HashEncoding = Encoding.UTF8;
        private string _secretWord = "secretWord";
        private bool _useSignature = false;
        [HttpPost]
        public IHttpActionResult Test(Models.EripNotify model)
        {
            if (_useSignature)
            {
                // Проверяем цифровую подпись
                if (model.Signature != ComputeSignature(model.Data, _secretWord))
                {
                    // NOTE: Добавить обработку ошибки
                    // ...
                    return InternalServerError();
                }
            }
            // Преобразуем из JSON в Object
            var obj = JObject.Parse(model.Data);
            // NOTE: Выполняем действия с полученным объектом
            // ...
            return Ok();
        }
        // Функция генерации и проверки цифровой подписи
        public string ComputeSignature(string json, string secretWord)
        {
            var hmac = string.IsNullOrWhiteSpace(secretWord) ? 
                new HMACSHA1(HashEncoding.GetBytes(string.Empty)) : 
                new HMACSHA1(HashEncoding.GetBytes(secretWord));
            var hash = hmac.ComputeHash(HashEncoding.GetBytes(json));
            var result = new StringBuilder();
            foreach (var item in hash)
                result.Append(item.ToString("X2"));
            return result.ToString();
        }
    }
}

Проверка состояния лицевого счета по URL

Проверка состояния лицевого счета по URL позволяет запрашивать баланс непосредственно у производителя услуг.

Вызов адреса сайта происходит в момент совершения платежа в адрес производителя услуг. Вызываемый адрес сайта указывается в настройках личного кабинета.

Для этого необходимо выполнить следующие операции:
  1. Перейти в раздел настройки (пункт меню “Настройка”);
  2. Перейти на вкладку “Услуги”;
  3. В списке услуг для нужной услуги перейти на “Уведомления”;
  4. Установить опцию “Проверять состояние лицевого счета по URL”;
  5. Указать адрес вызова сайта производителя услуг в поле “URL для проверки состояния лицевого счета” вида https://mydomain.by/express-pay/getbalance (см. рисунок).
Настройка адреса адрес сайт для доставки уведомления на сайт

Настройка адреса адрес сайт для доставки уведомления на сайт


В уведомлении на сайт данные передаются POST-запросом. Во всех запросах передаются обязательные параметры:

  • Data – информация о платеже в JSON-формате;
  • Signature={hash} – цифровая подпись запроса, которая формируется на основании секретного слова (задается в личном кабинете) и передаваемых данных. Данный параметр передается в случае установки опции “Применять цифровую подпись”.

Сайт производителя услуг должен ответить HTTP-кодом 200 в случае успешной обработки запроса.

При включении опции “Применять цифровую подпись” будет формироваться цифровая подпись для передаваемых данных, которая позволяет контролировать целостность передаваемых данных (защита от MITM-атак). Цифровая подпись основана на алгоритме HMAC-SHA1, который описан в стандарте RFC 2104.

Параметр “Таймаут ожидания ответа” устанавливает время, которое сервер «Экспресс Платежи» будет ожидать ответа от сайта производителя услуг. Если в течение данного времени сервер производителя услуг не вернет ответ с HTTP-кодом 200, то попытка доставки уведомления считается неудачной.

Входные параметры

Поле Тип Описание
AccountNo String(30) Номер лицевого счета

- обязательные поля

Параметры уведомления о состоянии лицевого счёта

Поле Тип Описание
Amount Decimal(19, 2) Состояние лицевого счёта (разделитель между целой и дробной частью ",")
Surname String(30) Фамилия
FirstName String(30) Имя
Patronymic String(30) Отчество
City String(30) Город
Street String(30) Улица
House String(10) Дом
Building String(10) Корпус
Apartment String(10) Квартира
IsNameEditable Integer При оплате разрешено изменять ФИО плательщика 0 – нет, 1 – да
IsAddressEditable Integer При оплате разрешено изменять адрес плательщика 0 – нет, 1 – да
IsAmountEditable Integer При оплате разрешено изменять сумму оплаты 0 – нет, 1 – да
Info String(1024) Назначение платежа
Error.Msg String(512) Сообщение об ошибке. Отсутствует, если ошибки нет.
Msg - вложенное в Error поле (см пример).

- обязательные поля

Пример передаваемых данных на URL (запрос):
{
    "AccountNo" : "10"
}
            
Пример полученных данных от URL в случае успеха (ответ):
{
    "Amount" : "10",
    "Surname" : "Ivanov",
    "FirstName" : "Ivan",
    "Patronymic" : "Ivanovich",
    "City" : "Minsk",
    "Street" : "Frunze",
    "House" : "2",
    "Building" : "1",
    "Apartment" : "10",
    "IsNameEditable" : "0",
    "IsAddressEditable" : "0",
    "IsAmountEditable" : "0",
    "Info" : "info",
}
            
Пример полученных данных от URL в случае ошибки (ответ):
{
    "Error" : {
        "Msg": "Лицевой счет не найден"
    }
}
            

Пример исходного кода получения данных от сервера

                
namespace EripNotify.Models
{
    public class EripNotify
    {
        public string Data { get; set; }
        public string Signature { get; set; }
    }
}
namespace EripNotify.Controllers
{
    public class EripNotifyController : ApiController
    {
        private static readonly Encoding HashEncoding = Encoding.UTF8;
        private string _secretWord = "secretWord";
        private bool _useSignature = false;
        [HttpPost]
        public IHttpActionResult Test(Models.EripNotify model)
        {
            if (_useSignature)
            {
                // Проверяем цифровую подпись
                if (model.Signature != ComputeSignature(model.Data, _secretWord))
                {
                    // NOTE: Добавить обработку ошибки
                    // ...
                    return InternalServerError();
                }
            }
            // Преобразуем из JSON в Object
            var obj = JObject.Parse(model.Data);
            // NOTE: Выполняем действия с полученным объектом
            // ...
            return Ok();
        }
        // Функция генерации и проверки цифровой подписи
        public string ComputeSignature(string json, string secretWord)
        {
            var hmac = string.IsNullOrWhiteSpace(secretWord) ? 
                new HMACSHA1(HashEncoding.GetBytes(string.Empty)) : 
                new HMACSHA1(HashEncoding.GetBytes(secretWord));
            var hash = hmac.ComputeHash(HashEncoding.GetBytes(json));
            var result = new StringBuilder();
            foreach (var item in hash)
                result.Append(item.ToString("X2"));
            return result.ToString();
        }
    }
}
                    
                

Получать уведомления о зачислении средств на расчетный счет по URL

Проверка зачисления средств на расчетный счет по URL позволяет получать оповещений, что платеж был успешно выполнен.

Вызов адреса сайта происходит в момент совершения платежа в адрес производителя услуг. Вызываемый адрес сайта указывается в настройках личного кабинета.

Для этого необходимо выполнить следующие операции:
  1. Перейти в раздел настройки (пункт меню “Настройка”);
  2. Перейти на вкладку “Услуги”;
  3. В списке услуг для нужной услуги перейти на “Уведомления”;
  4. Установить опцию “Получать уведомления о зачислении средств на расчетный счет по URL”;
  5. Указать адрес вызова сайта в поле “URL для уведомлений о зачислении средств на расчетный счет” вида https://test.com/ (см. рисунок).
Настройка адреса сайт для доставки уведомления о платежах на сайт

Настройка адреса адрес сайт для доставки уведомления о оплате на Р\С на сайт


В уведомлении на сайт данные передаются POST-запросом. Во всех запросах передаются обязательные параметры:

  • Data – информация о платеже в JSON-формате;
  • Signature={hash} – цифровая подпись запроса, которая формируется на основании секретного слова (задается в личном кабинете) и передаваемых данных. Данный параметр передается в случае установки опции “Применять цифровую подпись”.

Сайт производителя услуг должен ответить HTTP-кодом 200 в случае успешной обработки запроса.

При включении опции “Применять цифровую подпись” будет формироваться цифровая подпись для передаваемых данных, которая позволяет контролировать целостность передаваемых данных (защита от MITM-атак). Цифровая подпись основана на алгоритме HMAC-SHA1, который описан в стандарте RFC 2104.

Параметр “Таймаут ожидания ответа” устанавливает время, которое сервер «Экспресс Платежи» будет ожидать ответа от сайта производителя услуг. Если в течение данного времени сервер производителя услуг не вернет ответ с HTTP-кодом 200, то попытка доставки уведомления считается неудачной.

Параметры уведомления о зачислении средств на расчетный счет по URL для EPOS

Поле Тип Описание
CmdType Integer Тип уведомления:
  • 5 - Зачисление средств на расчетный счет для EPOS
ServiceId Integer Идентификатор услуги
Currency String(8) Валюта
Amount Decimal(19,4) Оплаченная покупателем сумма
TransferAmount Decimal(19,4) Перечисленная ПУ сумма
BankComission Decimal(19,4) Комиссия рассчетного агента
EripComission Decimal(19,4) Комиссия агрегатора
Rate Decimal(19,4) Курс пересчета
TransactionId BIGINT Идентификатор транзации в ЕРИП
EripTransactionId INT Код транзакции агрегатора
DateResultUtc DateTime Дата завершения оплаты
DateVerifiedUtc DateTime Дата сверки по транзакции
BankCode Int Код банка
AuthType String(512) Тип авторизации плательщика
MemOrderDate DateTime Дата ведомости
MemOrderNum Int Номер мемориального ордера
AccountNumber String(512) Номер счета для оплаты
PaymentNo Int Номер платежа
Пример передаваемых данных на URL (запрос) E-POS:
        {
            "CmdType":5,
            "ServiceId":1111,
            "Currency":"BYN",
            "Amount":"0,10",
            "TransferAmount":"0,10",
            "BankComission":"0",
            "EripComission":"0",
            "AggregatorComission":"0",
            "Rate":"1",
            "TransactionId":3349077861,
            "EripTransactionId":1654138,
            "DateResultUtc":"20210304132422",
            "DateVerifiedUtc":"20210305033250",
            "BankCode":749,
            "AuthType":"MS",
            "MemOrderDate":"20210305100501",
            "MemOrderNum":6616,
            "AccountNumber":"22222-2-720072350",
            "PaymentNo":111
        }
                    

Параметры уведомления о зачислении средств на расчетный счет по URL для ЕРИП

Поле Тип Описание
CmdType Integer Тип уведомления:
  • 4 - Зачисление средств на расчетный счет для ЕРИП
InvoiceNumber String(30) Номер лицевого счета
CustomerFio String(99) ФИО
CustomerAddress String(99) Адрес потребителя услуг
MoneyAmmount Decimal(12,2) Сумма оплаты
PenaltyInterest Decimal(12,2) Сумма пени
TransferredMoneyAmount Decimal(12,2) Перечисленная сумма
PaymentDateTime DateTime Дата совершения операции
PaidMeterReading String(MAX) Оплаченные показания счетчиков
OperationNumberInAgentOffice BIGINT Учетный номер операции в расчетном агенте
OperationNumberInCentralOffice BIGINT Учетный номер операции в центральном узле
DeviceIdentifier String(30) Идентификатор терминала
MethodOfMoneyAuthorization String(10) Способ авторизации суммы
MoneyAuthorizationDeviceID String(30) Идентификатор средства авторизации суммы
WarrantForPaymentNumber BIGINT Номер платежного документа
TransferredDateTime DateTime Дата перечисления средств

Пример передаваемых данных на URL (запрос) ЕРИП:

        {
            "CmdType":4,
            "InvoiceNumber":"1661822215603",
            "CustomerFio":"Иванов Иван Иванович",
            "CustomerAddress":"",
            "MoneyAmmount":"6",
            "PenaltyInterest":"0",
            "TransferredMoneyAmount":"5,92",
            "PaymentDateTime":"20240807105503",
            "PaidMeterReading":"",
            "OperationNumberInAgentOffice":2220186187,
            "OperationNumberInCentralOffice":5310302791,
            "DeviceIdentifier":"MBR0002",
            "MethodOfMoneyAuthorization":"MS",
            "MoneyAuthorizationDeviceID":"4246419999992081",
            "WarrantForPaymentNumber":7116,
            "TransferredDateTime":"20240808000000"
        }
                    

Пример исходного кода получения данных от сервера

                
namespace EripNotify.Models
 {
     public class EripNotify
     {
         public string Data { get; set; }
         public string Signature { get; set; }
     }
 }
 namespace EripNotify.Controllers
 {
     public class EripNotifyController : ApiController
     {
         private static readonly Encoding HashEncoding = Encoding.UTF8;
         private string _secretWord = "secretWord";
         private bool _useSignature = false;
         [HttpPost]
         public IHttpActionResult Test(Models.EripNotify model)
         {
             if (_useSignature)
             {
                 // Проверяем цифровую подпись
                 if (model.Signature != ComputeSignature(model.Data, _secretWord))
                 {
                     // NOTE: Добавить обработку ошибки
                     // ...
                     return InternalServerError();
                 }
             }
             // Преобразуем из JSON в Object
             var obj = JObject.Parse(model.Data);
             // NOTE: Выполняем действия с полученным объектом
             // ...
             return Ok();
         }
         // Функция генерации и проверки цифровой подписи
         public string ComputeSignature(string json, string secretWord)
         {
             var hmac = string.IsNullOrWhiteSpace(secretWord) ? 
                 new HMACSHA1(HashEncoding.GetBytes(string.Empty)) : 
                 new HMACSHA1(HashEncoding.GetBytes(secretWord));
             var hash = hmac.ComputeHash(HashEncoding.GetBytes(json));
             var result = new StringBuilder();
             foreach (var item in hash)
                 result.Append(item.ToString("X2"));
             return result.ToString();
         }
     }
 }
                            
                        

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

Формирование цифровой подписи для передаваемых данных обеспечивает целостность информации и гарантирует, что передаваемые данные не были изменены посторонними лицами в процессе передачи. Цифровая подпись данных осуществляется с помощью алгоритма HMAC-SHA1, который описан в стандарте RFC 2104.

При использовании цифровой подписи для запросов на сервер необходимо объединить все параметры запроса в одну строку в строго определенном порядке. Для объединенной строки необходимо рассчитать цифровую подпись, которая указывается при запросе в параметре signature. Сервер при получении входящего запроса выполняет проверку цифровой подписи (параметра signature) и параметров запроса.

Пример формирования строки запроса при использовании цифровой подписи для получения списка счетов: https://api.express-pay.by/v1/invoices?token={Token}&signature={Hash}.

Для усиления безопасности возможно формирование цифровой подписи с помощью секретного слова, которое известно только серверу и клиенту. Чтобы задать секретное слово, необходимо выполнить следующие операции в личном кабинете:

  1. Перейти в раздел настройки (пункт меню “Настройка”);
  2. Перейти на вкладку “Услуги”
  3. В списке услуг для нужной услуги перейти к настройкам API;
  4. Укажите секретное слово и никому его не передавайте (см. рисунок).
Использование цифровой подписи и задание секретного слова

Использование цифровой подписи и задание секретного слова

В случае успешной проверки выполняется обработка запроса. Если параметры запроса не соответствуют цифровой подписи, то отсылается уведомление об ошибке и запрос не обрабатывается сервером.

Порядок следования параметров запросов следующий:
  1. Добавление счета
    "token",
    "accountno",
    "amount",
    "currency",
    "expiration",
    "info",
    "surname",
    "firstname",
    "patronymic",
    "city",
    "street",
    "house",
    "building",
    "apartment",
    "isnameeditable",
    "isaddresseditable",
    "isamounteditable",
    "emailnotification",
    "returninvoiceurl"
    
  2. Изменение счета
    "token",
    "invoiceid",
    "amount",
    "currency",
    "expiration",
    "info",
    "surname",
    "firstname",
    "patronymic",
    "city",
    "street",
    "house",
    "building",
    "apartment",
    "isnameeditable",
    "isaddresseditable",
    "isamounteditable",
    "emailnotification",
    "smsphone"
    
  3. Детальная информация счета
    "token",
    "id",
    "returninvoiceurl"
    
  4. Отменить счет
    "token",
    "id"
    
  5. Статус счета
    "token",
    "id"
    
  6. Список счетов
    "token",
    "from",
    "to",
    "accountno",
    "status"
    
  7. Список платежей
    "token",
    "from",
    "to",
    "accountno"
    
  8. Детали по платежу
    "token",
    "id"
    
  9. Детали по балансу
    "token",
    "accountno"
    
  10. Выставление счета по карте
    "token",
    "accountno",                 
    "expiration",             
    "amount",                  
    "currency",
    "info",      
    "returnurl",
    "failurl",
    "language",
    "sessiontimeoutsecs",
    "expirationdate"
    
  11. Форма оплаты
    "token",
    "CardInvoiceNo"
    
  12. Статус счета по карте
    "token",
    "CardInvoiceNo",
    "language"
    
  13. Отмена счета по карте
    "token",
    "CardInvoiceNo"
    
  14. Генерация QR-кода для счета
    "token",
    "invoiceid",
    "viewtype",
    "imagewidth",
    "imageheight"
    
  15. Генерация QR-кода для лицевого счета
    "token",
    "accountnumber",
    "amount",
    "viewtype",
    "imagewidth",
    "imageheight"
    
  16. Выставление счета в системе ЕРИП (для платежных модулей)
    "token",
    "serviceid",
    "accountno",
    "amount",
    "currency",
    "expiration",
    "info",
    "surname",
    "firstname",
    "patronymic",
    "city",
    "street",
    "house",
    "building",
    "apartment",
    "isnameeditable",
    "isaddresseditable",
    "isamounteditable",
    "emailnotification",
    "smsphone",
    "returntype",
    "returnurl",
    "failurl",
    "returninvoiceurl"
    
  17. Выставление счета по карте (для платежных модулей)
    "token",
    "serviceid",
    "accountno",
    "expiration",
    "amount",
    "currency",
    "info",
    "returnurl",
    "failurl",
    "language",
    "sessiontimeoutsecs",
    "expirationdate",
    "returntype",
    "returninvoiceurl",
    "customerid"
    
  18. Привязка карты
    "token",
    "serviceid",
    "writeoffperiod",
    "amount",
    "currency",
    "info",
    "returnurl",
    "failurl",
    "language",
    "returntype"
    
  19. Отвязка карты и информация о карте
    "token",
    "serviceid",
    "customerId"
    
  20. Оплата по привязанной карте
    "token",
    "customerid",
    "serviceid",
    "amount",
    "info"
    

Примечание: Разделителем целой и дробной части в сумме (параметр amount) является запятая.


namespace ExPay.Api
{
    public static class AppSettings
    {
        public const string ServiceUrl = "https://api.express-pay.by/v1/";
        public const string Token = "a75b74cbcfe446509e8ee874f421bd63"; // API-ключ
        public static readonly Encoding DefaultEncoding = Encoding.UTF8;
    }
    public static class SignatureHelper
    {
        private static readonly Encoding HashEncoding = Encoding.UTF8;
        // Порядок следования полей при вычислении цифровой подписи.
        // Внимание! Для корректной работы порядок изменять нельзя
        private static readonly Dictionary<string, string[]> Mapping = new Dictionary<string, string[]>
        {
            {
                "add-invoice", new[]
                {
                    "token",
                    "accountno",
                    "amount",
                    "currency",
                    "expiration",
                    "info",
                    "surname",
                    "firstname",
                    "patronymic",
                    "city",
                    "street",
                    "house",
                    "building",
                    "apartment",
                    "isnameeditable",
                    "isaddresseditable",
                    "isamounteditable",
                    "emailnotification",
                    "returninvoiceurl"
                }
            },
            {
                "get-details-invoice", new[]
                {
                    "token",
                    "id",
                    "returninvoiceurl"
                }
            },
            {
                "cancel-invoice", new[]
                {
                    "token",
                    "id"
                }
            },
            {
                "status-invoice", new[]
                {
                    "token",
                    "id"
                }
            },
            {
                "get-list-invoices", new[]
                {
                    "token",
                    "from",
                    "to",
                    "accountno",
                    "status"
                }
            },
            {
                "get-list-payments", new[]
                {
                    "token",
                    "from",
                    "to",
                    "accountno"
                }
            },
            {
                "get-details-payment", new[]
                {
                    "token",
                    "id"
                }
            },
            {
                "balance", new[]
                {
                    "token",
                    "accountno"
                }
            },
            {
                "add-card-invoice", new[]
                {
                    "token",
                    "accountno",                 
                    "expiration",             
                    "amount",                  
                    "currency",
                    "info",      
                    "returnurl",
                    "failurl",
                    "language",
                    "pageview",
                    "sessiontimeoutsecs",
                    "expirationdate"
                }
            },
            {
                "card-invoice-form", new[]
                {
                    "token",
                    "CardInvoiceNo"
                }
            },
            {
                "status-card-invoice", new[]
                {
                    "token",
                    "CardInvoiceNo",
                    "language"
                }
            },
            {
                "reverse-card-invoice", new[]
                {
                    "token",
                    "CardInvoiceNo"
                }
            },
            {
                "get-qr-code", new[]
                {
                    "token",
                    "invoiceid",
                    "viewtype",
                    "imagewidth",
                    "imageheight"
                }
            },
            {
                "add-web-invoice",new[]
                {
                    "token",
                    "serviceid",
                    "accountno",
                    "amount",   
                    "currency",
                    "expiration",
                    "info",
                    "surname",
                    "firstname",
                    "patronymic",
                    "city",
                    "street",
                    "house",
                    "building",
                    "apartment",
                    "isnameeditable",
                    "isaddresseditable",
                    "isamounteditable",
                    "emailnotification",
                    "smsphone",
                    "returntype",
                    "returnurl",
                    "failurl",
                    "returninvoiceurl"
                }
            },
            {
                "add-webcard-invoice",new[]
                {
                    "token",
                    "serviceid",
                    "accountno",
                    "expiration",   
                    "amount",
                    "currency",
                    "info",
                    "returnurl",
                    "failurl",
                    "language",
                    "sessiontimeoutsecs",
                    "expirationdate",
                    "returntype",
                    "returninvoiceurl"
                }
            }

        };
        public static string Compute(Dictionary<string, string> requestParams, string secretWord, string action)
        {
            var normalizedParams = requestParams
                .ToDictionary(k => k.Key.ToLower(), v => v.Value);
            var cmdFields = Mapping[action];
            var builder = new StringBuilder();
            foreach (var cmdField in cmdFields)
            {
                if (normalizedParams.ContainsKey(cmdField))
                    builder.Append(normalizedParams[cmdField]);
            }
            HMACSHA1 hmac;
            if (string.IsNullOrWhiteSpace(secretWord))
            {
                // В алгоритме всегда должно быть задан ключ шифрования. Если используется конструктор по умолчанию, то ключ генерируется автоматически,
                // что нам не подходит
                hmac = new HMACSHA1(HashEncoding.GetBytes(string.Empty));
            }
            else
            {
                hmac = new HMACSHA1(HashEncoding.GetBytes(secretWord));
            }
            var hash = hmac.ComputeHash(
                HashEncoding.GetBytes(builder.ToString()));
            var result = new StringBuilder();
            foreach (var item in hash)
            {
                result.Append(item.ToString("X2"));
            }
            return result.ToString();
        }
    }
}
						

Тестовый стенд

При тестировании API вместо адреса https://api.express-pay.by необходимо использовать адрес тестового стенда https://sandbox-api.express-pay.by. В качестве тестовых данных используйте данные, приведенные ниже.

URL: https://sandbox-api.express-pay.by/v1/


Тестовые API ключи (токены)

Номер услуги API ключ Разрешить использование API Применять цифровую подпись Секретное слово
1 a75b74cbcfe446509e8ee874f421bd63 Нет Нет
2 a75b74cbcfe446509e8ee874f421bd64 Да Нет
3 a75b74cbcfe446509e8ee874f421bd65 Да Да
4 a75b74cbcfe446509e8ee874f421bd66 Да Да sandbox.expresspay.by

Тестовые API ключи (токены) для интернет-эквайринга

Номер услуги API ключ Разрешить использование API Применять цифровую подпись Секретное слово
5 a75b74cbcfe446509e8ee874f421bd67 Да Да
6 a75b74cbcfe446509e8ee874f421bd68 Да Да sandbox.expresspay.by

Система ЕРИП

Тестовые счета на оплату

Номер услуги API ключ Номер счета на оплату Номер лицевого счета Дата выставления счета Статус
3 a75b74cbcfe446509e8ee874f421bd65 1 10 01-01-2015 12:00 Ожидает оплаты
3 a75b74cbcfe446509e8ee874f421bd65 2 20 01-02-2015 12:00 Оплачен
3 a75b74cbcfe446509e8ee874f421bd65 3 30 01-03-2015 12:00 Оплачен частично
3 a75b74cbcfe446509e8ee874f421bd65 4 40 01-04-2015 12:00 Ожидает оплаты
3 a75b74cbcfe446509e8ee874f421bd65 5 50 01-05-2015 12:00 Оплачен частично
3 a75b74cbcfe446509e8ee874f421bd65 6 60 01-06-2015 12:00 Отменен
2 a75b74cbcfe446509e8ee874f421bd64 7 70 01-01-2015 12:00 Ожидает оплаты
2 a75b74cbcfe446509e8ee874f421bd64 8 80 01-02-2015 12:00 Оплачен
2 a75b74cbcfe446509e8ee874f421bd64 9 90 01-03-2015 12:00 Оплачен частично
2 a75b74cbcfe446509e8ee874f421bd64 10 100 01-04-2015 12:00 Ожидает оплаты
2 a75b74cbcfe446509e8ee874f421bd64 11 110 01-05-2015 12:00 Оплачен частично
2 a75b74cbcfe446509e8ee874f421bd64 12 120 01-06-2015 12:00 Отменен

Тестовые платежи

Номер услуги API ключ Номер платежа Номер лицевого счета Дата платежа
3 a75b74cbcfe446509e8ee874f421bd65 1 10 01-01-2015 12:00
3 a75b74cbcfe446509e8ee874f421bd65 2 20 01-02-2015 12:00
3 a75b74cbcfe446509e8ee874f421bd65 3 30 01-03-2015 12:00
2 a75b74cbcfe446509e8ee874f421bd64 4 40 01-04-2015 12:00
2 a75b74cbcfe446509e8ee874f421bd64 5 50 01-05-2015 12:00
2 a75b74cbcfe446509e8ee874f421bd64 6 60 01-06-2015 12:00

Интернет-эквайринг

Тестовые счета на оплату банковской картой

API ключ Номер счета на оплату Статус счета по банковской карте Запрет сторнирования
a75b74cbcfe446509e8ee874f421bd64 100 Счет зарегистрирован, но не оплачен Да
a75b74cbcfe446509e8ee874f421bd64 101 Предавторизованная сумма захолдирована (для двухстадийных платежей) Да
a75b74cbcfe446509e8ee874f421bd64 102 Проведена полная авторизация суммы счета Нет
a75b74cbcfe446509e8ee874f421bd64 103 Авторизация отменена Нет
a75b74cbcfe446509e8ee874f421bd64 104 По транзакции была проведена операция возврата Нет
a75b74cbcfe446509e8ee874f421bd64 105 Инициирована авторизация через ACS банка-эмитента Да
a75b74cbcfe446509e8ee874f421bd64 106 Авторизация отклонена Да
a75b74cbcfe446509e8ee874f421bd66 100 Счет зарегистрирован, но не оплачен Да
a75b74cbcfe446509e8ee874f421bd66 101 Предавторизованная сумма захолдирована (для двухстадийных платежей) Да
a75b74cbcfe446509e8ee874f421bd66 102 Проведена полная авторизация суммы счета Нет
a75b74cbcfe446509e8ee874f421bd66 103 Авторизация отменена Нет
a75b74cbcfe446509e8ee874f421bd66 104 По транзакции была проведена операция возврата Нет
a75b74cbcfe446509e8ee874f421bd66 105 Инициирована авторизация через ACS банка-эмитента Да
a75b74cbcfe446509e8ee874f421bd66 106 Авторизация отклонена Да

Система E-POS

Тестовые счета на оплату

Номер услуги API ключ Номер счета на оплату Номер лицевого счета Дата выставления счета Статус
7 a75b74cbcfe446509e8ee874f421bd69 100 100 20-06-2020 12:00 Ожидает оплаты