Create a payment

POST/v1/payments

You can use this endpoint to create a new payment.

In this mock: Use authorisation_mode moto_api to get a payment you can complete through the API (see How the mock behaves). Redirect the user to next_url: the mock hosts the payment pages (see Hosted payment pages), and webhooks report the outcome (see Webhooks). Amounts from 0 to 10,000,000. Reusing an Idempotency-Key returns 409 P0191.

Headers

Name	Type	Description
`Idempotency-Key`	string

Request body

Name	Type	Description
`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`	string	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. One of: instalment, recurring, unscheduled
`amount` required	integer	Sets the amount the user will pay, in pence.
`authorisation_mode`	string	Sets how you intend to authorise the payment. 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. 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. One of: web, agreement, moto_api
`delayed_capture`	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. Defaults to `false`.
`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
`email`	string	email
`language`	string	Sets the language of the user’s payment page with an ISO-6391 Alpha-2 code of a supported language. One of: en, cy
`metadata`	object
`metadata.metadata`	map
`moto`	boolean	You can use this parameter to designate a payment as a Mail Order / Telephone Order (MOTO) payment.
`prefilled_cardholder_details`	object	prefilled_cardholder_details
`prefilled_cardholder_details.billing_address`	object	A structure representing the billing address of a card
`prefilled_cardholder_details.billing_address.city`	string	The paying user's city.
`prefilled_cardholder_details.billing_address.country`	string	The paying user’s country, displayed as a 2-character ISO-3166-1-alpha-2 code.
`prefilled_cardholder_details.billing_address.line1`	string	The first line of the paying user’s address.
`prefilled_cardholder_details.billing_address.line2`	string	The second line of the paying user’s address.
`prefilled_cardholder_details.billing_address.postcode`	string	The paying user's postcode.
`prefilled_cardholder_details.cardholder_name`	string	The cardholder name you prefilled when you created this payment.
`reference` required	string	Associate a reference with this payment. `reference` is not unique - multiple payments can have identical `reference` values.
`return_url` required	string	The URL the paying user is directed to after their payment journey on GOV.UK Pay ends.
`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`.

Example request

curl -X POST "https://publicapi.payments.platform-engineering.com/v1/payments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 12000,
  "description": "New passport application",
  "reference": "12345",
  "return_url": "https://service-name.gov.uk/transactions/12345"
}'

Responses

201: Created

Name	Type	Description
`_links`	object	links for payment
`_links.auth_url_post`	object	A POST link related to a payment
`_links.auth_url_post.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.auth_url_post.method`	string
`_links.auth_url_post.params`	map
`_links.auth_url_post.type`	string
`_links.cancel`	object	A POST link related to a payment
`_links.cancel.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.cancel.method`	string
`_links.cancel.params`	map
`_links.cancel.type`	string
`_links.capture`	object	A POST link related to a payment
`_links.capture.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.capture.method`	string
`_links.capture.params`	map
`_links.capture.type`	string
`_links.events`	object	A link related to a payment
`_links.events.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.events.method`	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
`_links.next_url`	object	A link related to a payment
`_links.next_url.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.next_url.method`	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
`_links.next_url_post`	object	A POST link related to a payment
`_links.next_url_post.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.next_url_post.method`	string
`_links.next_url_post.params`	map
`_links.next_url_post.type`	string
`_links.refunds`	object	A link related to a payment
`_links.refunds.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.refunds.method`	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
`_links.self`	object	A link related to a payment
`_links.self.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.self.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`	object
`card_details.billing_address`	object	A structure representing the billing address of a card
`card_details.billing_address.city`	string	The paying user's city.
`card_details.billing_address.country`	string	The paying user’s country, displayed as a 2-character ISO-3166-1-alpha-2 code.
`card_details.billing_address.line1`	string	The first line of the paying user’s address.
`card_details.billing_address.line2`	string	The second line of the paying user’s address.
`card_details.billing_address.postcode`	string	The paying user's postcode.
`card_details.card_brand`	string
`card_details.card_type`	string
`card_details.cardholder_name`	string
`card_details.expiry_date`	string
`card_details.first_digits_card_number`	string
`card_details.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.
`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`	string	The language of the user’s payment page. One of: en, cy
`metadata`	object
`metadata.metadata`	map
`moto`	boolean	Indicates if this payment is a Mail Order / Telephone Order (MOTO) payment.
`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`	object	A structure representing the refunds availability
`refund_summary.amount_available`	integer	How much you can refund to the user, in pence.
`refund_summary.amount_submitted`	integer	How much you’ve already refunded to the user, in pence.
`refund_summary.status`	string	Whether you can refund the payment.
`return_url`	string	The URL you direct the paying user to after their payment journey on GOV.UK Pay ends.
`settlement_summary`	object	A structure representing information about a settlement
`settlement_summary.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`
`settlement_summary.captured_date`	string	The date your payment service provider took the payment from your user. This value uses ISO 8601 format - `YYYY-MM-DD`
`settlement_summary.settled_date`	string	The date that the transaction was paid into the service's account.
`state`	object	A structure representing the current state of the payment in its lifecycle.
`state.can_retry`	boolean	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.
`state.code`	string	An API error codethat explains why the payment failed. `code` only appears if the payment failed.
`state.finished`	boolean	Indicates whether a payment journey is finished.
`state.message`	string	A description of what went wrong with this payment. `message` only appears if the payment failed.
`state.status`	string	Where the payment is in the payment status lifecycle.

