Search payments API reference

This page is part of GOV.UK Pay’s API reference and is an index of the following you’ll use when searching for payments:

parameters
example requests
example responses
attributes you’ll get in your response

You can also read more about how searching for payments fits into the GOV.UK Pay reconciliation process in our task-based guidance.

The URL for this endpoint is:

GET https://publicapi.payments.service.gov.uk/v1/payments

You can use this endpoint to search payments you’ve previously created. The payments are sorted by date, with the most recently-created payments appearing first.

The data from this endpoint is ‘eventually consistent’, meaning it is updated on a delay. You can read more about data consistency in our API.

Query parameters for ‘Search payments’

Your request will return payments that match all of the criteria specified in your query parameters.

If your request has no query parameters, this endpoint returns all payments.

Name	Type	Description
`reference`	string	Returns payments with `reference` values exactly matching your specified value. This parameter is not case sensitive. A `reference` was associated with the payment when that payment was created.
`email`	string	Returns payments with matching `email` values. You can use full or partial email addresses. The `email` value is the paying user’s email address. It was entered either by the service when the payment was created or by the paying user when they completed their payment. You can read more about prefilling payment fields.
`state`	string	Returns payments in a matching `state`. `state` reflects where a payment is in the payment status lifecycle. You can read more about the payment status lifecycle and the meaning of different `state` values. Available `state` values are: `created` `started` `submitted` `capturable` `success` `failed` `cancelled` `error`
`card_brand`	string	Returns payments paid with a particular card brand. Available `card_brand` values are: `american-express` `diners-club` `discover` `jcb` `maestro` `master-card` `unionpay` `visa`
`from_date`	date (ISO 8601)	Returns payments created on or after the `from_date`. Date and time must be coordinated Universal Time (UTC) and ISO 8601 format to second-level accuracy - `YYYY-MM-DDThh:mm:ssZ`.
`to_date`	date (ISO 8601)	Returns payments created before the `to_date`. Date and time must be coordinated Universal Time (UTC) and ISO 8601 format to second-level accuracy - `YYYY-MM-DDThh:mm:ssZ`.
`page`	number	Returns a specific page of results. Defaults to `1`. You can read more about search pagination.
`display_size`	number	The number of payments returned per results page. Defaults to `500`. Maximum value is `500`. You can read more about search pagination.
`cardholder_name`	string	Returns payments paid with cards under this cardholder name.
`first_digits_card_number`	number	Returns payments paid by cards beginning with the `first_digits_card_number` value. `first_digits_card_number` value must be 6 digits.
`last_digits_card_number`	number	Returns payments paid by cards ending with the `last_digits_card_number` value. `last_digits_card_number` value must be 4 digits.
`from_settled_date`	date (ISO 8601)	Returns payments settled on or after the `from_settled_date` value. You can only search by settled date if your payment service provider is Stripe. Date must be in ISO 8601 format to date-level accuracy - `YYYY-MM-DD`. Payments are settled when your payment service provider sends funds to your bank account.
`to_settled_date`	date (ISO 8601)	Returns payments settled before the `to_settled_date` value. You can only search by settled date if your payment service provider is Stripe. Date must be in ISO 8601 format to date-level accuracy - `YYYY-MM-DD`. Payments are settled when your payment service provider sends funds to your bank account.
`agreement_id`	string	Returns payments that were authorised using the agreement with this `agreement_id`. Must be an exact match.

Example request for ‘Search payments’

This example request is a payment search filtered to return payments that were created on or after 8:30am on 15 January 2021:

curl -X GET "https://publicapi.payments.service.gov.uk/v1/payments?from_date=2021-01-15T08:30:00Z" -H "Authorization: Bearer api_test_123abc456def"

Example response for ‘Search payments’

After you send your request to search payments, you’ll receive a response similar to this example:

{
  "total": 100,
  "count": 20,
  "page": 1,
  "results": [
    {
      "amount": 1200,
      "authorisation_mode": "web",
      "authorisation_summary": {
        "three_d_secure": {
        "required": true,
        }
      },
      "description": "Pay your council tax.",
      "reference": "12345",
      "language": "en",
      "email": "sherlock.holmes@example.com",
      "state": {
        "status": "success",
        "finished": true
      },
      "payment_id": "hu20sqlact5260q2nanm0q8u93",
      "payment_provider": "sandbox",
      "created_date": "2021-04-07T09:49:36.631Z",
      "refund_summary": {
        "status": "available",
        "amount_available": 7000,
        "amount_submitted": 5000
      },
      "settlement_summary": {
        "capture_submit_time": "2021-04-07T09:53:46.084Z",
        "captured_date": "2021-04-07"
      },
      "card_details": {
        "last_digits_card_number": "1111",
        "first_digits_card_number": "444433",
        "cardholder_name": "MR RALPH ELLISON",
        "expiry_date": "10/23",
        "billing_address": {
          "line1": "52 Invisible Street",
          "line2": "Flat 581",
          "postcode": "IN5 M4N",
          "city": "London",
          "country": "GB"
        },
        "card_brand": "Visa",
        "card_type": "credit"
      },
      "delayed_capture": false,
      "moto": false,
      "total_amount": 12000,
      "provider_id": "4718b3be-d765-4bcd-a7aa-4c2fcbb986cf",
      "return_url": "https://stripe.com/docs/payments/checkout/custom-success-page",
      "_links": {
        "self": {
          "href": "https://publicapi.payments.service.gov.uk/v1/payments/hu20sqlact5260q2nanm0q8u93",
          "method": "GET"
        },
        "cancel": null,
        "events": {
          "href": "https://publicapi.payments.service.gov.uk/v1/payments/hu20sqlact5260q2nanm0q8u93/events",
          "method": "GET"
        },
        "refunds": {
          "href": "https://publicapi.payments.service.gov.uk/v1/payments/hu20sqlact5260q2nanm0q8u93/refunds",
          "method": "GET"
        },
        "capture": null
      },
      "card_brand": "Visa"
    }
    {
      "amount": 1200,
      "description": "Pay your council tax.",
      "reference": "12345",
      . . .
    }
    ]
  "_links": {
    "self": {
      "href": "https://publicapi.payments.service.gov.uk/v1/payments?from_date=2021-01-01T08%3A00%3A00Z&display_size=500&state=success&page=1"
        },
      "first_page": {
            "href": "https://publicapi.payments.service.gov.uk/v1/payments?from_date=2021-01-01T08%3A00%3A00Z&display_size=500&state=success&page=1"
      },
      "last_page": {
            "href": "https://publicapi.payments.service.gov.uk/v1/payments?from_date=2021-01-01T08%3A00%3A00Z&display_size=500&state=success&page=1"
      }
    }
  }
}

Attributes you’ll get in a ‘Search payments’ response

Name	Type	Description
`total`	number	Number of total payments matching your search criteria.
`count`	number	Number of payments on the current page of search results.
`page`	number	The page of results you’re viewing. To view other pages, make this request again using the `page` parameter. You can read more about search pagination.
`results`	object	Contains payments matching your search criteria.
`amount`	number	The amount, in pence, the user has paid or will pay.
`description`	string	The description assigned to the payment when it was created.
`reference`	string	The reference associated with the payment when it was created. `reference` is not unique - multiple payments can have the same `reference` value.
`language`	string	The language of the user’s payment page. Possible values are: `en` (English) `cy` (Welsh)
`metadata`	object	Contains any custom metadata you added to the payment when it was created. Read more about adding custom metadata to payments.
`state`	object	Contains information about where the payment is in its journey. Read more about the payment status lifecycle.
`state.status`	string	Where the payment is in the payment status lifecycle. Possible values are: `created` `started` `submitted` `capturable` `success` `failed` `cancelled` `error` You can read more about the payment status lifecycle and the meanings of each payment status.
`state.finished`	boolean	Indicates whether a payment journey is finished. A finished payment journey does not always mean the user has made a payment. For example, a user may submit their payment details but their bank rejects the payment - the payment journey is `finished` but no payment has actually been made.
`state.can_retry`	boolean	Indicates whether you can try to take another payment using the associated agreement for recurring payments. 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. You can read more about handling failed recurring payments.
`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 (PSP) that processed this payment.
`created_date`	date (ISO 8601)	The date and time you created this payment. This value uses Coordinated Universal Time (UTC) and ISO 8601 format - `YYYY-MM-DDThh:mm:ss.sssZ`.
`agreement_id`	string	The unique ID of the agreement for recurring payments that GOV.UK Pay used to take this payment. `agreement_id` only appears if `authorisation_mode` is `agreement` or if a payment was used to set up an agreement for recurring payments.
`refund_summary`	object	Contains information about refunds on this payment, such as refund availability. You can read more about refunding payments.
`refund_summary.status`	string	Whether you can refund the payment. Possible values are: `pending` `unavailable` `available` `full` You can read about the meanings of each refund `status` value.
`refund_summary.amount_available`	number	The amount you can refund to the user, in pence.
`refund_summary.amount_submitted`	number	The amount you’ve already refunded to the user, in pence.
`settlement_summary`	object	Contains information about when this payment was settled. A payment is settled when your payment service provider transfers it to your bank account.
`settlement_summary.capture_submit_time`	date (ISO 8601)	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`. `capture_submit_time` only appears if GOV.UK Pay has asked your PSP to take the payment.
`settlement_summary.captured_date`	date (ISO 8601)	The date your payment service provider took the payment from your user. This value appears in ISO 8601 format - `YYYY-MM-DD`. `captured_date` only appears if your payment service provider has taken the payment.
`settlement_summary.settled_date`	date (ISO 8601)	The date your payment service provider sent the payment to your bank account as part of a payout. This value appears in ISO 8601 format - `YYYY-MM-DD`. `settled_date` only appears if your payment service provider is Stripe and they have sent the payment to your bank account.
`card_details`	object	Contains details about the card the user paid with. If your user paid with a digital wallet, some information in `card_details` may not match your user’s physical card. This is because of how Apple Pay and Google Pay handle cardholder information. `card_details` does not appear if the paying user has not completed this payment.
`card_details.last_digits_card_number`	number	The last 4 digits of the card the user paid with.
`card_details.first_digits_card_number`	number	The first 6 digits of the card the user paid with.
`card_details.cardholder_name`	string	The cardholder name the user entered when they paid.
`card_details.expiry_date`	string	The expiry date of the card the user paid with.
`card_details.billing_address`	object	Contains the billing address the paying user entered when they paid. `billing_address` can contain: `line1` (the first line of the paying user’s address) `line2` (the second line of the paying user’s address) `postcode` (the paying user’s postcode) `city` (the paying user’s city) `country` (the paying user’s country, displayed as a 2-character ISO-3166-1-alpha-2 code)
`card_details.card_brand`	string	The brand of card the user paid with. Available `card_brand` values are: `american-express` `diners-club` `discover` `Jcb` `maestro` `master-card` `unionpay` `visa`
`card_details.card_type`	string	The type of card the user paid with. Possible values are: `credit` `debit` `null` `null` means your user paid with Google Pay or we did not recognise which type of card they paid with.
`card_details.wallet_type`	string	The digital wallet the user paid with. Possible values are: `Apple Pay` `Google Pay` `wallet_type` only appears if the user paid with a digital wallet. You can read more about taking digital wallet payments.
`delayed_capture`	boolean	`delayed_capture` is `true` if you’re controlling how long it takes GOV.UK Pay to take (‘capture’) a payment. You can read more about delaying taking a payment.
`moto`	boolean	Indicates if this payment is a Mail Order / Telephone Order (MOTO) payment. You can read more about taking payments over the phone.
`total_amount`	number	Amount your user paid in pence, including corporate card fees. `total_amount` only appears if you added a corporate card surcharge to the payment. You can read more about corporate card surcharges..
`fee`	number	The payment service provider’s transaction fee, 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. You can read more about PSP fees.
`net_amount`	number	The amount, in pence, that’ll be paid into your bank account after your payment service provider takes the `fee`.
`provider_id`	string	The unique ID your payment service provider generated for this payment. `provider_id` only appears after the user has submitted their payment details and GOV.UK Pay has tried to authorise the payment with your PSP. This is not the same as the `payment_id`.
`return_url`	string	The URL you directed the paying user to after their payment journey on GOV.UK Pay ended. You can read more about choosing your return URL and matching the paying user to a payment.
`authorisation_mode`	string	How GOV.UK Pay will authorise this payment. Possible values are: `web` `moto_api` `agreement` `authorisation_mode` is set when you create a payment. You can read more about the different authorisation modes in our API reference page for creating payments.
`results._links`	object	Contains URLs and methods for actions related to this payment.
`results._links.self`	object	Contains an API method and endpoint to get information about this payment. A `GET` request (`method`) to this endpoint (`href`) returns information about this payment.
`results._links.cancel`	object	Contains an API method and endpoint to cancel this payment. A `POST` request (`method`) to this endpoint (`href`) cancels this payment. You can read more about cancelling a payment that’s in progress. `cancel` value is `null` if the payment cannot be cancelled.
`results._links.events`	object	Contains an API method and endpoint to get this payment’s events. A `GET` request (`method`) to this endpoint (`href`) returns information about this payment’s events. You can read more about getting a payment’s events.
`results._links.refunds`	object	Contains an API method and endpoint to get refund information about this payment. A `GET` request (`method`) to this endpoint (`href`) returns refund information for this payment. You can read more about refunding payments.
`results._links.capture`	object	Contains an API method and endpoint to take (‘capture’) this payment from a user’s bank account. A `POST` request (`method`) to this endpoint (`href`) captures this payment. You can read more about capturing delayed payments.
`_links`	object	Contains links you can use to move between the pages of this search.
`_links.self`	object	Use this URL (`href`) to run the same search again.
`_links.first_page`	object	Use this URL (`href`) to get the first page of results.
`_links.last_page`	object	Use this URL (`href`) to get the last page of results.
`_links.next_page`	object	Use this URL (`href`) to get the next page of results.
`_links.prev_page`	object	Use this URL (`href`) to get the previous page of results.