---
title: "List payments"
method: GET
path: "/payments"
tags: ["Payment"]
---

# List payments

`GET /payments`

## Request

- Base URL: `https://api.gocardless.com`
- URL: `https://api.gocardless.com/payments`
- Auth: HTTP bearer

Returns a [cursor-paginated](https://docs.gocardless.com/docs/api-reference/data-conventions#cursor-pagination) list of your payments.

## Query parameters

- `before` string, nullable
- `after` string, nullable
- `limit` union
  - integer
  - string
- `created_at` object
  - `gt` string, date-time: Limit to records created after the specified date-time.
  - `lt` string, date-time: Limit to records created before the specified date-time.
  - `gte` string, date-time: Limit to records created on or after the specified date-time.
  - `lte` string, date-time: Limit to records created on or before the specified date-time.
- `currency` 'AUD' | 'CAD' | 'DKK' | 'EUR' | 'GBP' | 'NZD' | 'SEK' | 'USD': [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.
- `charge_date` object
  - `gt` string, date: Limit to records where the payment was or will be collected from the customer's bank account after the specified date.
  - `lt` string, date: Limit to records where the payment was or will be collected from the customer's bank account before the specified date.
  - `gte` string, date: Limit to records where the payment was or will be collected from the customer's bank account on or after the specified date.
  - `lte` string, date: Limit to records where the payment was or will be collected from the customer's bank account on or before the specified date.
- `customer` string: ID of a customer to filter payments by. If you pass this parameter, you cannot also pass `creditor`.
- `sort_field` 'charge_date' | 'amount': Field by which to sort records. One of: - `charge_date` - `amount`
- `sort_direction` 'asc' | 'desc': The direction to sort in. One of: - `asc` - `desc`
- `creditor` string: ID of a creditor to filter payments by. If you pass this parameter, you cannot also pass `customer`.
- `subscription` string: Unique identifier, beginning with "SB".
- `mandate` string: Unique identifier, beginning with "MD". Note that this prefix may not apply to mandates created before 2016.
- `status` 'pending_customer_approval' | 'pending_submission' | 'submitted' | 'confirmed' | 'paid_out' | 'cancelled' | 'customer_approval_denied' | 'failed' | 'charged_back': One of: - `pending_customer_approval`: we're waiting for the customer to approve this payment - `pending_submission`: the payment has been created, but not yet submitted to the banks - `submitted`: the payment has been submitted to the banks - `confirmed`: the payment has been confirmed as collected - `paid_out`: the payment has been included in a [payout](https://docs.gocardless.com/docs/api-reference/payout) - `cancelled`: the payment has been cancelled - `customer_approval_denied`: the customer has denied approval for the payment. You should contact the customer directly - `failed`: the payment failed to be processed. Note that payments can fail after being confirmed if the failure message is sent late by the banks. - `charged_back`: the payment has been charged back
- `scheme` string, nullable: A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to", "sepa_core", "sepa_credit_transfer" and "sepa_instant_credit_transfer" are supported.
- `include` string

## Headers

- `GoCardless-Version` string, required

## Response `200`

Successful response

- PaymentMultiResourceResponse
  - `payments` Payment[]
    - `id` string, required: Unique identifier, beginning with "PM".
    - `created_at` string, date-time, required: Fixed [timestamp](https://docs.gocardless.com/docs/api-reference/data-conventions#dates-and-times), recording when this resource was created.
    - `amount` integer, required: 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.
    - `amount_refunded` integer, required: Amount [refunded](https://docs.gocardless.com/docs/api-reference/refund), in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
    - `currency` 'AUD' | 'CAD' | 'DKK' | 'EUR' | 'GBP' | 'NZD' | 'SEK' | 'USD', required: [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, nullable, required: 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](https://docs.gocardless.com/docs/api-reference/compliance-requirements)).
    - `charge_date` string, date, nullable, required: 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](https://docs.gocardless.com/docs/api-reference/mandate)'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, nullable, required: 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>
    - `metadata` CustomerMetadata, required: 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.
    - `status` 'pending_customer_approval' | 'pending_submission' | 'submitted' | 'confirmed' | 'paid_out' | 'cancelled' | 'customer_approval_denied' | 'failed' | 'charged_back', required: One of: - `pending_customer_approval`: we're waiting for the customer to approve this payment - `pending_submission`: the payment has been created, but not yet submitted to the banks - `submitted`: the payment has been submitted to the banks - `confirmed`: the payment has been confirmed as collected - `paid_out`: the payment has been included in a [payout](https://docs.gocardless.com/docs/api-reference/payout) - `cancelled`: the payment has been cancelled - `customer_approval_denied`: the customer has denied approval for the payment. You should contact the customer directly - `failed`: the payment failed to be processed. Note that payments can fail after being confirmed if the failure message is sent late by the banks. - `charged_back`: the payment has been charged back
    - `app_fee` integer, nullable: 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). Only present if the payment was created via an app.
    - `links` PaymentLinks, required
      - `mandate` string: ID of the [mandate](https://docs.gocardless.com/docs/api-reference/mandate) against which this payment should be collected.
      - `creditor` string: ID of [creditor](https://docs.gocardless.com/docs/api-reference/creditor) to which the collected payment will be sent.
      - `payout` string: ID of [payout](https://docs.gocardless.com/docs/api-reference/payout) which contains the funds from this payment.<br/>_Note_: this property will not be present until the payment has been successfully collected.
      - `subscription` string: ID of [subscription](https://docs.gocardless.com/docs/api-reference/subscription) from which this payment was created.<br/>_Note_: this property will only be present if this payment is part of a subscription.
      - `instalment_schedule` string: ID of [instalment_schedule](https://docs.gocardless.com/docs/api-reference/instalment-schedule) from which this payment was created.<br/>**Note**: this property will only be present if this payment is part of an instalment schedule.
    - `faster_ach` boolean, nullable: This field indicates whether the ACH payment is processed through Faster ACH or standard ACH. It is only present in the API response for ACH payments.
    - `fx` PaymentFx, required
      - `exchange_rate` string, nullable: Rate used in the foreign exchange of the `amount` into the `fx_currency`. Present only after a resource is paid out. Has up to 10 decimal places.
      - `estimated_exchange_rate` string, nullable: Estimated rate that will be used in the foreign exchange of the `amount` into the `fx_currency`. This will vary based on the prevailing market rate until the moment that it is paid out. Present only before a resource is paid out. Has up to 10 decimal places.
      - `fx_amount` union: Amount that was paid out in the `fx_currency` after foreign exchange. Present only after the resource has been paid out.
        - string, nullable
        - integer
      - `fx_currency` 'AUD' | 'CAD' | 'DKK' | 'EUR' | 'GBP' | 'NZD' | 'SEK' | 'USD', nullable: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) code for the currency in which amounts will be paid out (after foreign exchange). Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. Present only if payouts will be (or were) made via foreign exchange.
    - `retry_if_possible` boolean, required: On failure, automatically retry the payment using [intelligent retries](https://docs.gocardless.com/docs/optimise/reduced-failed-payments-with-success-plus). 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>
    - `scheme` string, nullable, required: A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to", "sepa_core", "sepa_credit_transfer" and "sepa_instant_credit_transfer" are supported.
  - `meta` PaymentPaginationMeta: Cursor pagination information
    - `limit` integer, required
    - `cursors` object, required
      - `before` string, nullable, required: Cursor pointing to the end of the desired set.
      - `after` string, nullable, required: Cursor pointing to the start of the desired set.

## Other responses

- `400`: Bad Request
- `401`: Unauthorised
- `404`: Not found
- `422`: Validation Error
- `500`: Internal Error

---

[API](https://skmtc.dev/gocardless/apis/gocardless-api.md) - [All operations](https://skmtc.dev/gocardless/apis/gocardless-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gocardless/apis/gocardless-api/revisions/4dd3dae45364?raw)