Overview¶
This guide covers everything a merchant backend needs to take payins, send payouts and refunds, and receive webhooks from Payard: sign each request with your API key, create the operation with an idempotency key, and treat the webhook as a trigger to re-read the result.
The Payard Merchant API lets your backend take payments in (payins), pay money out (payouts) and receive status notifications (webhooks) over HTTPS and JSON. Payins and payouts are asynchronous: a 201 from a create call means accepted, and the final result arrives by webhook.
Environments and base URL¶
- Base URL:
https://<host>/api/v1. Payard gives you the host. Every path in this guide is relative to it. - Environment: chosen per request by the
x-envheader.PRODselects your production licence; any other value, or no header, selectsSANDBOX. - Transport: HTTPS only,
Content-Type: application/json, UTF-8.
Conventions¶
| Kind | Format | Example |
|---|---|---|
| Entity ids | UUID | bebcb6a6-99e0-4e4e-9dea-0d34cd50ddf3 |
| Amounts | Integer, minor units of the currency. Never send decimals. | 12550 in EUR = €125.50 |
| Currencies | ISO 4217 alphabetic code | EUR, GBP |
| Countries | ISO 3166-1 alpha-3 (alpha-2 only where a field says so) | DEU |
| Payment systems | Payard code | SEPA, FASTER_PAYMENTS, PAY_ID |
| Dates | ISO 8601, UTC | 2026-11-16T09:03:11.204Z |
Request bodies. Create and update bodies silently drop fields the route does not declare, so a misspelled optional field has no effect. Filter bodies (POST …/get-all) are strict: an unknown field is refused with REQUEST_VALIDATION_FAILED.
Reading one record. GET /<resource>/get-one/:id. You only ever see records of your own merchant.
Listing records. POST /<resource>/get-all with a JSON filter body ({} for no filter); paging and sorting go in the query string.
| Query parameter | Default | Meaning |
|---|---|---|
page |
1 |
1-based page number |
pageSize |
100 |
Records per page |
sort[0][field] |
per endpoint | Field to sort by; nested fields use dots |
sort[0][desc] |
false |
true for descending |
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"}}
A list response is { "data": [...], "totalCount": 137, "options": {...} }. Keep paging until page * pageSize >= totalCount. Omit a filter field you do not want instead of sending []: some filters read an empty array as "match nothing".
Idempotency. transaction/create, transaction/create-sync, payout/create and payment/refund accept an optional idempotencyKey (UUID v4). Generate one per business operation, store it before sending, and resend the same key when you retry after a timeout. Payard then returns the original record instead of creating a second one.
Stability. Responses may carry more fields than this guide documents, and new enum values (statuses, payment systems, webhook types) may appear. Ignore what you do not use and handle unknown values gracefully.