{
  "_links": {
    "auth_url_post": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST",
      "params": {
        "description": "This is a value for a parameter called description"
      },
      "type": "application/x-www-form-urlencoded"
    },
    "cancel": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST",
      "params": {
        "description": "This is a value for a parameter called description"
      },
      "type": "application/x-www-form-urlencoded"
    },
    "capture": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST",
      "params": {
        "description": "This is a value for a parameter called description"
      },
      "type": "application/x-www-form-urlencoded"
    },
    "events": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "next_url": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "next_url_post": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST",
      "params": {
        "description": "This is a value for a parameter called description"
      },
      "type": "application/x-www-form-urlencoded"
    },
    "refunds": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "amount": 1200,
  "card_details": {
    "billing_address": {
      "city": "address city",
      "country": "GB",
      "line1": "address line 1",
      "line2": "address line 2",
      "postcode": "AB1 2CD"
    }
  },
  "created_date": "2016-01-21T17:15:00.000Z",
  "delayed_capture": false,
  "description": "New passport application",
  "email": "citizen@example.org",
  "language": "en",
  "metadata": {
    "ledger_code": "AB100"
  },
  "moto": false,
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "payment_provider": "worldpay",
  "provider_id": "null",
  "reference": "12345",
  "refund_summary": {
    "amount_available": 100,
    "status": "available"
  },
  "return_url": "https://service-name.gov.uk/transactions/12345",
  "settlement_summary": {
    "capture_submit_time": "2016-01-21T17:15:00.000Z",
    "captured_date": "2016-01-21",
    "settled_date": "2016-01-21"
  },
  "state": {
    "code": "P010",
    "message": "User cancelled the payment",
    "status": "created"
  }
}

400: Bad request

Name	Type	Description
`code`	string	An API error codethat explains why the payment failed.<br><br>`code` only appears if the payment failed.
`description`	string	Additional details about the error.
`field`	string	The parameter in your request that's causing the error.
`header`	string	The header in your request that's causing the error.

{
  "code": "P0102",
  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000",
  "field": "amount",
  "header": "Idempotency-Key"
}

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.

Name	Type	Description
`code`	string	An API error codethat explains why the payment failed.<br><br>`code` only appears if the payment failed.
`description`	string	Additional details about the error.
`field`	string	The parameter in your request that's causing the error.
`header`	string	The header in your request that's causing the error.

{
  "code": "P0102",
  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000",
  "field": "amount",
  "header": "Idempotency-Key"
}

429: Too many requests

Name	Type	Description
`code`	string	A GOV.UK Pay API error code. You can find out more about this code in our documentation.
`description`	string	Additional details about the error

{
  "code": "P0900",
  "description": "Too many requests"
}

500: Downstream system error

Name	Type	Description
`code`	string	An API error codethat explains why the payment failed.<br><br>`code` only appears if the payment failed.
`description`	string	Additional details about the error.
`field`	string	The parameter in your request that's causing the error.
`header`	string	The header in your request that's causing the error.

{
  "code": "P0102",
  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000",
  "field": "amount",
  "header": "Idempotency-Key"
}