Обзор¶
Это руководство описывает всё, что нужно бэкенду мерчанта, чтобы принимать платежи (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 вернёт исходную запись, а не создаст вторую.
Стабильность. Ответы могут содержать больше полей, чем описано здесь, и могут появляться новые значения перечислений (статусы, платёжные системы, типы вебхуков). Игнорируйте то, чем не пользуетесь, и корректно обрабатывайте неизвестные значения.