canonical: https://jentic.com/apis/payments.service.gov.uk/govuk-pay

# Payments Service GOV.UK Pay API

The GOV.UK Pay API enables UK government services to accept online payments from citizens. It provides 10 endpoints for creating payment sessions, capturing delayed payments, processing refunds, and retrieving payment event histories. The API handles card payments through a government-hosted payment page, eliminating PCI compliance burden from service teams while providing full programmatic control over the payment lifecycle.

## For AI agents

Create payment sessions, capture delayed payments, issue refunds, and track payment events for UK government digital services through GOV.UK Pay.

## Scope

Does not handle direct card tokenization, recurring subscriptions, or non-GBP currencies - use for UK government service one-time payment collection only.

## Capabilities

- Create payment sessions with configurable amounts and reference metadata for government services
- Capture delayed payments after manual review or service confirmation
- Issue full and partial refunds on completed payments with status tracking
- Retrieve detailed payment event histories for audit and reconciliation
- Search across all payments with filtering by reference, state, or date range
- Cancel pending payments that have not yet been completed by the citizen

## Use cases

### Government Service Payment Collection

Accept payments from citizens for government services such as licence applications, permit fees, or fines. The API creates a payment session and returns a URL to the GOV.UK hosted payment page where the citizen enters their card details. After payment, the API confirms success and provides a reference for the service to proceed with fulfilment. No PCI compliance required from the service team.

Example prompt: Create a payment for 85.00 GBP with reference 'LICENCE-2026-001' and description 'Driving licence renewal' via POST `/v1/payments` and retrieve the payment page URL

### Refund Processing for Government Payments

Issue refunds to citizens when government services need to return funds, such as overpayments, cancelled applications, or duplicate charges. The API supports both full and partial refunds on completed payments. Refund status can be tracked via dedicated endpoints, providing audit trails for financial reconciliation across government departments.

Example prompt: Issue a partial refund of 25.00 GBP on payment {paymentId} via POST `/v1/payments/{paymentId}/refunds` with the refund amount

### Payment Audit and Reconciliation

Retrieve payment events and search across all transactions for financial reporting and audit purposes. Each payment maintains a complete event log from creation through completion or failure. The search endpoint supports filtering by reference, status, creation date, and amount range, enabling automated reconciliation between government accounting systems and GOV.UK Pay records.

Example prompt: Retrieve all payment events for payment {paymentId} via GET `/v1/payments/{paymentId}/events` and verify the payment completed successfully

### AI Agent Government Payment Operations via Jentic

AI agents use Jentic to create payments, issue refunds, and query payment status for UK government services without managing API keys or implementing the GOV.UK Pay request format manually. Jentic stores the API key securely and provides operation schemas so agents can perform payment operations with validated inputs.

Example prompt: Search Jentic for 'create a government payment', load the operation schema, and execute it to create a 50.00 GBP payment for a permit application

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/payments` | Create a new payment session |
| GET | `/v1/payments/{paymentId}` | Retrieve payment details and status |
| POST | `/v1/payments/{paymentId}/cancel` | Cancel a pending payment |
| POST | `/v1/payments/{paymentId}/capture` | Capture a delayed payment |
| GET | `/v1/payments/{paymentId}/events` | Get payment event history |
| POST | `/v1/payments/{paymentId}/refunds` | Issue a refund |
| GET | `/v1/payments/{paymentId}/refunds/{refundId}` | Get refund status |
| GET | `/v1/refunds` | Search across all refunds |

## Key resources

- **Payments** — Create, retrieve, cancel, and capture payment sessions with amount and reference
- **Refunds** — Issue and track refunds on completed payments with amount and status
- **Payment Events** — Retrieve timestamped event logs for payment lifecycle tracking

## Why Jentic

- **Setup:** Wiring GOV.UK Pay by hand means passing its API key in the Authorization header and driving the payment, capture, and refund lifecycle yourself. Through Jentic you install once, import the GOV.UK Pay API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** GOV.UK Pay puts the payment id in the URL path (`/v1/payments/{paymentId}/refunds`), so a rule can pin your agent to one payment: it can read that payment and its events and nothing else. You choose the operations it may call, so cancel, capture, and refund are not included unless you add them.
- **Credential handling:** Your GOV.UK Pay API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a payment for a government service' or 'check a payment status', and Jentic returns the matching GOV.UK Pay operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe API** — Commercial payment platform with broader method coverage and global reach
- **Adyen Checkout API** — Enterprise payment orchestration for high-volume commercial merchants
- **Mollie API** — European payment gateway with iDEAL, SEPA, and local method support

## FAQ

### What authentication does the GOV.UK Pay API use?

The GOV.UK Pay API uses an API key passed in the Authorization header. Each service gets a unique API key from the GOV.UK Pay admin tool. Through Jentic, the API key is stored in your Jentic One instance and injected into requests automatically - agents never handle the raw key.

### Can I issue partial refunds with the GOV.UK Pay API?

Yes. The POST `/v1/payments/{paymentId}/refunds` endpoint accepts an amount field. You can refund any amount up to the original payment total. Multiple partial refunds are allowed on the same payment as long as the cumulative total does not exceed the original charge.

### What are the rate limits for the GOV.UK Pay API?

GOV.UK Pay applies rate limits per API key. Standard service accounts are limited to 15 requests per second across all endpoints. The API returns 429 Too Many Requests when exceeded. For high-volume services, contact the GOV.UK Pay team for increased limits.

### How do I create a payment for a government service through Jentic?

Search Jentic for 'create a government payment' to find the POST `/v1/payments` operation. Jentic returns the input schema showing required fields: amount (in pence), reference, description, and return_url. Execute through Jentic and receive the payment page URL to redirect the citizen. Install with pip install jentic.

### Can I track the full lifecycle of a payment?

Yes. GET `/v1/payments/{paymentId}/events` returns a timestamped list of all state changes including created, started, submitted, confirmed, captured, and any failures. This provides a complete audit trail for each payment without external logging.

### What is delayed capture and when should I use it?

Delayed capture holds the payment authorization without collecting funds immediately. Use POST `/v1/payments` with a capture delay flag, then POST `/v1/payments/{paymentId}/capture` when ready to collect. This suits services that need manual review or confirmation before charging, such as booking-based permits.

### Can I limit what my agent is allowed to do with the GOV.UK Pay API?

Yes. Jentic One is self-hosted by you, so your own rules decide which GOV.UK Pay operations and credentials your agent may use. Because GOV.UK Pay puts the payment id in the URL path, such as `/v1/payments/{paymentId}/refunds`, a rule can pin the agent to a single payment so it can read that payment and its events and nothing more. You choose the operations it may call, so cancel, capture, and refund stay out of reach unless you explicitly add them.