Create a payment API reference

This page is part of GOV.UK Pay’s API reference and is an index of the following you’ll use when creating payments:

parameters
example requests
example responses
attributes you’ll get in your response

You can also read more about the end-to-end process of taking payments using GOV.UK Pay in our task-based guidance.

The URL for this endpoint is:

POST https://publicapi.payments.service.gov.uk/v1/payments

You can use this endpoint to create a new payment.

The data from this endpoint is ‘strongly consistent’, meaning it is updated immediately after you make any changes. You can read more about data consistency in our API.

JSON body parameters for ‘Create a payment’

Name	Type	Description
`amount` (required)	number	Sets the amount the user will pay, in pence. Maximum value is `10000000` (£100,000) if your PSP is Stripe. Contact us to take payments above this amount. Maximum value is `500000` (£5,000) if your PSP is Worldpay. Contact Government Banking to take payments above this amount.
`reference` (required)	string	Associate a reference with this payment. `reference` is not unique - multiple payments can have identical `reference` values. Limited to 255 characters and must not contain URLs.
`return_url` (required)	string	The URL the paying user is directed to after their payment journey on GOV.UK Pay ends. Limited to 2,000 characters and must not be JSON-encoded. You can read more about choosing your return URL and matching paying users to payments.
`description` (required)	string	A human-readable description of the payment you’re creating. Paying users see this description on the payment pages. Service staff see the description in the GOV.UK Pay admin tool. Limited to 255 characters and should not contain URLs.
`set_up_agreement` (optional)	string	Use this parameter to set up an existing agreement for recurring payments. The `set_up_agreement` value you send must be a valid `agreement_id`. Read more about taking recurring payments.
`delayed_capture` (optional)	boolean	You can use this parameter to delay taking a payment from the paying user’s bank account. For example, you might want to do your own anti-fraud checks on payments, or check that users are eligible for your service. You can read more about delaying taking a payment from the paying user’s bank account. Defaults to `false`.
`email` (optional)	string	Prefills the paying user’s email address field when they make their payment. Limited to 254 characters. You can read more about prefilling fields on the Enter payment details page.
`prefilled_cardholder_details` (optional)	object	An object that prefills the paying user’s address and cardholder name fields when they make their payment. `prefilled_cardholder_details` can contain 2 optional parameters: `cardholder_name` `billing_address` You can read more about using this object to prefill payment fields.
`prefilled_cardholder_details.cardholder_name` (optional)	string	Prefills the paying user’s cardholder name field when they make their payment. Limited to 255 characters.
`prefilled_cardholder_details.billing_address` (optional)	object	An object that prefills the paying user’s billing address. `billing_address` can contain: `line1` (the first line of the paying user’s address) `line2` (the second line of the paying user’s address) `postcode` (the paying user’s postcode) `city` (the paying user’s city) `country` (the paying user’s country, displayed as a 2-character ISO-3166-1-alpha-2 code) Every parameter is optional. If the `country` value is invalid or missing, the Country/territory field on the user’s payment page defaults to United Kingdom. You can read more about how to prefill cardholder details.
`language` (optional)	string	Sets the language of the user’s payment page. Available values are: `en` (English) `cy` (Welsh) `language` defaults to `en` if you do not include it in your request body. You can read more about using Welsh on your payment pages.
`metadata` (optional)	object	An object that adds custom metadata to a payment using parameter key-value pairs. The `metadata` object must contain between 1 and 15 parameter keys. Parameter keys are limited to 30 characters. Parameter values are limited to 100 characters. Parameter values can be empty. You cannot add or change metadata keys or values after you’ve created the payment. You can read more about adding custom metadata to payments.
`moto` (optional)	boolean	You can use this parameter to designate a payment as a Mail Order / Telephone Order (MOTO) payment. `moto` defaults to `false` if you do not include it in your request. You must have MOTO payments turned on in your GOV.UK Pay account to use the `moto` parameter. You can read more about enabling taking payments over the phone.
`authorisation_mode`	string	Sets how you intend to authorise the payment. Available values are: `web` `moto_api` `agreement` Defaults to `web`. Payments created with `web` mode follow the standard GOV.UK Pay payment journey. Paying users visit the `next_url` in the response to complete their payment. Payments created with `agreement` mode are authorised with an agreement for recurring payments. If you create an `agreement` payment, you must also send an active `agreement_id`. You must not send `return_url`, `email`, or `prefilled_cardholder_details` or your request will fail. You can read more about recurring payments. Payments created with `moto_api` mode return an `auth_url_post` object and a `one_time_token`. You can use `auth_url_post` and `one_time_token` to send the paying user’s card details through the API and complete the payment. If you create a `moto_api` payment, do not send a `return_url` in your request. You can read more about authorising payments through the API.
`agreement_id`	string	The unique ID GOV.UK Pay automatically associated with a recurring payments agreement. Including `agreement_id` in your request tells the API to take this payment using the card details that are associated with this agreement. `agreement_id` must match an active agreement ID. You must set `authorisation_mode` to `agreement` for the API to accept `agreement_id`. You can read more about recurring payments.

