MailPay

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

Optional Fields

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",
  "createdAt": "2026-02-20T10:00:00.000Z",
  "updatedAt": "2026-02-20T10:00:00.000Z"
}