Skip to main content

Reconcile and report on payments

The GOV.UK Pay admin tool and API have features to make it easier for finance teams to reconcile money received into your bank account or to automate the reconciliation process.

This page covers:

How payouts work

The way payments come into your bank account is different depending on whether your PSP is Worldpay or Stripe.

How Worldpay payouts work

You will receive one payment into your bank account for each Worldpay merchant code.

If you have more than one service in Pay, you can choose to use the same merchant code for each service or a different merchant code for each one.

If you have multiple services on one merchant code, you can use our reporting API to find all the transactions that are on that merchant code. Alternatively, select View transactions for all your services in the admin tool to download a CSV with this information. The merchant code itself is not shown in the API or the CSV, but you can use the description line to find the relevant transactions.

You can change what is shown on your bank statement for the payment in the Worldpay settings.

How Stripe payouts work

You will receive one payment into your bank account for each Stripe service you have in Pay.

You can choose to have multiple types of transaction going through one service (e.g. licensing and council tax, or parking fines and parking permits), or you can choose to have separate services for each type of transaction. You can use the description you set when you created a payment to help you determine what that payment was for.

The reporting API and the CSV download will show the transaction fees paid on each transaction.

You can download a report showing the total amount you received from Stripe in each payout and all the transactions that make up that payout. You can find this in ‘My services’.

The payout from Stripe will appear on your bank statement with a description based on your service’s name. If you want to change this description, just contact the GOV.UK Pay team.

The minimum payout for Stripe is £1.

Find payments

You can find payments in the GOV.UK Pay admin tool or through the API.

GOV.UK Pay retains payment data for 7 years. You can generate reports that show transaction volumes and values from over 7 years ago, but you will not be able to get information about individual transactions. You can read more about how we handle your data.

Use the admin tool to find payments

When you log into the GOV.UK Pay admin tool, you can view transactions for all your services or payments made to your bank account.

You can find payments using:

  • a reference number
  • a user’s email address
  • the payment status (for example in disputed, refunded, in progress)
  • the payment amount
  • the date you created the payment
  • the user’s card details

When you select a payment, you can see the history of the payment. For example, you can see when your service created the payment and when the user paid.

You can also download a CSV spreadsheet of all your selected payments to help with reconciliation. You can download one report for all your services or one report for each separate service.

You can also see payments made to your bank account by following the link from My services. This is only available for live Stripe accounts and test Stripe accounts.

Use the API to find payments

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
  • get a list of payments matching search criteria

Get information about a single payment

Use the following endpoint to 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"
}

The response contains:

  • when you created the payment (created_date)
  • the payment amount, in pence (amount)
  • the status of the payment (state)
  • details you sent when you created the payment (reference, description, metadata)

You can see definitions and possible values for every attribute in this response in our API reference for getting information about a single payment.

You can also read about the full payment status lifecycle and what it means for your service and your user.

Use the API to check when your PSP took a payment

You can see when your payment service provider (PSP) took a payment from your user’s account.

The response from GET /v1/payments/{PAYMENT_ID} 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

In this example, GOV.UK Pay asked the PSP to take the payment from the user’s account at 5:15pm on 21 January 2022 and the PSP took the payment on the same day:

"settlement_summary": {
  "capture_submit_time": "2022-01-21T17:15:000Z",
  "captured_date": "2022-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 Stripe makes payments 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 Worldpay, contact Worldpay support to find out your payment times.

PSP fees

If your PSP is Stripe, 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 request to get information about a payment.

In this example, we’ve deducted a £2 PSP fee (fee) from the user’s £40 payment (amount), meaning a £38 net amount (net_amount) will be paid into your account:

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

Stripe may charge transaction fees on failed payments. If this happens, net_amount will be a negative number. From 6 April 2022, Stripe will take negative net amounts from your Stripe account balance. For example, a net_amount of -200 on a payment will take £2.00 from your Stripe 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.

If your PSP is Worldpay, you can see your transaction fees on your Worldpay invoices.

Get a payment’s events

A payment event is when a payment reaches a milestone in its journey and its state updates, such as when it’s created, paid, or refunded.

Use the following API request 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:

  • when the payment’s state changed (updated)
  • what the payment’s state changed to (state)

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"
          },
      }
  ],
}

You can see definitions and possible values of every attribute for this endpoint in our API reference.

Get notified of payment state changes

You can create webhooks to notify you when payments reach certain states. Read our guidance about using webhooks to get automatic payment updates.

Get a list of payments matching search criteria

Use the following API request to search for payments from your service:

GET /v1/payments

Read our API reference for a full index of the query parameters you can use to filter your search.

