REST API
Authorization
POST/api/authorize
Ask whether a payment may proceed. The answer is a signed receipt. fundsReserved is always false: an approval permits a payment, it does not hold money.
Approved:
Request
JSON
{
"mandateId": "fde3a3a0-8125-4ea1-b6fc-a3e1c7138ead",
"amount": 50,
"beneficiaryId": "9596acc9-0320-4b89-8cc8-475f04fe3948"
}Response 200
JSON
{
"ok": true,
"data": {
"receiptId": "auth_93c446d771524834b72915e906ed06b6",
"decision": "approved",
"mandateId": "fde3a3a0-8125-4ea1-b6fc-a3e1c7138ead",
"mandateReference": "SHOP-001",
"payer": "NL91ABNA0417164300",
"payee": "DE89370400440532013000",
"payeeName": "Acme Supplies BV",
"amount": "50.00",
"currency": "EUR",
"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": [],
"explanation": "Mandate SHOP-001 authorizes this payment.",
"remainingAmount": 250,
"issuedAt": "2026-09-23T18:42:40.626Z",
"expiresAt": "2026-09-23T18:47:40.626Z",
"fundsReserved": false,
"signature": "auth-sig-e7647acd85cda9a233f73d96271278a72cd0a024d58cb598336e306fbe92f74a"
}
}Refused, over the per-payment limit and the total:
Request
JSON
{
"mandateId": "fde3a3a0-8125-4ea1-b6fc-a3e1c7138ead",
"amount": 500,
"beneficiaryId": "9596acc9-0320-4b89-8cc8-475f04fe3948"
}Response 200
JSON
{
"ok": true,
"data": {
"receiptId": "auth_5f16ca3670e74f4f8f4cb67d9bf465e8",
"decision": "refused",
"mandateId": "fde3a3a0-8125-4ea1-b6fc-a3e1c7138ead",
"mandateReference": "SHOP-001",
"payer": "NL91ABNA0417164300",
"payee": "DE89370400440532013000",
"payeeName": "Acme Supplies BV",
"amount": "500.00",
"currency": "EUR",
"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": false,
"detail": "Payment amount 500 EUR exceeds the per-payment limit of 100 EUR."
},
{
"name": "cumulative_limit",
"passed": false,
"detail": "Mandate total after this payment would be 500, above the cumulative limit of 250 EUR."
}
],
"failedChecks": [
"per_payment_limit",
"cumulative_limit"
],
"explanation": "Payment amount 500 EUR exceeds the per-payment limit of 100 EUR. Mandate total after this payment would be 500, above the cumulative limit of 250 EUR.",
"remainingAmount": 250,
"issuedAt": "2026-09-23T18:42:40.627Z",
"expiresAt": "2026-09-23T18:47:40.627Z",
"fundsReserved": false,
"signature": "auth-sig-85dcbfcf5fd3b4b7e4c56566445700915e5fa80a386b7a13a5804d7e7b8ccf94"
}
}POST/api/authorize/verify
Verify a receipt you were handed. Any edit breaks signatureValid.
Request
JSON
{
"receipt": {
"receiptId": "auth_93c446d771524834b72915e906ed06b6",
"decision": "approved",
"mandateId": "fde3a3a0-8125-4ea1-b6fc-a3e1c7138ead",
"mandateReference": "SHOP-001",
"payer": "NL91ABNA0417164300",
"payee": "DE89370400440532013000",
"payeeName": "Acme Supplies BV",
"amount": "50.00",
"currency": "EUR",
"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": [],
"explanation": "Mandate SHOP-001 authorizes this payment.",
"remainingAmount": 250,
"issuedAt": "2026-09-23T18:42:40.626Z",
"expiresAt": "2026-09-23T18:47:40.626Z",
"fundsReserved": false,
"signature": "auth-sig-e7647acd85cda9a233f73d96271278a72cd0a024d58cb598336e306fbe92f74a"
}
}Response 200
JSON
{
"ok": true,
"data": {
"signatureValid": true,
"expired": false,
"decision": "approved",
"usable": true,
"explanation": "Receipt is valid, unexpired, and records an approval."
}
}