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

# Search payments

`GET /v1/payments`

Search payments by reference, state, 'from' and 'to' date. The Authorisation token needs to be specified in the 'authorization' header as 'authorization: Bearer YOUR_API_KEY_HERE'

## 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

## Response `200`

OK

- PaymentSearchResults
  - `total` integer
  - `count` integer
  - `page` integer
  - `_links` SearchNavigationLinks — Links to navigate through pages
    - `self` Link — A link related to a payment
      - `href` string
      - `method` string
    - `first_page` Link — A link related to a payment
      - `href` string
      - `method` string
    - `last_page` Link — A link related to a payment
      - `href` string
      - `method` string
    - `prev_page` Link — A link related to a payment
      - `href` string
      - `method` string
    - `next_page` Link — A link related to a payment
      - `href` string
      - `method` string
  - `results` PaymentDetailForSearch[]
    - `amount` integer
    - `description` string
    - `reference` string
    - `language` 'en' | 'cy'
    - `metadata` object
    - `email` string
    - `state` PaymentState — A structure representing the current state of the payment in its lifecycle.
      - `status` string — Current progress of the payment in its lifecycle
      - `finished` boolean — Whether the payment has finished
      - `message` string — What went wrong with the Payment if it finished with an error - English message
      - `code` string — What went wrong with the Payment if it finished with an error - error code
    - `payment_id` string
    - `payment_provider` string
    - `created_date` string
    - `refund_summary` RefundSummary — A structure representing the refunds availability
      - `status` string — Availability status of the refund
      - `amount_available` integer — Amount available for refund in pence
      - `amount_submitted` integer — Amount submitted for refunds on this Payment in pence
    - `settlement_summary` PaymentSettlementSummary — A structure representing information about a settlement
      - `capture_submit_time` string — Date and time capture request has been submitted. May be null if capture request was not immediately acknowledged by payment gateway.
      - `captured_date` string — Date of the capture event.
      - `settled_date` string — The date that the transaction was paid into the service's account.
    - `card_details` CardDetails — A structure representing the payment card
      - `last_digits_card_number` string
      - `first_digits_card_number` string
      - `cardholder_name` string
      - `expiry_date` string — The expiry date of the card in MM/yy format
      - `billing_address` Address — A structure representing the billing address of a card
        - `line1` string
        - `line2` string
        - `postcode` string
        - `city` string
        - `country` string
      - `card_brand` string
      - `card_type` 'debit' | 'credit' | 'null' — The card type, `debit` or `credit` or `null` if not able to determine
    - `delayed_capture` boolean — delayed capture flag
    - `moto` boolean — Mail Order / Telephone Order (MOTO) payment flag
    - `corporate_card_surcharge` integer
    - `total_amount` integer
    - `fee` integer — processing fee taken by the GOV.UK Pay platform, in pence. Only available depending on payment service provider
    - `net_amount` integer — amount including all surcharges and less all fees, in pence. Only available depending on payment service provider
    - `provider_id` string
    - `return_url` string
    - `_links` PaymentLinksForSearch — links for search payment resource
      - `self` Link — A link related to a payment
        - `href` string
        - `method` string
      - `cancel` PostLink — A POST link related to a payment
        - `type` string
        - `params` object
        - `href` string
        - `method` string
      - `events` Link — A link related to a payment
        - `href` string
        - `method` string
      - `refunds` Link — A link related to a payment
        - `href` string
        - `method` string
      - `capture` PostLink — A POST link related to a payment
        - `type` string
        - `params` object
        - `href` string
        - `method` string
    - `card_brand` string — Card Brand

## Other responses

- `401` — Credentials are required to access this resource
- `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

---

[API](https://skmtc.net/alphagov/apis/gov-uk-pay-api.md) · [All operations](https://skmtc.net/alphagov/apis/gov-uk-pay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/alphagov/gov-uk-pay-api/versions/262275a01170/schema)