# Mandate

Source: https://docs.gocardless.com/docs/api-reference/mandate

## Create a mandate

`POST /mandates`

Creates a new mandate object.

### Request body

Wrap request body attributes in a `mandates` object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reference` | string | No | Unique reference. Different schemes have different length and [character set](#appendix-character-sets) requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank. |
| `scheme` | string | No | <a name="mandates_scheme"></a>Bank payment scheme to which this mandate and associated payments are submitted. Can be supplied or automatically detected from the customer's bank account. |
| `payer_ip_address` | string | No | For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).  Not required for creating offline mandates where `authorisation_source` is set to telephone or paper. |
| `metadata` | object | No | Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters. |
| `authorisation_source` | string | No | This field is ACH specific, sometimes referred to as [SEC code](https://www.moderntreasury.com/learn/sec-codes).  This is the way that the payer gives authorisation to the merchant.   web: Authorisation is Internet Initiated or via Mobile Entry (maps to SEC code: WEB)   telephone: Authorisation is provided orally over telephone (maps to SEC code: TEL)   paper: Authorisation is provided in writing and signed, or similarly authenticated (maps to SEC code: PPD) |
| `links` | object | No |  |

### Responses

| Status | Description |
| --- | --- |
| 201 | Resource created successfully |
| 400 | Bad Request |
| 401 | Unauthorised |
| 404 | Not found |
| 422 | Validation Error |
| 500 | Internal Error |

---

## List mandates

`GET /mandates`

Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your mandates.

### Responses

| Status | Description |
| --- | --- |
| 200 | Successful response |
| 400 | Bad Request |
| 401 | Unauthorised |
| 404 | Not found |
| 422 | Validation Error |
| 500 | Internal Error |

---

## Get a single mandate

`GET /mandates/{mandate_id}`

Retrieves the details of an existing mandate.

### Parameters

| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `mandate_id` | path | string | Yes | The mandate id |

### Responses

| Status | Description |
| --- | --- |
| 200 | Successful response |
| 400 | Bad Request |
| 401 | Unauthorised |
| 404 | Not found |
| 422 | Validation Error |
| 500 | Internal Error |

---

## Update a mandate

`PUT /mandates/{mandate_id}`

Updates a mandate object. This accepts only the metadata parameter.

### Parameters

| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `mandate_id` | path | string | Yes | The mandate id |

### Request body

Wrap request body attributes in a `mandates` object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `metadata` | object | No | Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters. |

### Responses

| Status | Description |
| --- | --- |
| 200 | Successful response |
| 400 | Bad Request |
| 401 | Unauthorised |
| 404 | Not found |
| 422 | Validation Error |
| 500 | Internal Error |

---

## Cancel a mandate

`POST /mandates/{mandate_id}/actions/cancel`

Immediately cancels a mandate and all associated cancellable payments. Any metadata supplied to this endpoint will be stored on the mandate cancellation event it causes.

This will fail with a `cancellation_failed` error if the mandate is already cancelled.

### Parameters

| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `mandate_id` | path | string | Yes | The mandate id |

### Request body

Wrap request body attributes in a `mandates` object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `metadata` | object | No | Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters. |

### Responses

| Status | Description |
| --- | --- |
| 200 | Action completed successfully |
| 400 | Bad Request |
| 401 | Unauthorised |
| 404 | Not found |
| 422 | Validation Error |
| 500 | Internal Error |

---

## Reinstate a mandate

`POST /mandates/{mandate_id}/actions/reinstate`

<a name="mandate_not_inactive"></a>Reinstates a cancelled or expired mandate to the banks. You will receive a `resubmission_requested` webhook, but after that reinstating the mandate follows the same process as its initial creation, so you will receive a `submitted` webhook, followed by a `reinstated` or `failed` webhook up to two working days later. Any metadata supplied to this endpoint will be stored on the `resubmission_requested` event it causes.

This will fail with a `mandate_not_inactive` error if the mandate is already being submitted, or is active.

Mandates can be resubmitted up to 10 times.

### Parameters

| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `mandate_id` | path | string | Yes | The mandate id |

### Request body

Wrap request body attributes in a `mandates` object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `metadata` | object | No | Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters. |

### Responses

| Status | Description |
| --- | --- |
| 200 | Action completed successfully |
| 400 | Bad Request |
| 401 | Unauthorised |
| 404 | Not found |
| 422 | Validation Error |
| 500 | Internal Error |