Skip to main content

Report on a payment

You can extract reporting information from GOV.UK Pay manually or through 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 the GOV.UK Pay admin tool to export transaction information in a CSV file.

You can export one file for one service’s transactions, or one file for all your services’ transactions.

  1. Go to the Overview page in the GOV.UK Pay admin tool.

  2. If you want to export one service’s transactions, select the service account you want reporting information for, then select Transactions.

    You can also view transactions for all your live services if you want to export all your services’ transactions.

  3. Filter transactions using the available search criteria if needed.

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

    If you have more than 5000 transactions, you must apply a filter before the CSV file download link appears.

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 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
  • get a payment’s events
  • generate a list of payments matching search criteria

Get information about a single payment

GET /v1/payments/{PAYMENT_ID}

Replace {PAYMENT_ID} with the ID of the payment you are getting information about.

Example response:

{
  "created_date": "2019-07-11T10:36:26.988Z",
  "amount": 3750,
  "state": {
    "status": "success",
    "finished": true,
  },
  "description": "Pay your council tax",
  "reference": "12345",
  "language": "en",
  "metadata": {
    "ledger_code": "AB100",
    "an_internal_reference_number": 200
  },
  "email": "sherlock.holmes@example.com",
  "card_details": {
    "card_brand": "Visa",
    "card_type": "debit",
    "last_digits_card_number": "1234",
    "first_digits_card_number": "123456",
    "expiry_date": "04/24",
    "cardholder_name": "Sherlock Holmes",
    "billing_address": {
        "line1": "221 Baker Street",
        "line2": "Flat b",
        "postcode": "NW1 6XE",
        "city": "London",
        "country": "GB"
    }
  },
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "authorisation_summary": {
    "three_d_secure": {
      "required": true,
    }
  }
  "refund_summary": {
    "status": "available",
    "amount_available": 4000,
    "amount_submitted": 0
  },
  "settlement_summary": {
    "capture_submit_time": "2019-07-12T17:15:000Z",
    "captured_date": "2019-07-12",
    "settled_date": "2019-07-12"
  },
  "delayed_capture": false,
  "moto": false,
  "corporate_card_surcharge": 250,
  "total_amount": 4000,
  "fee": 200,
  "net_amount": 3800,
  "payment_provider": "worldpay",
  "provider_id": "10987654321",
  "return_url": "https://your.service.gov.uk/completed"
}

Your user can continue their journey through your service if, in the state object, the:

  • status field is success
  • finished field is true

API response parameters

The _links object includes href and method fields that you can use to make API requests related to the payment. Use:

authorisation_summary

If the payment was authenticated with 3D Secure (3DS), authorisation_summary and three_d_secure contain information about the authentication.

required is true if the payment required 3D Secure authentication.

authorisation_summary is only available for payments created on or after 1 September 2021.

card_details

If your user has gone far enough in their payment journey, the card_details section contains the information they entered when they made the payment. All the fields are strings.

billing_address will be null if you’ve disabled collecting your users’ billing addresses.

expiry_date is in MM/YY format, for example 04/24.

card_brand is one of the following:

  • American Express
  • Diners Club
  • Discover
  • Jcb
  • Maestro
  • Mastercard
  • Union Pay
  • Visa

card_type is one of the following:

  • credit
  • debit
  • null - if we did not recognise which type of card your user made the payment with, or your user used Google Pay.

corporate_card_surcharge

corporate_card_surcharge shows the surcharge amount in pence if you’ve set up adding corporate card fees.

created_date

created_date is when you created the payment, in ISO 8601 format.

delayed_capture

delayed_capture is true if you’re controlling how long it takes GOV.UK Pay to take (‘capture’) a payment.

fee

If you use GOV.UK’s payment service provider (PSP), fee is the PSP transaction fee that we took from the amount your user paid.

metadata

The metadata object includes any metadata keys and values you added when creating a payment. You can add custom metadata to new payments to help with reconciliation and reporting.