Example request for ‘Create a payment’

This example request creates a £145 council tax payment with a reference of 12345. It also prefills some payment fields and uses metadata to add an internal ledger code and reference number:

curl "https://publicapi.payments.service.gov.uk/v1/payments" \
-H 'Authorization: Bearer api_test_123abc456def' \
-H 'Content-Type: application/json' \
-d '{
          "amount": 14500,
          "reference" : "12345",
          "description": "Pay your council tax",
          "return_url": "https://your.service.gov.uk/completed",
          "delayed_capture": false,
          "metadata": {
                "ledger_code": "AB100",
                "internal_reference_number": 200
          },
          "email": "sherlock.holmes@example.com",
          "prefilled_cardholder_details": {
            "cardholder_name": "Sherlock Holmes",
            "billing_address": {
                "line1": "221 Baker Street",
                "line2": "Flat b",
                "postcode": "NW1 6XE",
                "city": "London",
                "country": "GB"
            }
          },
          "language": "en"
}'

Example response for ‘Create a payment’

{
    "amount": 14500,
    "description": "Pay your council tax.",
    "reference": "12345",
    "language": "en",
    "state": {
        "status": "created",
        "finished": false
    },
    "payment_id": "hu20sqlact5260q2nanm0q8u93",
    "payment_provider": "stripe",
    "created_date": "2022-03-25T13:11:29.019Z",
    "refund_summary": {
        "status": "pending",
        "amount_available": 14500,
        "amount_submitted": 0
    },
    "settlement_summary": {},
    "delayed_capture": false,
    "moto": false,
    "return_url": "https://your.service.gov.uk/completed",
    "_links": {
        "self": {
            "href": "https://publicapi.payments.service.gov.uk/v1/payments/hu20sqlact5260q2nanm0q8u93",
            "method": "GET"
        },
        "next_url": {
            "href": "https://www.payments.service.gov.uk/secure/ef1b6ff1-db34-4c62-b854-3ed4ba3c4049",
            "method": "GET"
        },
        "next_url_post": {
            "type": "application/x-www-form-urlencoded",
            "params": {
                "chargeTokenId": "ef1b6ff1-db34-4c62-b854-3ed4ba3c4049"
            },
            "href": "https://www.payments.service.gov.uk/secure",
            "method": "POST"
        },
        "events": {
            "href": "https://publicapi.payments.service.gov.uk/v1/payments/hu20sqlact5260q2nanm0q8u93/events",
            "method": "GET"
        },
        "refunds": {
            "href": "https://publicapi.payments.service.gov.uk/v1/payments/hu20sqlact5260q2nanm0q8u93/refunds",
            "method": "GET"
        },
        "cancel": {
            "href": "https://publicapi.payments.service.gov.uk/v1/payments/hu20sqlact5260q2nanm0q8u93/cancel",
            "method": "POST"
        }
    }
}

Attributes you’ll get in a ‘Create a payment’ response

