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

Use the following API call 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.

Checking 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 call 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 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:

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

Search payments

Use the following API call 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.

Search payment response

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

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