Документация для автоматизации работы с заказами Zenpayments

Введение

Для работы с API вам понадобится личный кабинет. Если у вас его ещё нет, зарегистрируйтесь на сайте zenpayments.ru.

API позволяет автоматизировать работу с заказами: создавать, редактировать, проверять статус и удалять.

По всем вопросам работы API обращайтесь в чат поддержки или на почту support@zenpayments.ru.

Список кодов платёжных методов и шлюзов

При создании заказа, вы будете указывать один или несколько платёжных методов, которые будут доступны покупателю. Каждый метод это сочетание трёх параметров: method, gateway, terms. Чтобы разобраться, какие параметры следует использовать в вашем случае, используйте следующую таблицу:

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

Для создания платёжного метода "Внутренняя рассрочка" или "Подписка" также используется определённый набор параметров. Под внутренней рассрочкой подразумевается небанковская рассрочка, т.е. просто разбиение одного платежа на несколько, с автоматическим списанием с карты.

Под подпиской имеется в виду условно-бесконечные списания с заданной периодичностью. Минимальный период между платежами — 1 день. Максимальный период между платежами — 1 год. Для вашего удобства собрали таблицу с некоторыми популярными сочетаниями настроек:

Начало работы

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

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

Выпущенный токен можно протестировать прямо на этом сайте, с помощью кнопок "Отправить запрос".

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

Формат взаимодействия

Синтаксис запросов и ответов

Все запросы отправляются по https с использованием одного из следующих методов: GET, POST, PUT, DELETE. API поддерживает запросы с Content-type: application/json. Вот пример запроса с использованием curl:

curl -X GET "https://zenpayments.ru/api/v1/orders/{order_number}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer [TOKEN]" \

В этом примере:

• GET это http-метод. У каждого эндпоинта в документации указано, какой метод следует использовать
• zenpayments.ru это адрес нашего сервера. В будущем мы оставляем за собой право добавлять новые адреса серверов и отключать старые
• api/v1 это префикс, сигнализирующий о том, какую версию API вы используете. В данный момент, доступна только одна версия
• orders/{order_number} это название метода, который вы вызываете. Названия всех методов есть в соответствующих разделах документации
• [TOKEN] это токен, сгенерированный в настройках вашей школы

В ответ на любой запрос сервер вернет либо ответ с кодом 200 / 201, либо ошибку с кодами 4xx или 5xx.

Ограничения и рекомендации

У методов API действует ограничение на количество запросов.

В данный момент, ограничение одинаковое для всех методов: 60 запросов в минуту с одного IP-адреса.

Если вы превысите ограничение, на последующие запросы сервер будет возвращать ответ с кодом 429.

Формат ошибок

Общая информация

Любой запрос может вернуть ошибку. Бывают ошибки общего вида, а бывают специфические для конкретного эндпоинта.

Ошибки с http-кодом 5xx означают, что серверу не удалось обработать запрос. Следует повторить попытку позже.

Ошибки с http-кодом 4xx означают, что запрос обработан успешно, поэтому нужно смотреть на конкретный код и тело ответа, чтобы разобраться, что пошло не так. Типовые причины ошибок это неправильный токен, ошибка в URL или входных параметрах.

Примеры ответов с ошибкой

// HTTP/1.1 404 Not Found
{
    "message": "Not found",
}

// HTTP/1.1 422 Unprocessable Entity
{
  "message": "Поле customer last name обязательно. (and 1 more error)",
  "errors": {
    "customer_last_name": [
      "Поле customer last name обязательно."
    ],
    "customer_first_name": [
      "Поле customer first name обязательно."
    ]
  }
}

Поле message содержит пояснение ошибки. В зависимости от вида ошибки, в ответе могут содержаться и другие поля.

Документация по приёму вебхуков

Мы можем отправлять вебхуки вашим сервисам с целью уведомления о событиях. Ниже описаны технические детали реализации механизма отправки. Чтобы мы отправляли вам вебхуки, заполните поле callback_url при создании заказа.

Метод отправки

• HTTP-метод: POST
• Таймаут ответа: 5 секунд
• Количество попыток: до 5 (если не получен ответ с кодом 200 OK)
• Требования к получателю:
  • Ответ должен содержать статус 200 OK, иначе считается неудачным. Тело ответа может быть любым

Идемпотентность

Для обеспечения идемпотентности в теле запроса передаётся уникальный id события. Получатель может использовать этот идентификатор для предотвращения повторной обработки одного и того же события.

Проверка подлинности

В запросе присутствует заголовок:

• Signature — подпись, которую следует использовать для проверки подлинности отправителя и целостности данных.

Получив запрос, вы можете проверить, действительно ли отправителем являемся мы. Пример проверки на языке PHP:

function exampleValidator(\Symfony\Component\HttpFoundation\Request $request): bool
{
    $signature = $request->headers->get('Signature');
    $secret = 'Ваш секретный ключ';
    $body = $request->getContent();
    $payloadJson = json_encode($body);
    $hash = hash_hmac('sha256', $payloadJson, $secret);

    return hash_equals($signature, $hash);
}

Мы рекомендуем всегда проверять подлинность запросов, хотя окончательное решение остаётся за вами.

Секретный ключ для проверки подписи можно взять в разделе "Компании", кликнув по конкретному ИНН. Если в вашем аккаунте добавлено несколько компаний, обратите внимание, что у каждой компании будет свой ключ.

Пример запроса

POST /webhook-endpoint HTTP/1.1
Host: your-server-example.org
Content-Type: application/json
Signature: abcdef123456...

{
    "id": "5aWTnvn70JEEVVLCMNcSwhfbvv8pxj1m",
    "timestamp": "1748595629",
    "event": "payment.accepted",
    "payload": {
        "paid_at": 1748595629,
        "payment_number": "P-1-20429693492658176",
        "amount_paid": 10000,
        "amount_commission": 450,
        "currency_code": "RUB",
        "payment_method": 1,
        "payment_gateway": null,
        "payment_terms": null,
        "order_number": "ZP-1-20429651037913088",
        "order_id_client": null,
        "invoice_number": "INV-1-20429693375217664",
        "next_payment_at": null,
        "customer_last_name": "Пушкин",
        "customer_first_name": "Александр",
        "customer_middle_name": "Сергеевич",
        "customer_email": "alex@example.org",
        "customer_phone": null,
        "order_positions": [
            {
                "content": "Оплата доступа к курсу",
                "quantity": 1,
                "vat_code_id": 1,
                "price": 10000,
                "price_discounted": 10000
            }
        ],
        "pan4": "1111"
    }
}

Список событий

Содержимое каждого вебхука есть в примерах на отдельной странице.

Тестовые карты

Для тестирования оплаты в тестовой среде можно использовать специальную карту, с которой всегда будут успешно "списываться" деньги. Обратите внимание, что это сработает только в тестовой среде по адресу sandbox.zenpayments.ru.

Тестовая карта работает только с платёжным методом "Эквайринг".

• Номер карты: 4762085995973998
• Срок: 12/24
• Код CVC: 111 Код 3DSec: 111111

Авторизация запросов

Для авторизации, включите в запрос заголовок Authorization со значением "Bearer {YOUR_AUTH_KEY}".

Создать токен можно в личном кабинете, кликнув по выпадающему меню в левом нижнем углу и перейдя в раздел API токены.