Name	Type	Description
`amount`	number	The amount, in pence, the user has paid or will pay. `amount` will match the value you sent in the request body.
`description`	string	The description you sent in the request body when creating this payment.
`reference`	string	The reference you sent when creating this payment. `reference` is not unique - multiple payments can have the same `reference` value.
`language`	string	The language of the user’s payment page. Possible values are: `en` (English) `cy` (Welsh)
`metadata`	object	Contains any custom metadata you sent when creating this payment. The `metadata` object does not appear if you did not send any custom metadata in the request body. You can read more about adding custom metadata to payments.
`email`	string	The paying user’s email address. The paying user’s email field will be prefilled with this value when they make their payment. `email` does not appear if you did not include it in the request body.
`state`	object	Contains information about where the payment is in its journey. You can read more about the payment status lifecycle.
`state.status`	string	The status of this payment. `status` value will automatically be set to `created` because you’ve just created this payment. You can read more about the meanings of each payment status.
`state.finished`	boolean	Indicates whether a payment journey is finished. `finished` will automatically be set to `false` because you’ve just created this payment. A `finished` payment journey does not always mean the user has made a payment. For example, a user may submit payment details but their bank rejects the payment - the payment journey would be `finished` but the payment has not been made.
`payment_id`	string	The unique ID GOV.UK Pay automatically associated with this payment when you created it.
`payment_provider`	string	The payment service provider that will process this payment.
`created_date`	date (ISO 8601)	The date and time you created this payment. This value uses Coordinated Universal Time (UTC) and ISO 8601 format - `YYYY-MM-DDThh:mm:ss.sssZ`.
`agreement_id`	string	The unique ID of the agreement for recurring payments that GOV.UK Pay will use to take this payment. `agreement_id` will match the ID you sent in your request. `agreement_id` only appears if you set `authorisation_mode` to `agreement`.
`refund_summary`	object	Contains information about refunds on this payment, such as refund availability. You can read more about refunding payments.
`refund_summary.status`	string	Whether you can refund the payment. `status` value will be `pending` because your user has not yet made this payment. You can read about the meanings of each refund `status` value.
`refund_summary.amount_available`	number	How much you can refund to the user, in pence, once they have completed the payment.
`refund_summary.amount_submitted`	number	How much you’ve already refunded to the user in pence.
`settlement_summary`	object	Contains information about when this payment was settled. Payments are settled when your payment service provider sends funds to your bank account. You can read further guidance on when your payment service provider sends funds to your bank account. `settlement_summary` will be empty because you’ve just created this payment.
`delayed_capture`	boolean	`delayed_capture` is `true` if you’re controlling when GOV.UK Pay takes (‘captures’) the payment from the paying user’s bank account. You can read more about delaying taking a payment.
`moto`	boolean	Indicates if this payment is a Mail Order / Telephone Order (MOTO) payment. You can read more about taking payments over the phone.
`return_url`	string	The URL you direct the paying user to after their payment journey on GOV.UK Pay ends. `return_url` only appears if `authorisation_mode` is `web`. You can read more about choosing your return URL and matching the paying user to a payment.
`authorisation_mode`	string	How GOV.UK Pay will authorise this payment. Possible values are: `web` `moto_api` `agreement` `authorisation_mode` will match the value you sent in your request. Defaults to `web`.
`_links`	object	Contains URLs and methods for actions related to this payment.
`_links.self`	object	Contains an API method and URL to get information about this payment. A `GET` request (`method`) to this URL (`href`) returns information about this payment. You can read more about getting information for a single payment.
`_links.next_url`	object	Contains the URL the paying user will visit to complete this payment. `next_url` only appears if `authorisation_mode` is `web`.
`_links.events`	object	Contains an API method and endpoint to get this payment’s events. A `GET` request (`method`) to this endpoint (`href`) returns information about this payment’s events.
`_links.refunds`	object	Contains an API method and endpoint to get refund information about this payment. A `GET` request (`method`) to this endpoint (`href`) returns refund information for this payment.
`_links.cancel`	object	Contains an API method and endpoint to cancel this payment. A `POST` request (`method`) to this endpoint (`href`) cancels this payment. `cancel` value is `null` if the payment cannot be cancelled.
`_links.auth_url_post`	object	Contains an API method, URL, and a one time token to submit this payment for authorisation through the API. A `POST` request (`method`) to this URL (`href`) that contains the one time token (`one_time_token`) and paying user’s card details in the request body submits the payment for authorisation. `auth_url_post` only appears if you set `authorisation_mode` to `moto_api` when you created this payment. You can read more about taking and authorising MOTO payments through the API.
`_links.auth_url_post. params`	object	Contains the request parameters you’ll need to authorise this payment through the GOV.UK Pay API.
`_links.auth_url_post.params.one_time_token`	object	A single use token that identifies this payment when you send the user’s card details through the API for authorisation. You can read more about taking and authorising payments through the API.