REST API
Mandates
POST/api/mandates
Sign a mandate. With payerId the debtor account comes from the verified payer; without one, give debtorName and debtorIban. Fields are explained in Mandates.
Request
JSON
{
"beneficiaryId": "9596acc9-0320-4b89-8cc8-475f04fe3948",
"payerId": "95df7fad-016c-4406-bd04-8ff13ac121ee",
"mandateReference": "SHOP-001",
"signedBy": "Finance",
"currency": "EUR",
"maxAmount": 100,
"maxTotalAmount": 250
}Response 200
JSON
{
"ok": true,
"data": {
"mandateId": "fde3a3a0-8125-4ea1-b6fc-a3e1c7138ead",
"mandateReference": "SHOP-001",
"beneficiaryId": "9596acc9-0320-4b89-8cc8-475f04fe3948",
"rail": "sepa",
"payerId": "95df7fad-016c-4406-bd04-8ff13ac121ee",
"debtorName": "Merchant B.V.",
"debtorIban": "NL91ABNA0417164300",
"scheme": "agent_payout",
"mandateType": "recurring",
"currency": "EUR",
"maxAmount": 100,
"maxTotalAmount": 250,
"validFrom": "2026-09-23T18:42:40.621Z",
"validUntil": "2027-09-23T18:42:40.621Z",
"signedBy": "Finance",
"signedAt": "2026-09-23T18:42:40.622Z",
"signature": "mandate-sig-527a620bb6625e3bc2e9421163ff2714",
"status": "active",
"createdAt": "2026-09-23T18:42:40.622Z",
"updatedAt": "2026-09-23T18:42:40.622Z",
"history": [
{
"status": "active",
"timestamp": "2026-09-23T18:42:40.622Z",
"note": "Mandate SHOP-001 signed by Finance."
}
]
}
}POST/api/mandates/{id}/validate
Run the ten checks against a possible payment without deciding anything.
Request
JSON
{
"amount": 50,
"currency": "EUR",
"beneficiaryId": "9596acc9-0320-4b89-8cc8-475f04fe3948"
}Response 200
JSON
{
"ok": true,
"data": {
"mandateId": "fde3a3a0-8125-4ea1-b6fc-a3e1c7138ead",
"mandateReference": "SHOP-001",
"status": "active",
"scheme": "agent_payout",
"mandateType": "recurring",
"isValid": true,
"checks": [
{
"name": "mandate_reference_format",
"passed": true,
"detail": "Mandate reference SHOP-001 matches the mandate reference rules."
},
{
"name": "debtor_source_valid",
"passed": true,
"detail": "Debtor IBAN NL91ABNA0417164300 is valid."
},
{
"name": "signature_intact",
"passed": true,
"detail": "Mandate signature matches the signed mandate fields."
},
{
"name": "mandate_active",
"passed": true,
"detail": "Mandate status is active."
},
{
"name": "validity_window",
"passed": true,
"detail": "Mandate is inside its validity window (2026-09-23T18:42:40.621Z to 2027-09-23T18:42:40.621Z)."
},
{
"name": "mandate_type_usage",
"passed": true,
"detail": "Recurring mandate has authorized 0 payout(s) so far."
},
{
"name": "currency_match",
"passed": true,
"detail": "Payment currency EUR matches the mandate currency."
},
{
"name": "beneficiary_match",
"passed": true,
"detail": "Payment beneficiary matches the mandate beneficiary."
},
{
"name": "per_payment_limit",
"passed": true,
"detail": "Payment amount 50 EUR is within the per-payment limit of 100 EUR."
},
{
"name": "cumulative_limit",
"passed": true,
"detail": "Mandate total after this payment would be 50 of 250 EUR."
}
],
"failedChecks": [],
"usage": {
"payoutCount": 0,
"totalAmount": 0
},
"remainingAmount": 250,
"evaluatedContext": {
"amount": 50,
"currency": "EUR",
"beneficiaryId": "9596acc9-0320-4b89-8cc8-475f04fe3948"
},
"evaluatedAt": "2026-09-23T18:42:40.625Z",
"explanation": "Mandate SHOP-001 authorizes this payment."
}
}POST/api/mandates/{id}/revoke
Revoke a mandate. Every later decision under it is refused.
Request
JSON
{
"reason": "Withdrawn by finance"
}Response 200
JSON
{
"ok": true,
"data": {
"mandateId": "fde3a3a0-8125-4ea1-b6fc-a3e1c7138ead",
"mandateReference": "SHOP-001",
"beneficiaryId": "9596acc9-0320-4b89-8cc8-475f04fe3948",
"rail": "sepa",
"payerId": "95df7fad-016c-4406-bd04-8ff13ac121ee",
"debtorName": "Merchant B.V.",
"debtorIban": "NL91ABNA0417164300",
"scheme": "agent_payout",
"mandateType": "recurring",
"currency": "EUR",
"maxAmount": 100,
"maxTotalAmount": 250,
"validFrom": "2026-09-23T18:42:40.621Z",
"validUntil": "2027-09-23T18:42:40.621Z",
"signedBy": "Finance",
"signedAt": "2026-09-23T18:42:40.622Z",
"signature": "mandate-sig-527a620bb6625e3bc2e9421163ff2714",
"status": "revoked",
"createdAt": "2026-09-23T18:42:40.622Z",
"updatedAt": "2026-09-23T18:42:40.861Z",
"history": [
{
"status": "active",
"timestamp": "2026-09-23T18:42:40.622Z",
"note": "Mandate SHOP-001 signed by Finance."
},
{
"status": "revoked",
"timestamp": "2026-09-23T18:42:40.861Z",
"note": "Withdrawn by finance"
}
]
}
}GET/api/mandates/{id}
Read a mandate. Same shape as the signing response.
GET/api/mandates
List mandates.
Response 200
JSON
{
"ok": true,
"data": {
"mandates": [
{
"mandateId": "fde3a3a0-8125-4ea1-b6fc-a3e1c7138ead",
"mandateReference": "SHOP-001",
"beneficiaryId": "9596acc9-0320-4b89-8cc8-475f04fe3948",
"rail": "sepa",
"payerId": "95df7fad-016c-4406-bd04-8ff13ac121ee",
"debtorName": "Merchant B.V.",
"debtorIban": "NL91ABNA0417164300",
"scheme": "agent_payout",
"mandateType": "recurring",
"currency": "EUR",
"maxAmount": 100,
"maxTotalAmount": 250,
"validFrom": "2026-09-23T18:42:40.621Z",
"validUntil": "2027-09-23T18:42:40.621Z",
"signedBy": "Finance",
"signedAt": "2026-09-23T18:42:40.622Z",
"signature": "mandate-sig-527a620bb6625e3bc2e9421163ff2714",
"status": "active",
"createdAt": "2026-09-23T18:42:40.622Z",
"updatedAt": "2026-09-23T18:42:40.622Z",
"history": [
{
"status": "active",
"timestamp": "2026-09-23T18:42:40.622Z",
"note": "Mandate SHOP-001 signed by Finance."
}
]
}
]
}
}