State Webhooks
Like for our other resources (Payments, Paylinks), merchants can subscribe to mandate state webhooks via POST/v2/webhooks. Mandate states include:
| Mandate State | Definition |
|---|---|
| created | A new Mandate resource has been created. |
| pending | Mandate is pending amendment authorization |
| active | Mandate is active and eligible for payment requests. |
| cancelled | Mandate has been cancelled by the consumer, payer bank, or merchant. |
| declined | Mandate creation or amendment has been declined by the consumer or payer bank. |
| expired | Mandate has passed its expiry date. |
| failed | Mandate creation was unsuccessful. |
| suspended | Mandate has been suspended (paused) by the consumer, payer bank, or merchant. |
Please note that separate calls are required to subscribe to Mandate and Payment webhooks.
Error Handling
Mandate related errors are communicated to merchants through both a state_reason and a latest_error object that provide additional context required to handle unhappy path scenarios.
Definitions:
state_reason: Provides context on any change in Mandate or Payment state for any reason.
latest_error: Provides context when a change in Mandate or Payment state is the result of error.
Mandate Errors:
| Reason / Error Code | Context |
|---|---|
| MANDATE_INELIGIBLE_AMOUNT | A payment failed because the amount was outside the parameters of the mandate agreement. |
| MANDATE_INELIGIBLE_COUNT | A payment failed because the transaction limit in the mandate agreement was exceeded. |
| MANDATE_EXPIRED | The mandate agreement has expired. |
| MANDATE_INACTIVE | The mandate is not active or has been suspended. |
| MANDATE_INELIGIBLE | The payment contents do not align with the agreement terms. |