--- title: "Search payments" method: GET path: "/v1/payments" tags: ["Card payments"] --- # Search payments `GET /v1/payments` 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 - `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 --- [API](https://skmtc.net/government-digital-service/apis/gov-uk-pay-api.md) · [All operations](https://skmtc.net/government-digital-service/apis/gov-uk-pay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/government-digital-service/gov-uk-pay-api/revisions/4dc2d80f453a/schema)