---
title: "Create a payment"
method: POST
path: "/v1/payments"
tags: ["Card payments"]
---

# Create a payment

`POST /v1/payments`

You can use this endpoint to [create a new payment](https://docs.payments.service.gov.uk/making_payments/).

## Headers

- `Idempotency-Key` string

## Request body

- CreateCardPaymentRequest — The create payment request body
  - `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`.
  - `agreement_payment_type` 'instalment' | 'recurring' | 'unscheduled' — When a standing order agreement transaction is initiated we have to include an initiated reason attribute.This can have a value of `instalment`, `recurring`, or `unscheduled`.We must have a `set_up_agreement` property or you set `authorisation_mode` to `agreement` for the API to accept the AgreementPaymentType.
  - `amount` integer, required — Sets the amount the user will pay, in pence.
  - `authorisation_mode` 'web' | 'agreement' | 'moto_api' — Sets how you intend to authorise the payment. Defaults to `web`. Payments created with `web` mode follow the [standard GOV.UK Pay payment journey](https://docs.payments.service.gov.uk/payment_flow/). 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. 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.
  - `delayed_capture` boolean — You can use this parameter to [delay taking a payment from the paying user’s bank account](https://docs.payments.service.gov.uk/delayed_capture/#delay-taking-a-payment). For example, you might want to do your own anti-fraud checks on payments, or check that users are eligible for your service. Defaults to `false`.
  - `description` string, required — 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
  - `email` string — email
  - `language` 'en' | 'cy' — [Sets the language of the user’s payment page](https://docs.payments.service.gov.uk/optional_features/welsh_language) with an ISO-6391 Alpha-2 code of a supported language.
  - `metadata` ExternalMetadata
    - `metadata` object
  - `moto` boolean — You can use this parameter to [designate a payment as a Mail Order / Telephone Order (MOTO) payment](https://docs.payments.service.gov.uk/moto_payments).
  - `prefilled_cardholder_details` PrefilledCardholderDetails — prefilled_cardholder_details
    - `billing_address` Address — A structure representing the billing address of a card
      - `city` string — The paying user's city.
      - `country` string — The paying user’s country, displayed as a 2-character ISO-3166-1-alpha-2 code.
      - `line1` string — The first line of the paying user’s address.
      - `line2` string — The second line of the paying user’s address.
      - `postcode` string — The paying user's postcode.
    - `cardholder_name` string — The cardholder name you prefilled when you created this payment.
  - `reference` string, required — Associate a reference with this payment. `reference` is not unique - multiple payments can have identical `reference` values.
  - `return_url` string, required — The URL [the paying user is directed to after their payment journey on GOV.UK Pay ends](https://docs.payments.service.gov.uk/making_payments/#choose-the-return-url-and-match-your-users-to-payments).
  - `set_up_agreement` 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`.

## Response `201`

Created

- CreatePaymentResult
  - `_links` PaymentLinks — links for payment
    - `auth_url_post` PostLink — A POST link related to a payment
      - `href` string — A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string
      - `params` object
      - `type` string
    - `cancel` PostLink — A POST link related to a payment
      - `href` string — A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string
      - `params` object
      - `type` string
    - `capture` PostLink — A POST link related to a payment
      - `href` string — A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string
      - `params` object
      - `type` string
    - `events` Link — A link related to a payment
      - `href` string — A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string — An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
    - `next_url` Link — A link related to a payment
      - `href` string — A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string — An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
    - `next_url_post` PostLink — A POST link related to a payment
      - `href` string — A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string
      - `params` object
      - `type` string
    - `refunds` Link — A link related to a payment
      - `href` string — A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string — An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
    - `self` Link — A link related to a payment
      - `href` string — A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string — An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
  - `amount` integer — The amount, in pence, the user has paid or will pay. `amount` will match the value you sent in the request body.
  - `card_details` CardDetailsFromResponse
    - `billing_address` Address — A structure representing the billing address of a card
      - `city` string — The paying user's city.
      - `country` string — The paying user’s country, displayed as a 2-character ISO-3166-1-alpha-2 code.
      - `line1` string — The first line of the paying user’s address.
      - `line2` string — The second line of the paying user’s address.
      - `postcode` string — The paying user's postcode.
    - `card_brand` string
    - `card_type` string
    - `cardholder_name` string
    - `expiry_date` string
    - `first_digits_card_number` string
    - `last_digits_card_number` string
  - `created_date` string — The date you created the 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](https://docs.payments.service.gov.uk/delayed_capture).
  - `description` string — The description you sent in the request body when creating this payment.
  - `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.
  - `language` 'en' | 'cy' — The language of the user’s payment page.
  - `metadata` ExternalMetadata
    - `metadata` object
  - `moto` boolean — Indicates if this payment is a [Mail Order / Telephone Order (MOTO) payment](https://docs.payments.service.gov.uk/moto_payments).
  - `payment_id` string — The unique ID GOV.UK Pay automatically associated with this payment when you created it.
  - `payment_provider` string
  - `provider_id` string — The reference number your payment service provider associated with the payment.
  - `reference` string — The reference number you associated with this payment.
  - `refund_summary` RefundSummary — A structure representing the refunds availability
    - `amount_available` integer — How much you can refund to the user, in pence.
    - `amount_submitted` integer — How much you’ve already refunded to the user, in pence.
    - `status` string — Whether you can [refund the payment](https://docs.payments.service.gov.uk/refunding_payments/#checking-the-status-of-a-refund-status).
  - `return_url` string — The URL you direct the paying user to after their payment journey on GOV.UK Pay ends.
  - `settlement_summary` PaymentSettlementSummary — A structure representing information about a settlement
    - `capture_submit_time` string — The date and time GOV.UK Pay asked your payment service provider to take the payment from your user’s account. This value uses Coordinated Universal Time (UTC) and ISO 8601 format - `YYYY-MM-DDThh:mm:ss.SSSZ`
    - `captured_date` string — The date your payment service provider took the payment from your user. This value uses ISO 8601 format - `YYYY-MM-DD`
    - `settled_date` string — The date that the transaction was paid into the service's account.
  - `state` PaymentState — A structure representing the current state of the payment in its lifecycle.
    - `can_retry` boolean, nullable — If `can_retry` is `true`, you can use this agreement to try to take another recurring payment. If `can_retry` is `false`, you cannot take another recurring payment with this agreement. `can_retry` only appears on failed payments that were attempted using an agreement for recurring payments.
    - `code` string — An [API error code](https://docs.payments.service.gov.uk/api_reference/#gov-uk-pay-api-error-codes)that explains why the payment failed. `code` only appears if the payment failed.
    - `finished` boolean — Indicates whether a payment journey is finished.
    - `message` string — A description of what went wrong with this payment. `message` only appears if the payment failed.
    - `status` string — Where the payment is in [the payment status lifecycle](https://docs.payments.service.gov.uk/api_reference/#payment-status-meanings).

## Other responses

- `400` — Bad request
- `401` — Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)
- `422` — Your request failed. Check the `code` and `description` in the response to find out why your request failed.
- `429` — Too many requests
- `500` — Downstream system error

---

[API](https://skmtc.net/government-digital-service/apis/gov-uk-pay-api.md) · [All operations](https://skmtc.net/government-digital-service/apis/gov-uk-pay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/government-digital-service/gov-uk-pay-api/revisions/4dc2d80f453a/schema)