Sign in

v1

latestSwagger 2.02026-07-13103251.8 KB
Card payments

Create new payment

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'

post/v1/payments

Request body

amountinteger required

amount in pence

referencestring required

payment reference

descriptionstring required

payment description

language'en' | 'cy'

ISO-639-1 Alpha-2 code of a supported language to use on the payment pages

emailstring

email

return_urlstring required

service return url

delayed_captureboolean

delayed capture flag

motoboolean

Mail Order / Telephone Order (MOTO) payment flag

metadataobject

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.

Example request

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

Response

Created

amountinteger

The amount in pence.

descriptionstring

The human-readable description you gave the payment.

referencestring

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_idstring

The unique identifier of the payment.

payment_providerstring
return_urlstring

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_datestring

The date you created the payment.

delayed_captureboolean

Whether to delay capturing this payment.

motoboolean

Mail Order / Telephone Order (MOTO) payment flag.

provider_idstring

The reference number the payment gateway associated with the payment.

metadataobject

Custom metadata you added to the payment.

emailstring

The email address of your user.

Example response

{
  "amount": 1200,
  "state": {
    "status": "created",
    "message": "User cancelled the payment",
    "code": "P010"
  },
  "description": "New passport application",
  "reference": "12345",
  "language": "en",
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "payment_provider": "worldpay",
  "return_url": "https://service-name.gov.uk/transactions/12345",
  "created_date": "2016-01-21T17:15:00Z",
  "_links": {
    "self": {
      "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": {
      "type": "application/x-www-form-urlencoded",
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST"
    },
    "events": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "refunds": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "cancel": {
      "type": "application/x-www-form-urlencoded",
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST"
    },
    "capture": {
      "type": "application/x-www-form-urlencoded",
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST"
    }
  },
  "provider_id": "null",
  "email": "citizen@example.org",
  "refund_summary": {
    "status": "available",
    "amount_available": 100
  },
  "settlement_summary": {
    "capture_submit_time": "2016-01-21T17:15:000Z",
    "captured_date": "2016-01-21",
    "settled_date": "2016-01-21"
  },
  "card_details": {
    "last_digits_card_number": "1234",
    "first_digits_card_number": "123456",
    "cardholder_name": "Mr. Card holder",
    "expiry_date": "04/24",
    "billing_address": {
      "line1": "address line 1",
      "line2": "address line 2",
      "postcode": "AB1 2CD",
      "city": "address city",
      "country": "GB"
    },
    "card_brand": "Visa",
    "card_type": "debit"
  }
}