Войти Регистрация
Express API v1.5

Введение в Express API

Программный интерфейс для приёма платежей на вашем сайте

Что такое Express API?

Express API — это RESTful интерфейс для интеграции платежей IWEXPAY в ваше приложение. Он позволяет программно создавать платежи, отслеживать их статус и получать уведомления об оплате.

Возможности API

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

Безопасная авторизация с использованием access token

Несколько методов оплаты

Mts (электронный кошелёк), Bank (банковский перевод)

Webhooks (IPN)

Мгновенные уведомления о статусе платежа

Rate Limiting

Защита от злоупотреблений с гибкими лимитами

Базовый URL

Production
https://iwexpay.com

Формат данных

Все запросы и ответы используют формат JSON. Обязательно указывайте заголовки:

Заголовки запроса
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token}

Поддерживаемые валюты

Код Валюта Мин. сумма
RUBРоссийский рубль100.00
USDДоллар США1
EURЕвро1

Быстрый старт

Создайте первый платёж за 5 минут

1

Получите учётные данные

Войдите в личный кабинет IWEXPAY → Юридическое лицо → Настройки (значок шестерёнки)

Скопируйте Client ID и Client Secret

2

Получите access token

POST /merchant/api/verify
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"
  }
}
3

Создайте платёж

POST /merchant/api/transaction-info
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"
  }
}
4

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

Перенаправьте покупателя на approvedUrl для оплаты

PHP
// После получения ответа от API
header("Location: " . $response['data']['approvedUrl']);
exit;
5

Готово!

После оплаты пользователь будет перенаправлен на ваш successUrl или cancelUrl

Рекомендация

Настройте Webhooks для получения уведомлений о статусе платежа в реальном времени.

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

OAuth2 Client Credentials Flow

Как это работает

Express API использует OAuth2 аутентификацию. Для выполнения запросов вам нужен access token, который получается путём обмена ваших учётных данных.

Ваш сервер
client_id + client_secret
IWEXPAY API
access_token

Учётные данные

Параметр Описание Где получить
client_id Уникальный идентификатор вашего приложения Личный кабинет → Юр. лицо → Настройки
client_secret Секретный ключ для аутентификации Личный кабинет → Юр. лицо → Настройки
Безопасность

Никогда не передавайте client_secret в клиентском коде (JavaScript, мобильные приложения). Храните его только на сервере.

Срок действия токена

Access token действителен в течение 24 часов. После истечения срока необходимо получить новый токен.

Получение токена

POST /merchant/api/verify

POST 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);
}

Успешный ответ

200 OK
{
  "status": "success",
  "message": "Client Verified",
  "data": {
    "access_token": "z3iRLpWzCTWKKJLNQLL7gEDcZG"
  }
}

Ошибки

401 Unauthorized
{
  "status": "error",
  "message": "Unauthorized: Invalid client credentials"
}

Создание платежа

POST /merchant/api/transaction-info

POST 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;
}

Успешный ответ

200 OK
{
  "status": "success",
  "message": "Информация о транзакции успешно создана!",
  "data": {
    "approvedUrl": "https://iwexpay.com/merchant/payment?grant_id=52283195&token=T3LM4V0aWy70pxN3DEiy"
  }
}

Параметры ответа

Поле Описание
approvedUrl URL страницы оплаты. Перенаправьте покупателя на этот URL.
grant_id Уникальный идентификатор транзакции (в URL)
token Токен безопасности транзакции (в URL)

Сценарии использования

Пользователь сам выбирает сумму

Вы можете позволить пользователю самому указывать сумму платежа (например, для пополнения баланса, донатов, произвольных платежей). Сумма собирается на вашем сайте и передаётся в API при создании транзакции.

Схема работы:

User вводит сумму на вашем сайте
Ваш сервер передаёт сумму в IWEXPAY API
Оплата на странице IWEXPAY

Пример: 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 (Банковский перевод)

Оплата банковским переводом с ручным подтверждением

  • Подтверждение: После проверки администратором
  • Статус после оплаты: pendingsuccess
  • Webhook: payment.pending, затем payment.success или payment.rejected

Процесс оплаты Bank

1

Пользователь выбирает Bank

На странице оплаты показываются банковские реквизиты

2

Пользователь совершает перевод

Через банковское приложение или интернет-банк

3

Пользователь нажимает "Я оплатил"

Статус: pending, отправляется webhook payment.pending

4

Администратор проверяет платёж

Подтверждает или отклоняет транзакцию

Финальный статус

Отправляется webhook payment.success или payment.rejected

Важно для Bank

Для Bank платежей обязательно настройте Webhooks, чтобы получать уведомления о подтверждении платежа администратором.

Статус платежей

Получение информации о платежах

Список платежей

GET 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}`);
    });
}

Ответ

200 OK
{
  "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
    }
  }
}

Детали платежа

GET https://iwexpay.com/merchant/api/payments/{uuid}

Ответ

200 OK
{
  "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 отправляет на ваш сервер при изменении статуса платежа.

Платёж завершён
IWEXPAY
POST на ваш URL
Ваш сервер

Преимущества

Мгновенные уведомления

Получайте информацию сразу после события

Надёжная доставка

Автоматические повторные попытки при сбоях

Подпись HMAC

Криптографическая верификация источника

Обязательно для Bank платежей

Для Bank платежей webhooks — единственный способ узнать о подтверждении платежа администратором.

Настройка Webhooks

API для управления webhook подписками

Создание webhook

POST 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);
}

Ответ

201 Created
{
  "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!

Секретный ключ 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

Пример 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)

webhook-handler.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 минута

Превышение лимита

429 Too Many Requests
{
  "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 Укажите положительную сумму

Примеры кода

Готовые примеры интеграции

Полный пример интеграции

IWEXPayClient.php
<?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();
}
IWEXPayClient.js
/**
 * 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();
Bash скрипт
#!/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

webhook.php
<?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.js (Express.js)
/**
 * Обработчик 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

v1.5 6 декабря 2025

Безопасность

  • Добавлен Rate Limiting для всех endpoints
  • Добавлено логирование API запросов
  • 22 новых теста безопасности
v1.4 6 декабря 2025

Payment Status API

  • Новый endpoint: GET /merchant/api/payments
  • Новый endpoint: GET /merchant/api/payments/{uuid}
  • Фильтрация по статусу, методу оплаты, валюте, дате
  • Пагинация с лимитом 100 записей
v1.3 6 декабря 2025

Bank Payment + Webhooks

  • Добавлен метод оплаты Bank (банковский перевод)
  • Webhook события: payment.pending, payment.rejected
  • 18 тестов для Bank платежей
v1.1 6 декабря 2025

Webhooks (IPN)

  • Полная система Webhooks с HMAC-SHA256 подписью
  • 8 endpoints для управления webhooks
  • Автоматические повторные попытки доставки
v1.0 2025

Первый релиз

  • OAuth2 аутентификация
  • Создание платежей
  • Метод оплаты Mts