# Payment

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

## Create a payment

`POST /payments`

<a name="mandate_is_inactive"></a>Creates a new payment object.

This fails with a `mandate_is_inactive` error if the linked [mandate](#core-endpoints-mandates) is cancelled or has failed. Payments can be created against mandates with status of: `pending_customer_approval`, `pending_submission`, `submitted`, and `active`.

### Request body

Wrap request body attributes in a `payments` object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | string / integer | No | Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).  Minimum and maximum amounts vary by payment scheme. For more information, see [Transaction limits](https://support.gocardless.com/hc/en-gb/articles/115000309245-Transaction-limits)  For Variable Recurring Payments (VRP), this must not exceed the mandate's `max_amount_per_payment` constraint. |
| `currency` | string | No | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. |
| `description` | string | No | A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see [compliance requirements](#appendix-compliance-requirements)). |
| `charge_date` | string | No | A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the [mandate](#core-endpoints-mandates)'s `next_possible_charge_date` creation will fail. If the value is not a working day it will be rolled forwards to the next available one. |
| `reference` | string | No | An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.<br /> <strong>ACH</strong> - 10 characters<br /> <strong>Autogiro</strong> - 11 characters<br /> <strong>Bacs</strong> - 10 characters<br /> <strong>BECS</strong> - 30 characters<br /> <strong>BECS NZ</strong> - 12 characters<br /> <strong>Betalingsservice</strong> - 30 characters<br /> <strong>Faster Payments</strong> - 18 characters<br /> <strong>PAD</strong> - scheme doesn't offer references<br /> <strong>PayTo</strong> - 18 characters<br /> <strong>SEPA</strong> - 140 characters<br /> Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement. <p class='restricted-notice'><strong>Restricted</strong>: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the <a href='https://gocardless.com/pricing'>GoCardless Plus, Pro or Enterprise packages</a>.</p> <p class='restricted-notice'><strong>Restricted</strong>: You can not specify a payment reference for Faster Payments.</p> |
| `app_fee` | string / integer | No | The amount to be deducted from the payment as the OAuth app's fee, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). |
| `retry_if_possible` | boolean | No | On failure, automatically retry the payment using [intelligent retries](/success-plus/overview). Default is `false`. <p class="notice"><strong>Important</strong>: To be able to use intelligent retries, Success+ needs to be enabled in [GoCardless dashboard](https://manage.gocardless.com/success-plus). </p> |
| `faster_ach` | boolean | No | Set this to true or false in the request to create an ACH payment to explicitly choose whether the payment should be processed through Faster ACH or standard ACH, rather than relying on the presence or absence of the charge date to indicate that. |
| `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. |
| `psu_interaction_type` | string | No | Indicates how a Variable Recurring Payment (VRP) is initiated, by or on behalf of the payer.  - `in_session`: The payer is actively participating in the payment creation session. - `off_session`: The payer is not present during the transaction, and the payment is initiated by the merchant based on an established consent (e.g., a recurring subscription payment). |
| `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 payments

`GET /payments`

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

### Responses

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

---

## Get a single payment

`GET /payments/{payment_id}`

Retrieves the details of a single existing payment.

### Parameters

| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `payment_id` | path | string | Yes | The payment id |

### Responses

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

---

## Update a payment

`PUT /payments/{payment_id}`

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

### Parameters

| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `payment_id` | path | string | Yes | The payment id |

### Request body

Wrap request body attributes in a `payments` object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `retry_if_possible` | boolean | No | On failure, automatically retry the payment using [intelligent retries](/success-plus/overview). Default is `false`. <p class="notice"><strong>Important</strong>: To be able to use intelligent retries, Success+ needs to be enabled in [GoCardless dashboard](https://manage.gocardless.com/success-plus). </p> |
| `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 payment

`POST /payments/{payment_id}/actions/cancel`

Cancels the payment if it has not already been submitted to the banks. Any metadata supplied to this endpoint will be stored on the payment cancellation event it causes.

This will fail with a `cancellation_failed` error unless the payment's status is `pending_submission`.

### Parameters

| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `payment_id` | path | string | Yes | The payment id |

### Request body

Wrap request body attributes in a `payments` 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 |

---

## Retry a payment

`POST /payments/{payment_id}/actions/retry`

<a name="retry_failed"></a>Retries a failed payment if the underlying mandate is active. You will receive a `resubmission_requested` webhook, but after that retrying the payment follows the same process as its initial creation, so you will receive a `submitted` webhook, followed by a `confirmed` or `failed` event. Any metadata supplied to this endpoint will be stored against the payment submission event it causes.

This will return a `retry_failed` error if the payment has not failed.

Payments can be retried up to 3 times.

### Parameters

| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `payment_id` | path | string | Yes | The payment id |

### Request body

Wrap request body attributes in a `payments` 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. |
| `charge_date` | string | No | A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the [mandate](#core-endpoints-mandates)'s `next_possible_charge_date` creation will fail. If the value is not a working day it will be rolled forwards to the next available one. |

### Responses

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