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

# Create new payment

`POST /v1/payments`

Create a new payment for the account associated to the Authorisation token. The Authorisation token needs to be specified in the 'authorization' header as 'authorization: Bearer YOUR_API_KEY_HERE'

## Request body

- CreateCardPaymentRequest — The Payment Request Payload
  - `amount` integer, required — amount in pence
  - `reference` string, required — payment reference
  - `description` string, required — payment description
  - `language` 'en' | 'cy' — ISO-639-1 Alpha-2 code of a supported language to use on the payment pages
  - `email` string — email
  - `return_url` string, required — service return url
  - `delayed_capture` boolean — delayed capture flag
  - `moto` boolean — Mail Order / Telephone Order (MOTO) payment flag
  - `metadata` object — Additional metadata - up to 10 name/value pairs - on the payment. Each key must be between 1 and 30 characters long. The value, if a string, must be no greater than 50 characters long. Other permissible value types: boolean, number.
  - `prefilled_cardholder_details` PrefilledCardholderDetails
    - `cardholder_name` string — prefilled cardholder name
    - `billing_address` Address — A structure representing the billing address of a card
      - `line1` string
      - `line2` string
      - `postcode` string
      - `city` string
      - `country` string

## Response `201`

Created

- CreatePaymentResult
  - `amount` integer — The amount in pence.
  - `state` PaymentState — A structure representing the current state of the payment in its lifecycle.
    - `status` string — Current progress of the payment in its lifecycle
    - `finished` boolean — Whether the payment has finished
    - `message` string — What went wrong with the Payment if it finished with an error - English message
    - `code` string — What went wrong with the Payment if it finished with an error - error code
  - `description` string — The human-readable description you gave the payment.
  - `reference` string — The reference number you associated with this payment.
  - `language` 'en' | 'cy' — Which language your users will see on the payment pages when they make a payment.
  - `payment_id` string — The unique identifier of the payment.
  - `payment_provider` string
  - `return_url` string — An HTTPS URL on your site that your user will be sent back to once they have completed their payment attempt on GOV.UK Pay.
  - `created_date` string — The date you created the payment.
  - `delayed_capture` boolean — Whether to [delay capturing](https://docs.payments.service.gov.uk/optional_features/delayed_capture/) this payment.
  - `moto` boolean — Mail Order / Telephone Order (MOTO) payment flag.
  - `_links` PaymentLinks — links for payment
    - `self` Link — A link related to a payment
      - `href` string
      - `method` string
    - `next_url` Link — A link related to a payment
      - `href` string
      - `method` string
    - `next_url_post` PostLink — A POST link related to a payment
      - `type` string
      - `params` object
      - `href` string
      - `method` string
    - `events` Link — A link related to a payment
      - `href` string
      - `method` string
    - `refunds` Link — A link related to a payment
      - `href` string
      - `method` string
    - `cancel` PostLink — A POST link related to a payment
      - `type` string
      - `params` object
      - `href` string
      - `method` string
    - `capture` PostLink — A POST link related to a payment
      - `type` string
      - `params` object
      - `href` string
      - `method` string
  - `provider_id` string — The reference number the payment gateway associated with the payment.
  - `metadata` object — [Custom metadata](https://docs.payments.service.gov.uk/optional_features/custom_metadata/) you added to the payment.
  - `email` string — The email address of your user.
  - `refund_summary` RefundSummary — A structure representing the refunds availability
    - `status` string — Availability status of the refund
    - `amount_available` integer — Amount available for refund in pence
    - `amount_submitted` integer — Amount submitted for refunds on this Payment in pence
  - `settlement_summary` PaymentSettlementSummary — A structure representing information about a settlement
    - `capture_submit_time` string — Date and time capture request has been submitted. May be null if capture request was not immediately acknowledged by payment gateway.
    - `captured_date` string — Date of the capture event.
    - `settled_date` string — The date that the transaction was paid into the service's account.
  - `card_details` CardDetails — A structure representing the payment card
    - `last_digits_card_number` string
    - `first_digits_card_number` string
    - `cardholder_name` string
    - `expiry_date` string — The expiry date of the card in MM/yy format
    - `billing_address` Address — A structure representing the billing address of a card
      - `line1` string
      - `line2` string
      - `postcode` string
      - `city` string
      - `country` string
    - `card_brand` string
    - `card_type` 'debit' | 'credit' | 'null' — The card type, `debit` or `credit` or `null` if not able to determine

## Other responses

- `400` — Bad request
- `401` — Credentials are required to access this resource
- `422` — Invalid attribute value: description. Must be less than or equal to 255 characters length
- `429` — Too many requests
- `500` — Downstream system error

## Changes

- **2019-10-08** `6d52e43c48aa` — 6 breaking, 2 info
  - removed the request body
  - removed the media type `application/json` for the response with the status `201`
  - removed the media type `application/json` for the response with the status `400`
  - removed the media type `application/json` for the response with the status `422`
  - …4 more
- **2019-10-06** `884c555517bc` — 1 breaking, 7 info
  - added required request body
  - the endpoint scheme security `BearerAuth` was added to the API
  - the endpoint scheme security `Authorization` was removed from the API
  - added the media type `application/json` for the response with the status `201`
  - …4 more
- **2019-08-01** `6e01c8022b87` — 2 info
  - api tag `Card payments` added
  - api tag `Card Payments` removed
- **2019-07-31** `f8066d82895d` — 1 info
  - api operation id `newPayment` removed and replaced with `Create a payment`
- **2019-07-31** `ef50a2b1c4f1` — 1 info
  - api tag `Card Payments` added

[Full history](https://skmtc.dev/alphagov/apis/gov-uk-pay-api/changes/v1/payments/post.md)

---

[API](https://skmtc.dev/alphagov/apis/gov-uk-pay-api.md) · [All operations](https://skmtc.dev/alphagov/apis/gov-uk-pay-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/alphagov/gov-uk-pay-api/revisions/262275a01170/schema)