If you do not include query parameters in your request, this endpoint returns all payments.

Do not use this endpoint to check a payment’s status during the payment flow. Data from this endpoint is updated on a delay and may not be up to date.

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

Example 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"
    }
    ...
  }
  ...
}

You can see definitions and possible values of every attribute for this endpoint in our API reference.

Check your payments are correct (‘reconciliation’)

GOV.UK Pay has functionality that makes it easier to do regular reconciliation.

You can:

You can set up which bank accounts your payments go to and get information about payments you’ve received in the admin tool or using the API.

If you take payments through Apple Pay or Google Pay, familiarise yourself with the cardholder information we store for digital wallet payments. This information is different from what we store for online payments, and could affect your reconciliation process.

Reconcile payments with the admin tool

The GOV.UK Pay admin tool can help you reconcile your payments. You can:

Download transaction information

You can use the GOV.UK Pay admin tool to download transaction information in a CSV file. You can import this into your finance systems. You can download 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.

  1. Filter transactions using the available search criteria if needed.
  2. Select Download all transaction details as a CSV file.

If you have more than 5,000 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.

If you want to automate this process you can use the API.

Set payment references

If you’re using payment pages, you can ask your user to enter a reference they already have, for example an invoice number or their name when they pay. If they do not have a reference already, Pay can generate one for them and send this to them with the confirmation of their payment. Most services choose to have the user enter the reference.

Users will also see this reference number in the payment confirmation email.

Set payment descriptions

You can use payment descriptions to help identify which type of service a user is paying for. This is also shown to the user on the payment page and in the payment confirmation email.

Add additional information your users will not be able to see (‘custom metadata’ or ‘reporting columns’)

If you’re using payment pages, you can add metadata by adding reporting columns in the GOV.UK Pay admin tool.

Custom metadata lets you add more information to payments. For example, you can add an identifier from your finance or accounting system to help you reconcile the payments later.

If you added metadata to a payment using the API, you can still see that metadata in the GOV.UK Pay admin tool. You can also use metadata to find payments in the admin tool.

Reconcile payments with the API

You can integrate your finance and accounting systems with GOV.UK Pay using the API.

For example, you could automatically fetch data about the outcome of payment journeys. You could import that into your finance system so payments can be reconciled against bank transaction information.

To help you reconcile payments, you can:

Add more information to a payment (‘custom metadata’ or ‘reporting columns’)

You can use custom metadata to add more information to new payments when creating them through our API. For example, you can add an identifier from your finance or accounting system to help you reconcile the payment later.

Paying users cannot see metadata while they’re making a payment.

Include a metadata object in the body of your request to create a new payment.

This example request creates a payment for a £100 fine and adds a ledger code and an internal reference number as metadata:

POST /v1/payments

{
  "amount": 10000,
  "reference" : "WA5678",
  "description": "Pay a fine for a late tax filing.",
  "return_url": "https://your.service.gov.uk/completed",
  "metadata": {
    "ledger_code": "AB100",
    "an_internal_reference_number": 200
  }
}

The metadata object must contain between 1 and 10 parameters as key-value pairs.

Each parameter key must be a unique, case-insensitive string between 1 and 30 characters long. If 2 or more keys are identical, the API will remove all but one of the identical keys from the metadata object.

The data type of each parameter value must be either a:

  • string of no more than 100 characters
  • number
  • boolean

Parameter values can be empty.

The API response will include your metadata.

You cannot add or change metadata keys or values after you’ve created the payment request.

Getting a payment’s metadata in the API

When you get information about a single payment or get a list of payments, the API response will include the metadata object.

The order of the parameters in the metadata object may be different to your original object.

Get a payment’s settlement information

Payments are ‘settled’ when your PSP sends funds to your bank account. Settlement data helps you reconcile your payments by telling you when an individual payment entered your bank account.

The GOV.UK Pay API can give you payment settlement data in the settled_date attribute in YYYY-MM-DD format. You can also find payments based on when they were settled.

To get settlement information about a single payment, get information about that payment through our API.

To get settlement information about multiple payments, get a list of payments through our API. Use the from_settled_date and to_settled_date query parameters to only include payments that were settled within a specific date range.

Read more about the settlement_summary object in our API reference pages for getting information about a single payment and searching for payments.

Get a list of payments that match your search criteria

You can use the GOV.UK Pay API to get a list of payments that match certain criteria. For example, you could get a list of successful payments that arrived in your bank account between 1 January 2023 and 31 January 2023.

You can use these lists of payments to help your reconciliation process.

Read about how to get a list of payments here or in our API reference.

Change what appears on your users’ bank statements

To change what appears on your users’ bank statements, you can either: