Skip to main content

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 reporting 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. You can read more about what happens when creating payments.
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.

You can read more about filtering by date.
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.

You can read more about filtering by date.
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 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,
      "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.
    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:SSZ.
    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:SSZ.

    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.

    card_details only appears if the paying user has 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.
    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.

    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.