Platební požadavky — API dokumentace

Documentation

Authentication Payment Requests Contacts Webhooks Support Swagger UI

Payment Requests

Base URL: /api-pub/v1/payment-requests

Payment requests are the core resource in MailPay. Each one represents an expected incoming payment with a specified amount, due date, and bank account. Once created, MailPay automatically monitors your inbox for matching payments and updates the request status accordingly. You can optionally link a payment request to a contact or use your own externalId to sync with your system.

Quick Start — Create a Payment Request

curl -X POST https://mailpay.cz/api-pub/v1/payment-requests \
  -H "Authorization: Bearer mp_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice #001",
    "amount": "1500.00",
    "dueDate": "2026-03-01T00:00:00Z",
    "bankAccount": "1234567890/0100"
  }'

Create with Contact & Variable Symbol

Link a payment request to a contact using contactId (internal) or contactExternalId (your system's ID):

curl -X POST https://mailpay.cz/api-pub/v1/payment-requests \
  -H "Authorization: Bearer mp_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice #002",
    "amount": "2500.00",
    "dueDate": "2026-03-15T00:00:00Z",
    "bankAccount": "1234567890/0100",
    "contactExternalId": "customer-123",
    "variableSymbol": "2024002"
  }'

Required Fields

Field	Type	Description
`name`	string	Payment request name / description
`amount`	string	Decimal amount, e.g. `"1500.00"`
`dueDate`	string	ISO 8601 date, e.g. `"2026-03-01T00:00:00Z"`
`bankAccount`	string	Account number / bank code, e.g. `"1234567890/0100"`

Optional Fields

Field	Type	Description
`contactId`	string	Internal contact ID
`contactExternalId`	string	Your system's contact ID
`variableSymbol`	string	Variable symbol
`specificSymbol`	string	Specific symbol
`constantSymbol`	string	Constant symbol
`currency`	string	Default: `"CZK"`
`note`	string	Internal note
`externalId`	string	Your system's ID (unique per org)
`backUrl`	string	URL to redirect the user back to after payment (included in `paymentUrl`)

Get a Payment Request

Retrieve a payment request by its internal ID or by your externalId:

curl https://mailpay.cz/api-pub/v1/payment-requests/:id \
  -H "Authorization: Bearer mp_xxx"

curl https://mailpay.cz/api-pub/v1/payment-requests/by-external-id/:externalId \
  -H "Authorization: Bearer mp_xxx"

Example response:

{
  "id": "clx1abc...",
  "externalId": "invoice-001",
  "name": "Invoice #001",
  "amount": "1500.00",
  "currency": "CZK",
  "dueDate": "2026-03-01T00:00:00.000Z",
  "variableSymbol": null,
  "specificSymbol": null,
  "constantSymbol": null,
  "bankAccount": {
    "id": "clx2def...",
    "accountNumber": "1234567890",
    "bankCode": "0100"
  },
  "contact": null,
  "note": null,
  "status": "PENDING",
  "paymentUrl": "https://mailpay.cz/pay/clx3ghi...",
  "qrCode": "SPD*1.0*ACC:CZ6501000000001234567890*AM:1500.00*CC:CZK*PT:IP*DT:20260301",
  "createdAt": "2026-02-20T10:00:00.000Z",
  "updatedAt": "2026-02-20T10:00:00.000Z"
}

Response Fields

Field	Type	Description
`paymentUrl`	string \| null	Direct link to the QR payment page. If `backUrl` was provided during creation, it is appended as a query parameter.
`qrCode`	string \| null	SPAYD string that can be used to generate a QR code for bank payment. Contains IBAN, amount, currency, symbols, and due date.

Create with Back URL

Pass backUrl to include a "back to merchant" link on the payment page. The URL will be appended to paymentUrl as a query parameter:

curl -X POST https://mailpay.cz/api-pub/v1/payment-requests \
  -H "Authorization: Bearer mp_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order #42",
    "amount": "990.00",
    "dueDate": "2026-03-01T00:00:00Z",
    "bankAccount": "1234567890/0100",
    "backUrl": "https://example.com/order/42/thank-you"
  }'

API Documentation