Введение в Express API
Программный интерфейс для приёма платежей на вашем сайте
Express API — это RESTful интерфейс для интеграции платежей IWEXPAY в ваше приложение. Он позволяет программно создавать платежи, отслеживать их статус и получать уведомления об оплате.
Возможности API
OAuth2 Аутентификация
Безопасная авторизация с использованием access token
Несколько методов оплаты
Mts (электронный кошелёк), Bank (банковский перевод)
Webhooks (IPN)
Мгновенные уведомления о статусе платежа
Rate Limiting
Защита от злоупотреблений с гибкими лимитами
Базовый URL
https://iwexpay.com
Формат данных
Все запросы и ответы используют формат JSON. Обязательно указывайте заголовки:
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token}
Поддерживаемые валюты
| Код | Валюта | Мин. сумма |
|---|---|---|
RUB | Российский рубль | 100.00 |
USD | Доллар США | 1 |
EUR | Евро | 1 |
Быстрый старт
Создайте первый платёж за 5 минут
Получите учётные данные
Войдите в личный кабинет IWEXPAY → Юридическое лицо → Настройки (значок шестерёнки)
Скопируйте Client ID и Client Secret
Получите access token
curl -X POST https://iwexpay.com/merchant/api/verify \
-H "Content-Type: application/json" \
-d '{
"client_id": "ваш_client_id",
"client_secret": "ваш_client_secret"
}'
{
"status": "success",
"message": "Client Verified",
"data": {
"access_token": "z3iRLpWzCTWKKJLNQLL7gEDcZG"
}
}
Создайте платёж
curl -X POST https://iwexpay.com/merchant/api/transaction-info \
-H "Content-Type: application/json" \
-H "Authorization: Bearer z3iRLpWzCTWKKJLNQLL7gEDcZG" \
-d '{
"payer": "IWEXPAY",
"amount": 1500.00,
"currency": "RUB",
"successUrl": "https://ваш-сайт.ru/success",
"cancelUrl": "https://ваш-сайт.ru/cancel"
}'
{
"status": "success",
"message": "Информация о транзакции успешно создана!",
"data": {
"approvedUrl": "https://iwexpay.com/merchant/payment?grant_id=12345678&token=ABC123xyz"
}
}
Перенаправьте пользователя
Перенаправьте покупателя на approvedUrl для оплаты
// После получения ответа от API
header("Location: " . $response['data']['approvedUrl']);
exit;
Готово!
После оплаты пользователь будет перенаправлен на ваш successUrl или cancelUrl
Настройте Webhooks для получения уведомлений о статусе платежа в реальном времени.
Аутентификация
OAuth2 Client Credentials Flow
Как это работает
Express API использует OAuth2 аутентификацию. Для выполнения запросов вам нужен access token, который получается путём обмена ваших учётных данных.
Учётные данные
| Параметр | Описание | Где получить |
|---|---|---|
client_id |
Уникальный идентификатор вашего приложения | Личный кабинет → Юр. лицо → Настройки |
client_secret |
Секретный ключ для аутентификации | Личный кабинет → Юр. лицо → Настройки |
Никогда не передавайте client_secret в клиентском коде (JavaScript, мобильные приложения). Храните его только на сервере.
Срок действия токена
Access token действителен в течение 24 часов. После истечения срока необходимо получить новый токен.
Получение токена
POST /merchant/api/verify
https://iwexpay.com/merchant/api/verify
Параметры запроса
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
client_id |
string | Да | Идентификатор вашего приложения |
client_secret |
string | Да | Секретный ключ приложения |
Пример запроса
curl -X POST https://iwexpay.com/merchant/api/verify \
-H "Content-Type: application/json" \
-d '{
"client_id": "PrX7xvDFkBSPY0Yow5QW1WtRQUfBCm",
"client_secret": "74H7QvxWeV73ap7UG1Ma45LkDcG5JP..."
}'
<?php
$data = [
'client_id' => 'ваш_client_id',
'client_secret' => 'ваш_client_secret'
];
$ch = curl_init('https://iwexpay.com/merchant/api/verify');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$result = json_decode($response, true);
if ($result['status'] === 'success') {
$accessToken = $result['data']['access_token'];
echo "Token: " . $accessToken;
}
curl_close($ch);
// Node.js / Server-side only!
const response = await fetch('https://iwexpay.com/merchant/api/verify', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json'
},
body: JSON.stringify({
client_id: 'ваш_client_id',
client_secret: 'ваш_client_secret'
})
});
const result = await response.json();
if (result.status === 'success') {
const accessToken = result.data.access_token;
console.log('Token:', accessToken);
}
Успешный ответ
{
"status": "success",
"message": "Client Verified",
"data": {
"access_token": "z3iRLpWzCTWKKJLNQLL7gEDcZG"
}
}
Ошибки
{
"status": "error",
"message": "Unauthorized: Invalid client credentials"
}
Создание платежа
POST /merchant/api/transaction-info
https://iwexpay.com/merchant/api/transaction-info
Заголовки
Authorization: Bearer {access_token}
Content-Type: application/json
Параметры запроса
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
payer |
string | Да | Название платёжной системы. Используйте "IWEXPAY" |
amount |
number | Да | Сумма платежа (например: 1500.00) |
currency |
string | Да | Код валюты: RUB, USD, EUR |
successUrl |
string | Да | URL для перенаправления после успешной оплаты |
cancelUrl |
string | Да | URL для перенаправления при отмене |
Пример запроса
curl -X POST https://iwexpay.com/merchant/api/transaction-info \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer {access_token}" \
-d '{
"payer": "IWEXPAY",
"amount": 1500.00,
"currency": "RUB",
"successUrl": "https://ваш-сайт.ru/payment/success",
"cancelUrl": "https://ваш-сайт.ru/payment/cancel"
}'
<?php
$accessToken = 'ваш_access_token';
$data = [
'payer' => 'IWEXPAY',
'amount' => 1500.00,
'currency' => 'RUB',
'successUrl' => 'https://ваш-сайт.ru/payment/success',
'cancelUrl' => 'https://ваш-сайт.ru/payment/cancel'
];
$ch = curl_init('https://iwexpay.com/merchant/api/transaction-info');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer ' . $accessToken
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$result = json_decode($response, true);
if ($result['status'] === 'success') {
// Перенаправляем пользователя на страницу оплаты
header('Location: ' . $result['data']['approvedUrl']);
exit;
}
curl_close($ch);
// Node.js / Server-side only!
const accessToken = 'ваш_access_token';
const response = await fetch('https://iwexpay.com/merchant/api/transaction-info', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`
},
body: JSON.stringify({
payer: 'IWEXPAY',
amount: 1500.00,
currency: 'RUB',
successUrl: 'https://ваш-сайт.ru/payment/success',
cancelUrl: 'https://ваш-сайт.ru/payment/cancel'
})
});
const result = await response.json();
if (result.status === 'success') {
// Перенаправляем пользователя на страницу оплаты
window.location.href = result.data.approvedUrl;
}
Успешный ответ
{
"status": "success",
"message": "Информация о транзакции успешно создана!",
"data": {
"approvedUrl": "https://iwexpay.com/merchant/payment?grant_id=52283195&token=T3LM4V0aWy70pxN3DEiy"
}
}
Параметры ответа
| Поле | Описание |
|---|---|
approvedUrl |
URL страницы оплаты. Перенаправьте покупателя на этот URL. |
grant_id |
Уникальный идентификатор транзакции (в URL) |
token |
Токен безопасности транзакции (в URL) |
Сценарии использования
Вы можете позволить пользователю самому указывать сумму платежа (например, для пополнения баланса, донатов, произвольных платежей). Сумма собирается на вашем сайте и передаётся в API при создании транзакции.
Схема работы:
Пример: HTML форма на вашем сайте
<!-- Вариант 1: Произвольная сумма -->
<form action="/pay" method="POST">
<label>Сумма пополнения:</label>
<input type="number" name="amount" min="100" max="100000" placeholder="Введите сумму">
<button type="submit">Оплатить</button>
</form>
<!-- Вариант 2: Фиксированные варианты -->
<form action="/pay" method="POST">
<label>Выберите сумму:</label>
<select name="amount">
<option value="100">100 ₽</option>
<option value="500">500 ₽</option>
<option value="1000">1 000 ₽</option>
<option value="5000">5 000 ₽</option>
</select>
<button type="submit">Оплатить</button>
</form>
Пример: Серверный обработчик
# Пользователь ввёл сумму 2500 на вашем сайте
# Ваш сервер передаёт её в IWEXPAY API:
AMOUNT=2500 # <-- сумма от пользователя
curl -X POST https://iwexpay.com/merchant/api/transaction-info \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer {access_token}" \
-d '{
"payer": "IWEXPAY",
"amount": '"$AMOUNT"',
"currency": "RUB",
"successUrl": "https://ваш-сайт.ru/success",
"cancelUrl": "https://ваш-сайт.ru/cancel"
}'
# Ответ содержит approvedUrl - перенаправьте пользователя туда
<?php
// /pay endpoint на вашем сервере
// 1. Получаем сумму от пользователя
$amount = (float) $_POST['amount'];
// 2. Валидация суммы (обязательно!)
if ($amount < 100 || $amount > 100000) {
die('Сумма должна быть от 100 до 100 000 рублей');
}
// 3. Получаем access_token
$token = getAccessToken(); // ваша функция аутентификации
// 4. Создаём транзакцию с суммой от пользователя
$ch = curl_init('https://iwexpay.com/merchant/api/transaction-info');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Authorization: Bearer ' . $token
],
CURLOPT_POSTFIELDS => json_encode([
'payer' => 'IWEXPAY',
'amount' => $amount, // <-- сумма от пользователя
'currency' => 'RUB',
'successUrl' => 'https://ваш-сайт.ru/success',
'cancelUrl' => 'https://ваш-сайт.ru/cancel'
])
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
// 5. Перенаправляем на страницу оплаты
header('Location: ' . $response['data']['approvedUrl']);
exit;
// Node.js / Express обработчик
// POST /pay endpoint на вашем сервере
app.post('/pay', async (req, res) => {
// 1. Получаем сумму от пользователя
const amount = parseFloat(req.body.amount);
// 2. Валидация суммы
if (amount < 100 || amount > 100000) {
return res.status(400).send('Сумма должна быть от 100 до 100 000 рублей');
}
// 3. Получаем access_token
const token = await getAccessToken();
// 4. Создаём транзакцию с суммой от пользователя
const response = await fetch('https://iwexpay.com/merchant/api/transaction-info', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': `Bearer ${token}`
},
body: JSON.stringify({
payer: 'IWEXPAY',
amount: amount, // <-- сумма от пользователя
currency: 'RUB',
successUrl: 'https://ваш-сайт.ru/success',
cancelUrl: 'https://ваш-сайт.ru/cancel'
})
});
const result = await response.json();
// 5. Перенаправляем на страницу оплаты
res.redirect(result.data.approvedUrl);
});
Сумма фиксируется в момент создания транзакции. На странице оплаты IWEXPAY пользователь не может изменить сумму. Обязательно валидируйте сумму на сервере (минимум/максимум).
Методы оплаты
Доступные способы оплаты для ваших клиентов
Mts (Электронный кошелёк)
Мгновенная оплата с баланса пользователя IWEXPAY
- Подтверждение: Мгновенное
- Статус после оплаты:
success - Webhook:
payment.success
Bank (Банковский перевод)
Оплата банковским переводом с ручным подтверждением
- Подтверждение: После проверки администратором
- Статус после оплаты:
pending→success - Webhook:
payment.pending, затемpayment.successилиpayment.rejected
Процесс оплаты Bank
Пользователь выбирает Bank
На странице оплаты показываются банковские реквизиты
Пользователь совершает перевод
Через банковское приложение или интернет-банк
Пользователь нажимает "Я оплатил"
Статус: pending, отправляется webhook payment.pending
Администратор проверяет платёж
Подтверждает или отклоняет транзакцию
Финальный статус
Отправляется webhook payment.success или payment.rejected
Для Bank платежей обязательно настройте Webhooks, чтобы получать уведомления о подтверждении платежа администратором.
Статус платежей
Получение информации о платежах
Список платежей
https://iwexpay.com/merchant/api/payments
Параметры фильтрации
| Параметр | Тип | Описание |
|---|---|---|
status |
string | Фильтр по статусу: pending, success, cancelled |
payment_method |
string | Метод оплаты: mts, bank |
currency |
string | Валюта: RUB, USD, EUR |
date_from |
string | Начальная дата (YYYY-MM-DD) |
date_to |
string | Конечная дата (YYYY-MM-DD) |
page |
integer | Номер страницы (по умолчанию: 1) |
limit |
integer | Количество записей (макс: 100) |
Пример запроса
curl -X GET "https://iwexpay.com/merchant/api/payments?status=success&limit=10" \
-H "Authorization: Bearer {access_token}" \
-H "Accept: application/json"
<?php
$accessToken = 'ваш_access_token';
$params = http_build_query([
'status' => 'success',
'limit' => 10
]);
$ch = curl_init('https://iwexpay.com/merchant/api/payments?' . $params);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Accept: application/json',
'Authorization: Bearer ' . $accessToken
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$result = json_decode($response, true);
if ($result['status'] === 'success') {
foreach ($result['data']['items'] as $payment) {
echo "Платёж #{$payment['uuid']}: {$payment['amount']} {$payment['currency']}\n";
}
}
curl_close($ch);
// Node.js / Server-side only!
const accessToken = 'ваш_access_token';
const params = new URLSearchParams({
status: 'success',
limit: 10
});
const response = await fetch(`https://iwexpay.com/merchant/api/payments?${params}`, {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`
}
});
const result = await response.json();
if (result.status === 'success') {
result.data.items.forEach(payment => {
console.log(`Платёж #${payment.uuid}: ${payment.amount} ${payment.currency}`);
});
}
Ответ
{
"status": "success",
"data": {
"items": [
{
"uuid": "abc123-def456-ghi789",
"order_no": "ORD-12345",
"amount": "1500.00",
"currency": "RUB",
"payment_method": "mts",
"payment_status": "success",
"created_at": "2025-12-06T12:30:00Z"
}
],
"pagination": {
"total": 150,
"page": 1,
"limit": 10,
"pages": 15
}
}
}
Детали платежа
https://iwexpay.com/merchant/api/payments/{uuid}
Ответ
{
"status": "success",
"data": {
"uuid": "abc123-def456-ghi789",
"order_no": "ORD-12345",
"amount": "1500.00",
"currency": "RUB",
"fee": "15.00",
"total": "1485.00",
"payer": "user@example.com",
"payment_method": "mts",
"payment_status": "success",
"created_at": "2025-12-06T12:30:00Z",
"updated_at": "2025-12-06T12:30:05Z"
}
}
Жизненный цикл платежа
Статусы и переходы
Статусы платежа
| Статус | Описание | Mts | Bank |
|---|---|---|---|
pending |
Ожидает оплаты или подтверждения | - | Да |
success |
Платёж успешно завершён | Да | Да |
cancelled |
Отменён пользователем | Да | Да |
rejected |
Отклонён администратором | - | Да |
expired |
Истёк срок действия (30 минут) | Да | Да |
Webhooks
Получайте уведомления о событиях в реальном времени
Что такое Webhooks?
Webhooks (также известные как IPN - Instant Payment Notification) — это HTTP-уведомления, которые IWEXPAY отправляет на ваш сервер при изменении статуса платежа.
Преимущества
Мгновенные уведомления
Получайте информацию сразу после события
Надёжная доставка
Автоматические повторные попытки при сбоях
Подпись HMAC
Криптографическая верификация источника
Для Bank платежей webhooks — единственный способ узнать о подтверждении платежа администратором.
Настройка Webhooks
API для управления webhook подписками
Создание webhook
https://iwexpay.com/merchant/api/webhooks
Параметры
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
url |
string | Да | URL для получения уведомлений (HTTPS) |
events |
array | Да | Список событий для подписки |
Пример
curl -X POST https://iwexpay.com/merchant/api/webhooks \
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/json" \
-d '{
"url": "https://ваш-сайт.ru/webhooks/iwexpay",
"events": ["payment.success", "payment.pending", "payment.cancelled"]
}'
<?php
$accessToken = 'ваш_access_token';
$data = [
'url' => 'https://ваш-сайт.ru/webhooks/iwexpay',
'events' => ['payment.success', 'payment.pending', 'payment.cancelled']
];
$ch = curl_init('https://iwexpay.com/merchant/api/webhooks');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer ' . $accessToken
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$result = json_decode($response, true);
if ($result['status'] === 'success') {
$webhookSecret = $result['data']['secret'];
// ВАЖНО: Сохраните secret для верификации подписи!
echo "Webhook создан! Secret: " . $webhookSecret;
}
curl_close($ch);
// Node.js / Server-side only!
const accessToken = 'ваш_access_token';
const response = await fetch('https://iwexpay.com/merchant/api/webhooks', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': `Bearer ${accessToken}`
},
body: JSON.stringify({
url: 'https://ваш-сайт.ru/webhooks/iwexpay',
events: ['payment.success', 'payment.pending', 'payment.cancelled']
})
});
const result = await response.json();
if (result.status === 'success') {
const webhookSecret = result.data.secret;
// ВАЖНО: Сохраните secret для верификации подписи!
console.log('Webhook создан! Secret:', webhookSecret);
}
Ответ
{
"status": "success",
"message": "Webhook created successfully",
"data": {
"id": 42,
"url": "https://ваш-сайт.ru/webhooks/iwexpay",
"events": ["payment.success", "payment.pending", "payment.cancelled"],
"secret": "whsec_abc123xyz789",
"is_active": true
}
}
Секретный ключ secret показывается только один раз при создании. Сохраните его для верификации подписи.
Другие операции
| Операция | Метод | Endpoint |
|---|---|---|
| Список webhooks | GET | /merchant/api/webhooks |
| Получить webhook | GET | /merchant/api/webhooks/{id} |
| Обновить webhook | PUT | /merchant/api/webhooks/{id} |
| Удалить webhook | DELETE | /merchant/api/webhooks/{id} |
| Список событий | GET | /merchant/api/webhooks/events |
События Webhooks
Доступные типы событий для подписки
Список событий
| Событие | Описание | Mts | Bank |
|---|---|---|---|
payment.pending |
Платёж ожидает подтверждения | - | Да |
payment.success |
Платёж успешно завершён | Да | Да |
payment.cancelled |
Платёж отменён пользователем | Да | Да |
payment.rejected |
Платёж отклонён администратором | - | Да |
payment.expired |
Истёк срок действия платежа | Да | Да |
Формат payload
{
"event": "payment.success",
"timestamp": "2025-12-06T12:30:00Z",
"data": {
"transaction_id": "abc123-def456-ghi789",
"order_id": "ORD-12345",
"merchant_id": 42,
"amount": 1500.00,
"currency": "RUB",
"fee": 15.00,
"payment_method": "mts",
"status": "success",
"payer_email": "user@example.com"
}
}
HTTP заголовки
| Заголовок | Описание |
|---|---|
X-Webhook-Signature |
HMAC-SHA256 подпись payload |
X-Webhook-Event |
Тип события |
X-Webhook-Timestamp |
Время отправки (Unix timestamp) |
Верификация подписи
Проверка подлинности webhook уведомлений
Алгоритм подписи
Подпись создаётся алгоритмом HMAC-SHA256 с использованием вашего secret ключа.
signature = HMAC-SHA256(secret, payload_json)
Пример верификации (PHP)
<?php
// Ваш секретный ключ (сохраните его при создании webhook)
$secret = 'whsec_abc123xyz789';
// Получаем данные
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
// Вычисляем ожидаемую подпись
$expectedSignature = hash_hmac('sha256', $payload, $secret);
// Сравниваем подписи
if (!hash_equals($expectedSignature, $signature)) {
http_response_code(401);
exit('Invalid signature');
}
// Подпись верна, обрабатываем событие
$event = json_decode($payload, true);
switch ($event['event']) {
case 'payment.success':
// Платёж успешен - выполняем заказ
$transactionId = $event['data']['transaction_id'];
$amount = $event['data']['amount'];
// ... ваша логика
break;
case 'payment.pending':
// Bank платёж ожидает подтверждения
break;
case 'payment.rejected':
// Bank платёж отклонён
break;
}
// Возвращаем 200 OK
http_response_code(200);
echo 'OK';
Повторные попытки
При ошибке доставки (HTTP код не 2xx) IWEXPAY повторит отправку:
- 1-я повторная попытка: через 1 минуту
- 2-я повторная попытка: через 5 минут
- 3-я повторная попытка: через 30 минут
Всегда возвращайте HTTP 200 как можно быстрее. Обрабатывайте события асинхронно (через очередь задач).
Безопасность
Rate limiting и лучшие практики
Rate Limiting
API имеет ограничения на количество запросов для защиты от злоупотреблений:
| Endpoint | Лимит | Период |
|---|---|---|
/merchant/api/verify |
100 запросов | 1 минута |
/merchant/api/transaction-info |
1000 запросов | 1 минута |
/merchant/api/payments |
2000 запросов | 1 минута |
/merchant/api/webhooks/* |
100 запросов | 1 минута |
Превышение лимита
{
"status": "error",
"message": "Too many requests. Please slow down.",
"retry_after": 60
}
Best Practices
Храните секреты на сервере
Никогда не используйте client_secret в клиентском коде
Используйте HTTPS
Все URL (successUrl, cancelUrl, webhook URL) должны быть HTTPS
Верифицируйте webhooks
Всегда проверяйте подпись HMAC-SHA256 перед обработкой
Кэшируйте токен
Access token действует 24 часа — не запрашивайте новый перед каждым запросом
Коды ошибок
HTTP статусы и коды ошибок API
HTTP статус коды
| Код | Статус | Описание |
|---|---|---|
| 200 | OK | Запрос выполнен успешно |
| 201 | Created | Ресурс успешно создан |
| 400 | Bad Request | Некорректный формат запроса |
| 401 | Unauthorized | Неверные учётные данные или токен |
| 403 | Forbidden | Доступ запрещён |
| 404 | Not Found | Ресурс не найден |
| 422 | Unprocessable Entity | Ошибка валидации данных |
| 429 | Too Many Requests | Превышен лимит запросов |
| 500 | Internal Server Error | Внутренняя ошибка сервера |
Формат ошибки
{
"status": "error",
"message": "Описание ошибки",
"errors": {
"field_name": ["Сообщение об ошибке для поля"]
}
}
Типичные ошибки
| Сообщение | Причина | Решение |
|---|---|---|
Invalid client credentials |
Неверный client_id или client_secret | Проверьте учётные данные в личном кабинете |
Token expired |
Истёк срок действия токена | Получите новый access_token |
Invalid currency |
Неподдерживаемая валюта | Используйте RUB, USD или EUR |
Amount must be positive |
Сумма ≤ 0 | Укажите положительную сумму |
Примеры кода
Готовые примеры интеграции
Полный пример интеграции
<?php
/**
* IWEXPAY Express API - Пример интеграции
*/
class IWEXPayClient
{
private $baseUrl = 'https://iwexpay.com';
private $clientId;
private $clientSecret;
private $accessToken;
public function __construct($clientId, $clientSecret)
{
$this->clientId = $clientId;
$this->clientSecret = $clientSecret;
}
/**
* Получение access token
*/
public function authenticate()
{
$response = $this->request('POST', '/merchant/api/verify', [
'client_id' => $this->clientId,
'client_secret' => $this->clientSecret
]);
if ($response['status'] === 'success') {
$this->accessToken = $response['data']['access_token'];
return true;
}
throw new Exception($response['message'] ?? 'Authentication failed');
}
/**
* Создание платежа
*/
public function createPayment($amount, $currency, $successUrl, $cancelUrl)
{
if (!$this->accessToken) {
$this->authenticate();
}
return $this->request('POST', '/merchant/api/transaction-info', [
'payer' => 'IWEXPAY',
'amount' => $amount,
'currency' => $currency,
'successUrl' => $successUrl,
'cancelUrl' => $cancelUrl
], true);
}
/**
* Получение списка платежей
*/
public function getPayments($filters = [])
{
if (!$this->accessToken) {
$this->authenticate();
}
$query = http_build_query($filters);
return $this->request('GET', '/merchant/api/payments?' . $query, [], true);
}
/**
* HTTP запрос
*/
private function request($method, $endpoint, $data = [], $withAuth = false)
{
$ch = curl_init($this->baseUrl . $endpoint);
$headers = [
'Content-Type: application/json',
'Accept: application/json'
];
if ($withAuth && $this->accessToken) {
$headers[] = 'Authorization: Bearer ' . $this->accessToken;
}
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
if ($method === 'POST') {
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
}
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
}
// Использование
$client = new IWEXPayClient('ваш_client_id', 'ваш_client_secret');
try {
$result = $client->createPayment(
1500.00,
'RUB',
'https://ваш-сайт.ru/success',
'https://ваш-сайт.ru/cancel'
);
if ($result['status'] === 'success') {
header('Location: ' . $result['data']['approvedUrl']);
exit;
}
} catch (Exception $e) {
echo 'Ошибка: ' . $e->getMessage();
}
/**
* IWEXPAY Express API - Пример интеграции (Node.js)
*/
class IWEXPayClient {
constructor(clientId, clientSecret) {
this.baseUrl = 'https://iwexpay.com';
this.clientId = clientId;
this.clientSecret = clientSecret;
this.accessToken = null;
}
/**
* Получение access token
*/
async authenticate() {
const response = await this.request('POST', '/merchant/api/verify', {
client_id: this.clientId,
client_secret: this.clientSecret
});
if (response.status === 'success') {
this.accessToken = response.data.access_token;
return true;
}
throw new Error(response.message || 'Authentication failed');
}
/**
* Создание платежа
*/
async createPayment(amount, currency, successUrl, cancelUrl) {
if (!this.accessToken) {
await this.authenticate();
}
return this.request('POST', '/merchant/api/transaction-info', {
payer: 'IWEXPAY',
amount: amount,
currency: currency,
successUrl: successUrl,
cancelUrl: cancelUrl
}, true);
}
/**
* Получение списка платежей
*/
async getPayments(filters = {}) {
if (!this.accessToken) {
await this.authenticate();
}
const query = new URLSearchParams(filters).toString();
return this.request('GET', `/merchant/api/payments?${query}`, {}, true);
}
/**
* HTTP запрос
*/
async request(method, endpoint, data = {}, withAuth = false) {
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
};
if (withAuth && this.accessToken) {
headers['Authorization'] = `Bearer ${this.accessToken}`;
}
const options = { method, headers };
if (method === 'POST') {
options.body = JSON.stringify(data);
}
const response = await fetch(`${this.baseUrl}${endpoint}`, options);
return response.json();
}
}
// Использование
const client = new IWEXPayClient('ваш_client_id', 'ваш_client_secret');
async function createPayment() {
try {
const result = await client.createPayment(
1500.00,
'RUB',
'https://ваш-сайт.ru/success',
'https://ваш-сайт.ru/cancel'
);
if (result.status === 'success') {
// Для браузера:
window.location.href = result.data.approvedUrl;
// Для Express.js:
// res.redirect(result.data.approvedUrl);
}
} catch (error) {
console.error('Ошибка:', error.message);
}
}
createPayment();
#!/bin/bash
# IWEXPAY Express API - Пример интеграции (Bash/cURL)
CLIENT_ID="ваш_client_id"
CLIENT_SECRET="ваш_client_secret"
# 1. Получение access token
echo "Получение токена..."
AUTH_RESPONSE=$(curl -s -X POST https://iwexpay.com/merchant/api/verify \
-H "Content-Type: application/json" \
-d "{
\"client_id\": \"$CLIENT_ID\",
\"client_secret\": \"$CLIENT_SECRET\"
}")
ACCESS_TOKEN=$(echo $AUTH_RESPONSE | grep -o '"access_token":"[^"]*"' | cut -d'"' -f4)
if [ -z "$ACCESS_TOKEN" ]; then
echo "Ошибка аутентификации: $AUTH_RESPONSE"
exit 1
fi
echo "Токен получен: $ACCESS_TOKEN"
# 2. Создание платежа
echo "Создание платежа..."
PAYMENT_RESPONSE=$(curl -s -X POST https://iwexpay.com/merchant/api/transaction-info \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
"payer": "IWEXPAY",
"amount": 1500.00,
"currency": "RUB",
"successUrl": "https://ваш-сайт.ru/success",
"cancelUrl": "https://ваш-сайт.ru/cancel"
}')
echo "Ответ: $PAYMENT_RESPONSE"
# Извлечение URL для оплаты
APPROVED_URL=$(echo $PAYMENT_RESPONSE | grep -o '"approvedUrl":"[^"]*"' | cut -d'"' -f4)
if [ -n "$APPROVED_URL" ]; then
echo "URL для оплаты: $APPROVED_URL"
fi
# 3. Получение списка платежей
echo "Получение списка платежей..."
curl -s -X GET "https://iwexpay.com/merchant/api/payments?status=success&limit=10" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Accept: application/json" | python3 -m json.tool
Обработка webhook
<?php
/**
* Обработчик Webhook уведомлений от IWEXPAY
*/
// Секретный ключ (получен при создании webhook)
$webhookSecret = 'whsec_ваш_секретный_ключ';
// Получаем payload и подпись
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
// Верифицируем подпись
$expectedSignature = hash_hmac('sha256', $payload, $webhookSecret);
if (!hash_equals($expectedSignature, $signature)) {
http_response_code(401);
die('Invalid signature');
}
// Парсим событие
$event = json_decode($payload, true);
// Логируем для отладки
error_log('IWEXPAY Webhook: ' . $event['event'] . ' - ' . json_encode($event['data']));
// Обрабатываем событие
switch ($event['event']) {
case 'payment.success':
handlePaymentSuccess($event['data']);
break;
case 'payment.pending':
handlePaymentPending($event['data']);
break;
case 'payment.cancelled':
handlePaymentCancelled($event['data']);
break;
case 'payment.rejected':
handlePaymentRejected($event['data']);
break;
default:
error_log('Unknown event: ' . $event['event']);
}
// Возвращаем 200 OK
http_response_code(200);
echo 'OK';
// ==================== ОБРАБОТЧИКИ СОБЫТИЙ ====================
function handlePaymentSuccess($data)
{
$transactionId = $data['transaction_id'];
$amount = $data['amount'];
$orderId = $data['order_id'] ?? null;
// Ваша логика: обновить заказ, отправить email и т.д.
// Пример: updateOrderStatus($orderId, 'paid');
}
function handlePaymentPending($data)
{
$transactionId = $data['transaction_id'];
// Bank платёж ожидает подтверждения администратором
// Можно показать пользователю сообщение об ожидании
}
function handlePaymentCancelled($data)
{
$transactionId = $data['transaction_id'];
// Пользователь отменил платёж
// Восстановить товар в корзину и т.д.
}
function handlePaymentRejected($data)
{
$transactionId = $data['transaction_id'];
// Bank платёж отклонён администратором
// Уведомить пользователя
}
/**
* Обработчик Webhook уведомлений от IWEXPAY (Express.js)
*/
const express = require('express');
const crypto = require('crypto');
const app = express();
// Секретный ключ (получен при создании webhook)
const WEBHOOK_SECRET = 'whsec_ваш_секретный_ключ';
// Важно: используйте raw body для верификации подписи
app.post('/webhooks/iwexpay', express.raw({ type: 'application/json' }), (req, res) => {
const payload = req.body.toString();
const signature = req.headers['x-webhook-signature'] || '';
// Верифицируем подпись
const expectedSignature = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(payload)
.digest('hex');
if (!crypto.timingSafeEqual(
Buffer.from(expectedSignature),
Buffer.from(signature)
)) {
console.error('Invalid webhook signature');
return res.status(401).send('Invalid signature');
}
// Парсим событие
const event = JSON.parse(payload);
console.log(`IWEXPAY Webhook: ${event.event}`, event.data);
// Обрабатываем событие
switch (event.event) {
case 'payment.success':
handlePaymentSuccess(event.data);
break;
case 'payment.pending':
handlePaymentPending(event.data);
break;
case 'payment.cancelled':
handlePaymentCancelled(event.data);
break;
case 'payment.rejected':
handlePaymentRejected(event.data);
break;
default:
console.log('Unknown event:', event.event);
}
// Возвращаем 200 OK
res.status(200).send('OK');
});
// ==================== ОБРАБОТЧИКИ СОБЫТИЙ ====================
function handlePaymentSuccess(data) {
const { transaction_id, amount, order_id } = data;
// Ваша логика: обновить заказ, отправить email и т.д.
console.log(`Платёж ${transaction_id} успешен: ${amount}`);
}
function handlePaymentPending(data) {
const { transaction_id } = data;
// Bank платёж ожидает подтверждения администратором
console.log(`Платёж ${transaction_id} ожидает подтверждения`);
}
function handlePaymentCancelled(data) {
const { transaction_id } = data;
// Пользователь отменил платёж
console.log(`Платёж ${transaction_id} отменён`);
}
function handlePaymentRejected(data) {
const { transaction_id } = data;
// Bank платёж отклонён администратором
console.log(`Платёж ${transaction_id} отклонён`);
}
app.listen(3000, () => console.log('Webhook server running on port 3000'));
FAQ
Часто задаваемые вопросы
Войдите в личный кабинет IWEXPAY → Юридическое лицо → нажмите на значок шестерёнки рядом с типом "Express". Там вы найдёте Client ID и Client Secret.
Access token действителен 24 часа. Рекомендуется кэшировать токен и обновлять его заблаговременно.
Mts — мгновенная оплата с баланса пользователя IWEXPAY. Подтверждение происходит автоматически.
Bank — банковский перевод, требующий ручного подтверждения администратором после проверки поступления средств.
Для Bank платежей — да, обязательно. Если необходимо узнать статус платежа на вашем сервере.
Для Mts платежей — рекомендуется, но можно использовать параметры в successUrl для идентификации платежа.
Используйте реальные учётные данные для создания тестовых платежей с минимальными суммами. Sandbox-режим находится в разработке.
Минимальная сумма: 100.00 RUB, 1 USD/EUR. Максимальная сумма зависит от настроек вашего мерчант-аккаунта.
Changelog
История изменений API
Безопасность
- Добавлен Rate Limiting для всех endpoints
- Добавлено логирование API запросов
- 22 новых теста безопасности
Payment Status API
- Новый endpoint:
GET /merchant/api/payments - Новый endpoint:
GET /merchant/api/payments/{uuid} - Фильтрация по статусу, методу оплаты, валюте, дате
- Пагинация с лимитом 100 записей
Bank Payment + Webhooks
- Добавлен метод оплаты Bank (банковский перевод)
- Webhook события: payment.pending, payment.rejected
- 18 тестов для Bank платежей
Webhooks (IPN)
- Полная система Webhooks с HMAC-SHA256 подписью
- 8 endpoints для управления webhooks
- Автоматические повторные попытки доставки
Первый релиз
- OAuth2 аутентификация
- Создание платежей
- Метод оплаты Mts