Перейти к содержанию

Обзор

Это руководство описывает всё, что нужно бэкенду мерчанта, чтобы принимать платежи (payins), отправлять выплаты и возвраты и получать вебхуки от Payard: подписывайте каждый запрос своим API-ключом, создавайте операцию с ключом идемпотентности и воспринимайте вебхук как сигнал перечитать результат.

Payard Merchant API позволяет вашему бэкенду принимать платежи (payins), отправлять деньги (payouts) и получать уведомления о статусах (вебхуки) по HTTPS в формате JSON. Платежи и выплаты асинхронны: ответ 201 на создание означает принято, а итоговый результат приходит вебхуком.

Окружения и базовый URL

  • Базовый URL: https://<host>/api/v1. Хост выдаёт Payard. Все пути в руководстве указаны относительно него.
  • Окружение выбирается в каждом запросе заголовком x-env. PROD выбирает боевую лицензию; любое другое значение или отсутствие заголовка выбирает SANDBOX.
  • Транспорт: только HTTPS, Content-Type: application/json, UTF-8.

Соглашения

Что Формат Пример
Идентификаторы сущностей UUID bebcb6a6-99e0-4e4e-9dea-0d34cd50ddf3
Суммы Целое число в минимальных единицах валюты. Никогда не передавайте дробные значения. 12550 в EUR = 125,50 €
Валюты Буквенный код ISO 4217 EUR, GBP
Страны ISO 3166-1 alpha-3 (alpha-2 только там, где это указано для поля) DEU
Платёжные системы Код Payard SEPA, FASTER_PAYMENTS, PAY_ID
Даты ISO 8601, UTC 2026-11-16T09:03:11.204Z

Тела запросов. В запросах на создание и изменение поля, которые маршрут не объявляет, молча отбрасываются, поэтому опечатка в необязательном поле ни на что не влияет. Тела фильтров (POST …/get-all) строгие: неизвестное поле отклоняется с REQUEST_VALIDATION_FAILED.

Чтение одной записи. GET /<resource>/get-one/:id. Вы всегда видите только записи своего мерчанта.

Списки. POST /<resource>/get-all с JSON-фильтром в теле ({} — без фильтра); пагинация и сортировка передаются в строке запроса.

Параметр По умолчанию Значение
page 1 Номер страницы, начиная с 1
pageSize 100 Записей на странице
sort[0][field] зависит от эндпоинта Поле сортировки; вложенные поля через точку
sort[0][desc] false true — по убыванию
POST /api/v1/payout/get-all?page=1&pageSize=50&sort[0][field]=createdAt&sort[0][desc]=true
Content-Type: application/json

{"statuses":["COMPLETED","FAILED"],"created":{"startDate":"2026-11-01T00:00:00Z","endDate":"2026-11-30T23:59:59Z"}}

Ответ списка: { "data": [...], "totalCount": 137, "options": {...} }. Листайте страницы, пока не выполнится page * pageSize >= totalCount. Если поле фильтра не нужно, не передавайте его вовсе вместо []: некоторые фильтры трактуют пустой массив как «ничего не подходит».

Идемпотентность. transaction/create, transaction/create-sync, payout/create и payment/refund принимают необязательный idempotencyKey (UUID v4). Генерируйте его на каждую бизнес-операцию, сохраняйте до отправки и при повторе после таймаута отправляйте тот же ключ. Тогда Payard вернёт исходную запись, а не создаст вторую.

Стабильность. Ответы могут содержать больше полей, чем описано здесь, и могут появляться новые значения перечислений (статусы, платёжные системы, типы вебхуков). Игнорируйте то, чем не пользуетесь, и корректно обрабатывайте неизвестные значения.