Docs

Concepts

Mandates

A mandate is a signed standing authorization: who may be paid, how much, until when. Every payout and every authorization decision is checked against one.

Fields#

Field Meaning
mandateReference your reference; SEPA rules: 1–35 characters, letters, digits and +?/-:().,' and space, no leading or trailing /
beneficiaryId the only payee this mandate allows
payerId the verified payer whose default funding source is debited — or give debtorName and debtorIban directly
signedBy who signed
currency the only currency allowed
maxAmount cap per payment
maxTotalAmount optional cap on the sum of all payments
scheme sepa_core, sepa_b2b or agent_payout
mandateType one_off (a single payment) or recurring
validFrom, validUntil the window; both optional

A mandate is signed over its fields, including the payer and the rail, so it cannot be reassigned or altered without the signature breaking.

The ten checks#

Every decision runs these, in order, and reports each by name:

  1. mandate_reference_format — the reference follows the rules
  2. debtor_source_valid — the debtor account is a valid IBAN
  3. signature_intact — nothing was edited since signing
  4. mandate_active — not revoked, not expired
  5. validity_window — today is inside validFrom–validUntil
  6. mandate_type_usage — a one_off mandate has not been used
  7. currency_match — the payment's currency is the mandate's
  8. beneficiary_match — the payee is the mandate's payee
  9. per_payment_limit — amount ≤ maxAmount
  10. cumulative_limit — total so far + amount ≤ maxTotalAmount

A result reads isValid, checks[] (name, passed, detail), failedChecks[] and an explanation. Payouts in draft, pending_kyc, approved, processing, paid and returned count toward the total; kyc_rejected and failed do not.

Lifecycle#

active → revoked (by request) or expired (past validUntil, recorded when first observed). Suspending a payer stops new mandates but leaves existing ones to be revoked deliberately. A payer that is still pending_verification cannot sign at all.

Receipts#

POST /api/authorize returns a receipt: decision, the amount and currency, payer and payee, the mandate reference, the checks, fundsReserved: false, issuedAt/expiresAt (5 minutes by default), and a signature over all of it.

POST /api/authorize/verify answers usable (valid, unexpired, approved), signatureValid and expired. Any edit — the amount, the payee, a refusal turned into an approval — makes signatureValid: false.

An approval permits a payment. It does not reserve or move money.