---
title: "Search payments"
method: GET
path: "/v1/payments"
tags: ["Card payments"]
---

# Search payments

`GET /v1/payments`

## Request

- Base URL: `https://publicapi.payments.service.gov.uk`
- URL: `https://publicapi.payments.service.gov.uk/v1/payments`
- Auth: HTTP bearer

You can use this endpoint to [search for payments you’ve previously created](https://docs.payments.service.gov.uk/reporting/#search-payments/). Payments are sorted by date, with the most recently-created payment appearing first.

## Query parameters

- `reference` string
- `email` string
- `state` 'created' | 'started' | 'submitted' | 'success' | 'failed' | 'cancelled' | 'error'
- `card_brand` string
- `from_date` string
- `to_date` string
- `page` string
- `display_size` string
- `cardholder_name` string
- `first_digits_card_number` string
- `last_digits_card_number` string
- `from_settled_date` string
- `to_settled_date` string
- `agreement_id` string

## Response `200`

OK - your request was successful.

- PaymentSearchResults
  - `_links` SearchNavigationLinks: Links to navigate through pages of your search.
    - `first_page` Link: A link related to a payment
      - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
    - `last_page` Link: A link related to a payment
      - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
    - `next_page` Link: A link related to a payment
      - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
    - `prev_page` Link: A link related to a payment
      - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
    - `self` Link: A link related to a payment
      - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
  - `count` integer: Number of payments on the current page of search results.
  - `page` integer: The [page of results you’re viewing](https://docs.payments.service.gov.uk/api_reference/#pagination). To view other pages, make this request again using the `page` parameter.
  - `results` PaymentDetailForSearch[]: Contains payments matching your search criteria.
    - `_links` PaymentLinksForSearch: links for search payment resource
      - `cancel` PostLink: A POST link related to a payment
        - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`.
        - `method` string
        - `params` object
        - `type` string
      - `capture` PostLink: A POST link related to a payment
        - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`.
        - `method` string
        - `params` object
        - `type` string
      - `events` Link: A link related to a payment
        - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`.
        - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
      - `refunds` Link: A link related to a payment
        - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`.
        - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
      - `self` Link: A link related to a payment
        - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`.
        - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
    - `agreement_payment_type` 'instalment' | 'recurring' | 'unscheduled': When the customer initiates a standing order agreement transaction we have to include a customerInitiatedReason attribute. This can have a value of `instalment`, `recurring`, or `unscheduled`.
    - `amount` integer: The description assigned to the payment when it was created.
    - `authorisation_mode` 'web' | 'moto_api' | 'external': How the payment will be authorised. Payments created in `web` mode require the paying user to visit the `next_url` to complete the payment.
    - `authorisation_summary` AuthorisationSummary: Object containing information about the authentication of the payment.
      - `three_d_secure` ThreeDSecure: Object containing information about the 3D Secure authentication of the payment.
        - `required` boolean: Indicates if this payment was authorised with 3D Secure authentication. `required` is `true` if the payment required 3D Secure authentication.
    - `card_brand` string: This attribute is deprecated. Please use `card_details.card_brand` instead.
    - `card_details` CardDetails: A structure representing the payment card
      - `billing_address` Address: A structure representing the billing address of a card
        - `city` string: The paying user's city.
        - `country` string: The paying user’s country, displayed as a 2-character ISO-3166-1-alpha-2 code.
        - `line1` string: The first line of the paying user’s address.
        - `line2` string: The second line of the paying user’s address.
        - `postcode` string: The paying user's postcode.
      - `card_brand` string: The brand of card the user paid with.
      - `card_type` 'debit' | 'credit' | 'null': The type of card the user paid with.`null` means your user paid with Google Pay or we did not recognise which type of card they paid with.
      - `cardholder_name` string
      - `expiry_date` string: The expiry date of the card the user paid with in `MM/YY` format.
      - `first_digits_card_number` string
      - `last_digits_card_number` string
      - `wallet_type` 'Apple Pay' | 'Google Pay': The digital wallet type that the user paid with
    - `corporate_card_surcharge` integer: The [corporate card surcharge](https://docs.payments.service.gov.uk/corporate_card_surcharges/#add-corporate-card-fees) amount in pence.
    - `created_date` string
    - `delayed_capture` boolean: `delayed_capture` is `true` if you’re [controlling how long it takes GOV.UK Pay to take (‘capture’) a payment](https://docs.payments.service.gov.uk/delayed_capture).
    - `description` string: The description assigned to the payment when it was created.
    - `email` string
    - `exemption` Exemption: A structure representing that 3DS exemption was requested and the outcome of the exemption, if applicable.
      - `outcome` Outcome: A structure representing the outcome of a 3DS exemption, if known.
        - `result` string: The outcome of the requested exemption
      - `requested` boolean: Indicates whether an exemption was requested for the given payment.
      - `type` string: Indicates the type of exemption. Only present for corporate exemption
    - `fee` integer: The [payment service provider’s (PSP) transaction fee](https://docs.payments.service.gov.uk/reporting/#psp-fees), in pence. `fee` only appears when we have taken (‘captured’) the payment from the user or if their payment fails after they submitted their card details. `fee` will not appear if your PSP is Worldpay or you are using an API key from a test service.
    - `language` 'en' | 'cy': The ISO-6391 Alpha-2 code of the [language of the user's payment page](https://docs.payments.service.gov.uk/optional_features/welsh_language).
    - `metadata` ExternalMetadata
      - `metadata` object, required
    - `moto` boolean: Indicates if this payment is a [Mail Order / Telephone Order (MOTO) payment](https://docs.payments.service.gov.uk/moto_payments).
    - `net_amount` integer: The amount, in pence, that will be paid into your bank account after your payment service provider takes the `fee`.
    - `payment_id` string: The unique ID GOV.UK Pay automatically associated with this payment when you created it.
    - `payment_provider` string: The payment service provider that processed this payment.
    - `provider_id` string: The unique ID your payment service provider generated for this payment. This is not the same as the `payment_id`.
    - `reference` string: The reference associated with the payment when it was created. `reference` is not unique - multiple payments can have the same `reference` value.
    - `refund_summary` RefundSummary: A structure representing the refunds availability
      - `amount_available` integer: How much you can refund to the user, in pence.
      - `amount_submitted` integer: How much you’ve already refunded to the user, in pence.
      - `status` string: Whether you can [refund the payment](https://docs.payments.service.gov.uk/refunding_payments/#checking-the-status-of-a-refund-status).
    - `return_url` string: The URL you direct the paying user to after their payment journey on GOV.UK Pay ends.
    - `settlement_summary` PaymentSettlementSummary: A structure representing information about a settlement
      - `capture_submit_time` string: The date and time GOV.UK Pay asked your payment service provider to take the payment from your user’s account. This value uses Coordinated Universal Time (UTC) and ISO 8601 format - `YYYY-MM-DDThh:mm:ss.SSSZ`
      - `captured_date` string: The date your payment service provider took the payment from your user. This value uses ISO 8601 format - `YYYY-MM-DD`
      - `settled_date` string: The date that the transaction was paid into the service's account.
    - `state` PaymentState: A structure representing the current state of the payment in its lifecycle.
      - `can_retry` boolean, nullable: If `can_retry` is `true`, you can use this agreement to try to take another recurring payment. If `can_retry` is `false`, you cannot take another recurring payment with this agreement. `can_retry` only appears on failed payments that were attempted using an agreement for recurring payments.
      - `code` string: An [API error code](https://docs.payments.service.gov.uk/api_reference/#gov-uk-pay-api-error-codes)that explains why the payment failed. `code` only appears if the payment failed.
      - `finished` boolean: Indicates whether a payment journey is finished.
      - `message` string: A description of what went wrong with this payment. `message` only appears if the payment failed.
      - `status` string: Where the payment is in [the payment status lifecycle](https://docs.payments.service.gov.uk/api_reference/#payment-status-meanings).
    - `total_amount` integer: Amount your user paid in pence, including corporate card fees. `total_amount` only appears if you [added a corporate card surcharge to the payment](https://docs.payments.service.gov.uk/corporate_card_surcharges/#add-corporate-card-fees).
  - `total` integer: Total number of payments matching your search criteria.

## Other responses

- `401`: Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)
- `422`: Invalid parameters: from_date, to_date, status, display_size. See Public API documentation for the correct data formats
- `429`: Too many requests
- `500`: Downstream system error

## Changes

- **2026-10-13** `6dc4b2c91eb8`: 1 info
  - the response property `results/items/metadata/metadata` became required for the status `200`
- **2025-10-03** `4dc2d80f453a`: 1 info
  - added the optional property `results/items/agreement_payment_type` to the response with the `200` status
- **2025-02-10** `79a24d1c3a34`: 1 info
  - added the optional property `results/items/exemption` to the response with the `200` status
- **2024-12-18** `eafdca6d5023`: 1 warning
  - removed the optional property `results/items/exemption` from the response with the `200` status
- **2024-12-18** `376f6a312f08`: 1 info
  - added the optional property `results/items/exemption` to the response with the `200` status

[Operation history](https://skmtc.dev/government-digital-service/apis/gov-uk-pay-api/changes/v1/payments/get.md)

---

[API](https://skmtc.dev/government-digital-service/apis/gov-uk-pay-api.md) - [All operations](https://skmtc.dev/government-digital-service/apis/gov-uk-pay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/government-digital-service/apis/gov-uk-pay-api/revisions/6dc4b2c91eb8?raw)