Table of contents

Reporting

You can extract reporting information from GOV.UK Pay manually or via the API, for each service you have set up in GOV.UK Pay.

You can also read about refunding payments, including how to search for refunds using the GOV.UK Pay API.

Manual reporting

You can use your GOV.UK Pay admin account to export transaction information in a CSV file.

  1. For the account you want reporting information for, select Transactions in the Dashboard page.

  2. Filter transactions using the available search criteria.

  3. Select Download all transaction details as a CSV file.

The CSV file contains all transaction data, which is much more comprehensive than the information on the Transactions page. You can process CSV files using spreadsheet software and edit the contents you do not need.

Reporting via the GOV.UK Pay API

Before reading this section, you should be familiar with the ‘Making payments’ section.

You can get data from the GOV.UK Pay API in a format suitable for automatic processing. For example, you could develop software to query the GOV.UK Pay API for payment data periodically and import the data into your finance system. This could remove routine manual operations from your workflow and lead to significant cost savings for your organisation.

You can use the GOV.UK Pay API to:

  • get information about a single payment
  • generate a list of payments matching search criteria

Get information about a single payment

GET /v1/payments/paymentId

  1. Sign in to the API Explorer (link opens in new window).
  2. Under Resource, select {Payment Id}.
  3. Under Action, select Find payment by ID (link opens in new window).

If the payment exists, the JSON response body to this API call contains a "state" field. You can use this information when designing a service.

For example, the response for a successful payment contains:

  "state": {
    "status": "success",
    "finished": true
    },

With a successful payment, you know that the user can continue their journey through your service.

For a valid request, the JSON response body to this API call also contains other useful information. For example, if a user has gone far enough in their payment journey, the "card_details" section contains information that they have entered when making a payment:

  "card_details": {
    "last_digits_card_number": "1111",
    "first_digits_card_number": "100002",
    "cardholder_name": "Sherlock Holmes",
    "expiry_date": "12/21",
    "billing_address": {
      "line1": "221 Baker Street",
      "line2": "Flat b",
      "postcode": "NW16XE",
      "city": "London",
      "country": "GB"
    },

Generate a list of payments (search payments)

GET /v1/payments

  1. Sign in to the API Explorer (link opens in new window).
  2. Under Resource, select General.
  3. Under Action, select Search payments (link opens in new window).

Search criteria

An example search request:

GET /v1/payments?from_date=2018-10-01T13:30:00Z&to_date=2018-10-14T15:00:00Z&reference=12345&state=success

Some of the query parameters you can use to search for payments are:

  • reference
  • email
  • state
  • card_brand
  • first_digits_card_number
  • last_digits_card_number
  • cardholder_name

If you search for a specific payment, all criteria you use must match. Otherwise, that payment will not be returned in the results.

If your request has no query parameters, the API will return all payments.

Filter by date

You can use the following query parameters to filter payments by date:

  • from_date - the start date for payments to be searched, inclusive
  • to_date - the end date for payments to be searched, exclusive

These take inputs based on a subset of ISO 8601 (link opens in new window). For example, a valid input would be 2015-08-13T12:35:00Z.

Pagination

You can use the following query parameters for pagination:

  • display-size - default, and maximum, is 500
  • page - default is 1

These must be a positive integer. For example, for the following search:

GET /v1/payments?from_date=2018-10-01T13:30:00Z&to_date=2018-10-14T15:00:00Z

If there were 1543 payments in the response, you could paginate this as follows:

GET /v1/payments?from_date=2018-10-01T13:30:00Z&to_date=2018-10-14T15:00:00Z&display-size=500&page=2

This would return payments 501-1000.