Withdrawal
The Withdrawal API provides a buyer-facing flow for submitting a right-of-withdrawal declaration. The flow is three steps: initiate → verify session → submit.
NOTE
This API class is only available for webshops with the WITHDRAWAL_DECLARATION feature enabled. Requests must include the webshop UID in the context.
Methods
getConfig
Returns the configuration needed to render the withdrawal page. Text values are taken from the webshop's withdrawal settings for the given language, falling back to default text if no custom text is configured.
Parameters
| Parameter | Type | Description |
|---|
| language | string | The language code (ISO 639-1) for which to return the configured text, e.g. "sv". |
Returns
| Property | Type | Description |
|---|
| intro_text | string | Introductory body text to display on the withdrawal page. |
| heading | string | Heading text to display on the withdrawal page. |
Example
- API Console
- PHP
- JSON
- Response
Withdrawal.getConfig("sv")
initiate
Initiates a withdrawal submission. If the given email address matches the order with the given order number, a confirmation email is sent to that address. The email contains a personal link with a time-limited JWT required for the next step.
This method always returns true regardless of whether a match was found, to prevent email-address enumeration.
Parameters
| Parameter | Type | Description |
|---|
| email | string | The email address of the buyer. |
| orderNumber | integer | The order number to submit a withdrawal for. |
Returns
Always returns true.
Example
- API Console
- PHP
- JSON
- Response
Withdrawal.initiate("buyer@example.com", 12345)
Errors
| Code | Data | Description |
|---|
| -32602 | Invalid e-mail address provided | The email parameter was empty. |
| -32602 | Invalid order number provided | The orderNumber parameter was negative. |
verifySession
Verifies the JWT from the initiation email and returns the order details needed to display a confirmation screen before the buyer submits the declaration.
Parameters
| Parameter | Type | Description |
|---|
| token | string | The JWT received from the initiation email link. |
Returns
| Property | Type | Description |
|---|
| order_number | integer | The order number being withdrawn. |
| buyer_name | string or null | Full name of the buyer, or null if not available. |
| buyer_email | string | Email address of the buyer. |
Example
- API Console
- PHP
- JSON
- Response
Withdrawal.verifySession("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example")
Errors
| Code | Data | Description |
|---|
| -32602 | expired_token | The token has expired. The buyer must restart the flow with initiate. |
| -32602 | invalid_token | The token is invalid or does not match the webshop. |
submit
Submits the withdrawal declaration. The token from the initiation email is required to authenticate the submission. An optional message from the buyer can be included.
Parameters
| Parameter | Type | Description |
|---|
| token | string | The JWT received from the initiation email link. |
| message | string or null | An optional message from the buyer. Whitespace-only values are treated as null. |
Returns
| Property | Type | Description |
|---|
| declaration_id | integer | The unique identifier of the created withdrawal declaration. |
Example
- API Console
- PHP
- JSON
- Response
Withdrawal.submit("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example", "I changed my mind about this order.")
Errors
| Code | Data | Description |
|---|
| -32602 | expired_token | The token has expired. The buyer must restart the flow with initiate. |
| -32602 | invalid_token | The token is invalid or does not match the webshop. |
Abicart API