moto

moto is true if you took the payment over the phone.

net_amount

If you use GOV.UK’s PSP, net_amount is the amount that will be paid into your account after we take the PSP transaction fee.

payment_id

payment_id is the unique ID that GOV.UK Pay automatically generated for this payment.

payment_provider

payment_provider is the name of your PSP, or sandbox if you’re using a test (‘sandbox’) account.

refund_summary

You can use refund_summary to check if you can refund a payment.

return_url

return_url is the URL that your service hosts for your user to return to, after their payment journey on GOV.UK Pay ended.

settlement_summary

Use settlement_summary to check when your PSP:

state

Use state to see the status of the payment.

Checking when your PSP took a payment

You can see when your PSP took a payment from your user’s account.

The response contains:

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

For example:

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

If your PSP is Stripe, you should receive the payment in your bank account within:

  • 2 working days of captured_date if your user completed their payment during the week
  • 3 working days of captured_date if your user completed their payment at the weekend or on a bank holiday

You can confirm when payments are paid into your bank account by signing in to the GOV.UK Pay admin tool then selecting View payments to your bank account.

If your PSP is Government Banking’s contracted PSP (currently Worldpay), SmartPay or ePDQ, contact your PSP to find out your payment times.

PSP fees

If you use GOV.UK’s 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 an API key from your test (‘sandbox’) account - we do not deduct fees from payments in this account

To test transaction fees, you can request a test Stripe account from your account in the GOV.UK Pay admin tool.

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/{PAYMENT_ID}/events

Replace {PAYMENT_ID} with the ID of the payment you are getting the events of.

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

  • an updated field that shows when the state changed, in ISO 8601 format
  • what the state was updated to

The response starts with the oldest state.

For example:

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

Search payments

GET /v1/payments

Do not search payments using the API to check a payment’s status during payment flow. The payment status field in the search results does not immediately update and so 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

Example search response:

{
  "total": 100,
  "count": 20,
  "page": 2,
  "results": [
    {
      "amount": 1200,
      "description": "Pay your council tax",
      "reference": "12345",
      ...
    },
    {
      "amount": 600,
      "description": "Pay your council tax",
      "reference": "678910",
      ...
    },
  ],
  "_links": {
    "prev_page": {
      "href": "https://publicapi.payments.service.gov.uk/v1/payments?display_size=20&page=1",
      "method": "GET"
    },
    "next_page": {
      "href": "https://publicapi.payments.service.gov.uk/v1/payments?display_size=20&page=3",
      "method": "GET"
    }
    ...
  }
  ...
}

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
american-express American Express
diners-club Diners Club
discover Discover
jcb Jcb
maestro Maestro
master-card Mastercard
unionpay Union Pay
visa Visa

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

All dates are in Coordinated Universal Time (UTC).

Dates must be in ISO 8601 format and include a:

  • date
  • time in hours and minutes - seconds are optional
  • time zone designation

For example, 2019-09-20T13:30Z.

Filter payments by when your PSP sent payments to your bank account

If your PSP is Stripe, you can use the following query parameters to filter by when your PSP sent payments to your bank account:

  • from_settled_date - the start date for payments to be searched, inclusive
  • to_settled_date - the end date for payments to be searched, inclusive

All dates are in Coordinated Universal Time (UTC).

For example, to list all the payments your PSP sent to you on 16 June 2020:

GET /v1/payments?from_settled_date=2020-06-16&to_settled_date=2020-06-16

Dates must be in ISO 8601 format and include a date value only. For example, 2015-08-13.

If your PSP has not sent this payment to your bank account yet, the payment will not be in the response.

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.

The API response includes a _links object, which includes href and method fields you can use to move between pages. Use the fields in:

  • self to run the same search again
  • first_page to get the first page of results
  • last_page to get the last page
  • prev_page to get the previous page
  • next_page to get the next page