Sign in

v39

latestOpenAPI 3.0.1raw.githubusercontent.com2025-10-031646108.8 KB
Card payments

Create a payment

You can use this endpoint to create a new payment.

post/v1/payments

Headers

Idempotency-Keystring

Request body

agreement_idstring

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.

amountinteger 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. 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_captureboolean

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.

descriptionstring 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

emailstring

email

language'en' | 'cy'

Sets the language of the user’s payment page with an ISO-6391 Alpha-2 code of a supported language.

motoboolean

You can use this parameter to designate a payment as a Mail Order / Telephone Order (MOTO) payment.

referencestring required

Associate a reference with this payment. reference is not unique - multiple payments can have identical reference values.

return_urlstring required

The URL the paying user is directed to after their payment journey on GOV.UK Pay ends.

set_up_agreementstring

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

{
  "agreement_id": "abcefghjklmnopqr1234567890",
  "amount": 12000,
  "description": "New passport application",
  "email": "Joe.Bogs@example.org",
  "language": "en",
  "prefilled_cardholder_details": {
    "billing_address": {
      "city": "address city",
      "country": "GB",
      "line1": "address line 1",
      "line2": "address line 2",
      "postcode": "AB1 2CD"
    },
    "cardholder_name": "J. Bogs"
  },
  "reference": "12345",
  "return_url": "https://service-name.gov.uk/transactions/12345",
  "set_up_agreement": "abcefghjklmnopqr1234567890"
}

Response

Created

amountinteger

The amount, in pence, the user has paid or will pay. amount will match the value you sent in the request body.

created_datestring

The date you created the payment.

delayed_captureboolean

delayed_capture is true if you’re controlling when GOV.UK Pay takes (‘captures’) the payment from the paying user’s bank account.

descriptionstring

The description you sent in the request body when creating this payment.

emailstring

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.

motoboolean

Indicates if this payment is a Mail Order / Telephone Order (MOTO) payment.

payment_idstring

The unique ID GOV.UK Pay automatically associated with this payment when you created it.

payment_providerstring
provider_idstring

The reference number your payment service provider associated with the payment.

referencestring

The reference number you associated with this payment.

return_urlstring

The URL you direct the paying user to after their payment journey on GOV.UK Pay ends.

Example response

{
  "_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",
  "description": "New passport application",
  "email": "citizen@example.org",
  "language": "en",
  "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"
  }
}