Skip to main content

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