# Payout
Source: https://docs.gocardless.com/docs/api-reference/payout
## List payouts
`GET /payouts`
Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your payouts.
### Parameters
| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `before` | query | string \| null | No | Cursor pointing to the end of the desired set. |
| `after` | query | string \| null | No | Cursor pointing to the start of the desired set. |
| `limit` | query | | No | Number of records to return. |
| `created_at` | query | object | No | |
| `creditor` | query | string | No | Unique identifier, beginning with "CR". |
| `creditor_bank_account` | query | string | No | Unique identifier, beginning with "BA". |
| `currency` | query | enum | 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. |
| `status` | query | enum | No | One of: - `pending`: the payout has been created, but not yet sent to your bank or it is in the process of being exchanged through our FX provider. - `paid`: the payout has been sent to the your bank. FX payouts will become `paid` after we emit the `fx_rate_confirmed` webhook. - `bounced`: the payout bounced when sent, the payout can be retried. |
| `reference` | query | string | No | Reference which appears on the creditor's bank statement. |
| `payout_type` | query | enum | No | Whether a payout contains merchant revenue or partner fees. |
| `metadata` | query | 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. _Note:_ This should not be used for storing PII data. |
### Responses
| Status | Description |
| --- | --- |
| 200 | Successful response |
| 400 | Bad Request |
| 401 | Unauthorised |
| 404 | Not found |
| 422 | Validation Error |
| 500 | Internal Error |
### Response body
Each item in the `payouts` array has the following attributes.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier, beginning with "PO". |
| `created_at` | string | Yes | Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created. |
| `amount` | integer | Yes | Amount in minor unit (e.g. pence in GBP, cents in EUR). |
| `deducted_fees` | integer | Yes | Fees that have already been deducted from the payout amount in minor unit (e.g. pence in GBP, cents in EUR), inclusive of tax if applicable.
For each `late_failure_settled` or `chargeback_settled` action, we refund the transaction fees in a payout. This means that a payout can have a negative `deducted_fees` value.
This field is calculated as `(GoCardless fees + app fees + surcharge fees) - (refunded fees)`
If the merchant is invoiced for fees separately from the payout, then `deducted_fees` will be 0. |
| `currency` | enum | Yes | [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. |
| `reference` | string | Yes | Reference which appears on the creditor's bank statement. |
| `status` | enum | Yes | One of: - `pending`: the payout has been created, but not yet sent to your bank or it is in the process of being exchanged through our FX provider. - `paid`: the payout has been sent to the your bank. FX payouts will become `paid` after we emit the `fx_rate_confirmed` webhook. - `bounced`: the payout bounced when sent, the payout can be retried. |
| `payout_type` | enum | Yes | Whether a payout contains merchant revenue or partner fees. |
| `arrival_date` | string \| null | Yes | Date the payout is due to arrive in the creditor's bank account. One of: - `yyyy-mm-dd`: the payout has been paid and is due to arrive in the creditor's bank account on this day - `null`: the payout hasn't been paid yet |
| `links` | object | Yes | |
| `fx` | object | Yes | |
| `tax_currency` | string \| null | Yes | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) code for the currency in which tax is paid out to the tax authorities of your tax jurisdiction. Currently “EUR”, “GBP”, for French or British merchants, this will be `null` if tax is not applicable beta |
| `metadata` | object | Yes | 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. _Note:_ This should not be used for storing PII data. |
### Error body
Errors are wrapped in an `error` object.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | integer | No | |
| `documentation_url` | string | No | |
| `errors` | array | Yes | |
| `message` | string | Yes | |
| `request_id` | string | Yes | |
| `type` | string | No | |
---
## Get a single payout
`GET /payouts/{payout_id}`
Retrieves the details of a single payout. For an example of how to reconcile the transactions in a payout, see [this guide](#events-reconciling-payouts-with-events).
### Parameters
| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `payout_id` | path | string | Yes | The payout id |
### Responses
| Status | Description |
| --- | --- |
| 200 | Successful response |
| 400 | Bad Request |
| 401 | Unauthorised |
| 404 | Not found |
| 422 | Validation Error |
| 500 | Internal Error |
### Response body
The response is wrapped in a `payouts` object.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier, beginning with "PO". |
| `created_at` | string | Yes | Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created. |
| `amount` | integer | Yes | Amount in minor unit (e.g. pence in GBP, cents in EUR). |
| `deducted_fees` | integer | Yes | Fees that have already been deducted from the payout amount in minor unit (e.g. pence in GBP, cents in EUR), inclusive of tax if applicable.
For each `late_failure_settled` or `chargeback_settled` action, we refund the transaction fees in a payout. This means that a payout can have a negative `deducted_fees` value.
This field is calculated as `(GoCardless fees + app fees + surcharge fees) - (refunded fees)`
If the merchant is invoiced for fees separately from the payout, then `deducted_fees` will be 0. |
| `currency` | enum | Yes | [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. |
| `reference` | string | Yes | Reference which appears on the creditor's bank statement. |
| `status` | enum | Yes | One of: - `pending`: the payout has been created, but not yet sent to your bank or it is in the process of being exchanged through our FX provider. - `paid`: the payout has been sent to the your bank. FX payouts will become `paid` after we emit the `fx_rate_confirmed` webhook. - `bounced`: the payout bounced when sent, the payout can be retried. |
| `payout_type` | enum | Yes | Whether a payout contains merchant revenue or partner fees. |
| `arrival_date` | string \| null | Yes | Date the payout is due to arrive in the creditor's bank account. One of: - `yyyy-mm-dd`: the payout has been paid and is due to arrive in the creditor's bank account on this day - `null`: the payout hasn't been paid yet |
| `links` | object | Yes | |
| `fx` | object | Yes | |
| `tax_currency` | string \| null | Yes | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) code for the currency in which tax is paid out to the tax authorities of your tax jurisdiction. Currently “EUR”, “GBP”, for French or British merchants, this will be `null` if tax is not applicable beta |
| `metadata` | object | Yes | 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. _Note:_ This should not be used for storing PII data. |
### Error body
Errors are wrapped in an `error` object.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | integer | No | |
| `documentation_url` | string | No | |
| `errors` | array | Yes | |
| `message` | string | Yes | |
| `request_id` | string | Yes | |
| `type` | string | No | |
---
## Update a payout
`PUT /payouts/{payout_id}`
Updates a payout object. This accepts only the metadata parameter.
### Parameters
| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `payout_id` | path | string | Yes | The payout id |
### Request body
Wrap request body attributes in a `payouts` 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 |
### Response body
The response is wrapped in a `payouts` object.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier, beginning with "PO". |
| `created_at` | string | Yes | Fixed [timestamp](#api-usage-dates-and-times), recording when this resource was created. |
| `amount` | integer | Yes | Amount in minor unit (e.g. pence in GBP, cents in EUR). |
| `deducted_fees` | integer | Yes | Fees that have already been deducted from the payout amount in minor unit (e.g. pence in GBP, cents in EUR), inclusive of tax if applicable.
For each `late_failure_settled` or `chargeback_settled` action, we refund the transaction fees in a payout. This means that a payout can have a negative `deducted_fees` value.
This field is calculated as `(GoCardless fees + app fees + surcharge fees) - (refunded fees)`
If the merchant is invoiced for fees separately from the payout, then `deducted_fees` will be 0. |
| `currency` | enum | Yes | [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. |
| `reference` | string | Yes | Reference which appears on the creditor's bank statement. |
| `status` | enum | Yes | One of: - `pending`: the payout has been created, but not yet sent to your bank or it is in the process of being exchanged through our FX provider. - `paid`: the payout has been sent to the your bank. FX payouts will become `paid` after we emit the `fx_rate_confirmed` webhook. - `bounced`: the payout bounced when sent, the payout can be retried. |
| `payout_type` | enum | Yes | Whether a payout contains merchant revenue or partner fees. |
| `arrival_date` | string \| null | Yes | Date the payout is due to arrive in the creditor's bank account. One of: - `yyyy-mm-dd`: the payout has been paid and is due to arrive in the creditor's bank account on this day - `null`: the payout hasn't been paid yet |
| `links` | object | Yes | |
| `fx` | object | Yes | |
| `tax_currency` | string \| null | Yes | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) code for the currency in which tax is paid out to the tax authorities of your tax jurisdiction. Currently “EUR”, “GBP”, for French or British merchants, this will be `null` if tax is not applicable beta |
| `metadata` | object | Yes | 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. _Note:_ This should not be used for storing PII data. |
### Error body
Errors are wrapped in an `error` object.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | integer | No | |
| `documentation_url` | string | No | |
| `errors` | array | Yes | |
| `message` | string | Yes | |
| `request_id` | string | Yes | |
| `type` | string | No | |