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

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"
  }
}

Changes

Changed in 6 of the 50 revisions of this API.715

Oct 8, 20196d52e43c48aa62See the full diff
- ▲
  removed the request body
  request-body-removed
- ▲
  removed the media type application/json for the response with the status
  response-media-type-removed
- ▲
  removed the media type application/json for the response with the status
  response-media-type-removed
- ▲
  removed the media type application/json for the response with the status
  response-media-type-removed
- ▲
  removed the media type application/json for the response with the status
  response-media-type-removed
- ▲
  removed the media type application/json for the response with the status
  response-media-type-removed
- ○
  the endpoint scheme security Authorization was added to the API
  api-security-added
- ○
  the endpoint scheme security BearerAuth was removed from the API
  api-security-removed
This revision also has 46 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Oct 6, 2019884c555517bc17See the full diff
- ▲
  added required request body
  request-body-added-required
- ○
  the endpoint scheme security BearerAuth was added to the API
  api-security-added
- ○
  the endpoint scheme security Authorization was removed from the API
  api-security-removed
- ○
  added the media type application/json for the response with the status
  response-media-type-added
- ○
  added the media type application/json for the response with the status
  response-media-type-added
- ○
  added the media type application/json for the response with the status
  response-media-type-added
- ○
  added the media type application/json for the response with the status
  response-media-type-added
- ○
  added the media type application/json for the response with the status
  response-media-type-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 1, 20196e01c8022b872See the full diff
- ○
  api tag Card payments added
  api-tag-added
- ○
  api tag Card Payments removed
  api-tag-removed
Jul 31, 2019f8066d82895d1See the full diff
- ○
  api operation id newPayment removed and replaced with Create a payment
  api-operation-id-removed
Jul 31, 2019ef50a2b1c4f11See the full diff
- ○
  api tag Card Payments added
  api-tag-added
Feb 22, 201989daf4ffa64f2See the full diff
- ○
  api operation id Create a payment removed and replaced with newPayment
  api-operation-id-removed
- ○
  api tag Card payments removed
  api-tag-removed

Full history