Skip to main content
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. Select the account you want reporting information for in the My Service section.

  2. Go to the transactions list.

  3. Filter transactions using the available search criteria.

  4. 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.

You can export up to 100,000 transactions.

Reporting via the GOV.UK Pay API

Before reading this section, you should be familiar with making payments.

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

See the GOV.UK Pay API browser for more details

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 your 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 your 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": {
  "card_type": "debit",
  "card_brand": "visa",
  "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"
  }
}

The card_type is null if we did not recognise which type of card your user made the payment with.

Checking when your Payment Service Provider (PSP) took a payment

If your PSP is Worldpay, you can see when Worldpay took a payment from your user’s account.

The response contains:

  • capture_submit_time if we’ve asked Worldpay to take the payment from your user’s account
  • captured_date if Worldpay has taken the payment

For example:

"settlement_summary": {
  "capture_submit_time": "2016-01-21T17:15:000Z",
  "captured_date": "2016-01-21"
}

You should receive the payment in your bank account within 2 business days of captured_date.

PSP fees

If you use GOV.UK’s Payment Service Provider (PSP), we’ll automatically deduct the PSP’s transaction fee from each payment. You can see how much the fee was when you make the API call to get information about a payment.

Example response:

"total_amount": 4000,
"fee": 200,
"net_amount": 3800

Where:

  • total_amount is the amount your user paid in pence, including a corporate card surcharge if you added one
  • fee is the PSP transaction fee that we took from the amount your user paid, in pence
  • net_amount is the amount that will be paid into your account, in pence

The response will not contain a fee or net_amount parameter if either:

  • your PSP is SmartPay, Worldpay or ePDQ - we do not deduct these PSPs’ transaction fees
  • you’re using a test API key - we do not deduct fees from test payments

You can also sign in to the GOV.UK Pay admin tool to see transaction fee information or export the information in a CSV file.

Get a payment’s events

Use the following API call to get a list of a payment’s events:

GET /v1/payments/paymentId/events

The API will respond with an events object. For each change to the payment’s state, the events object includes:

  • when the state changed
  • what the state was updated to

The response starts with the oldest state.

For example:

{
    "events": [
        {
            "payment_id": "9co6rdsak0btz4wuxac0a29i4a",
            "state": {
                "status": "created",
                "finished": false
            },
            "updated": "2019-07-11T10:36:26.988Z",
        },
        {
            "payment_id": "9co6rdsak0btz4wuxac0a29i4a",
            "state": {
                "status": "failed",
                "finished": true,
                "message": "Payment expired",
                "code": "P0020"
            },
            "updated": "2019-07-11T12:11:35.849Z",
        }
    ],
}

Generate a list of payments (search payments)

GET /v1/payments

See the GOV.UK Pay API browser for more details

Do not search payments using the API to check a payment’s status during payment flow. Search results are asynchronous so the payment status may not be up-to-date.

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 - case insensitive, exact match only
  • email - case insensitive
  • cardholder_name - case insensitive
  • state - case sensitive, exact match only
  • first_digits_card_number - exact match only
  • last_digits_card_number - exact match only

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.

Search by card brand

card_brand to search for card_brand in API response
visa Visa
master-card Mastercard
maestro Maestro
american-express American Express
diners-club Diners Club
discover Discover
jcb Jcb
unionpay Union Pay

card_brand is case insensitive. You cannot search for partial values of card_brand.

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 the ISO 8601 standard. 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.