GOV.UK Pay API

General

General Overview

{
  "amount": 12000,
Integer (Int32) *

amount in pence

  "reference": "12345",
String *

payment reference

  "description": "New passport application",
String *

payment description

  "return_url": "https://service-name.gov.uk/transactions/12345"
String *

service return url

}

Search payments

Open in API Explorer
GET /v1/payments

Search payments by reference, state, 'from' and 'to' date. The Authorisation token needs to be specified in the 'authorization' header as 'authorization: Bearer YOUR_API_KEY_HERE'

Example Request

Format:
curl --request GET \
  --url 'https://publicapi.payments.service.gov.uk/v1/payments?reference=foo&email=foo&state=foo&card_brand=foo&from_date=foo&to_date=foo&page=foo&display_size=foo' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR API KEY HERE'
require 'uri'
require 'net/http'

url = URI("https://publicapi.payments.service.gov.uk/v1/payments?reference=foo&email=foo&state=foo&card_brand=foo&from_date=foo&to_date=foo&page=foo&display_size=foo")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer YOUR API KEY HERE'

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "publicapi.payments.service.gov.uk",
  "port": null,
  "path": "/v1/payments?reference=foo&email=foo&state=foo&card_brand=foo&from_date=foo&to_date=foo&page=foo&display_size=foo",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer YOUR API KEY HERE"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://publicapi.payments.service.gov.uk/v1/payments?reference=foo&email=foo&state=foo&card_brand=foo&from_date=foo&to_date=foo&page=foo&display_size=foo",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "authorization: Bearer YOUR API KEY HERE"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
import http.client

conn = http.client.HTTPSConnection("publicapi.payments.service.gov.uk")

headers = {
    'accept': "application/json",
    'authorization': "Bearer YOUR API KEY HERE"
    }

conn.request("GET", "/v1/payments?reference=foo&email=foo&state=foo&card_brand=foo&from_date=foo&to_date=foo&page=foo&display_size=foo", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://publicapi.payments.service.gov.uk/v1/payments?reference=foo&email=foo&state=foo&card_brand=foo&from_date=foo&to_date=foo&page=foo&display_size=foo"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("accept", "application/json")
	req.Header.Add("authorization", "Bearer YOUR API KEY HERE")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Query Parameters

Name Type Required Description Example
reference String Optional

Your payment reference to search

foo
email String Optional

The user email used in the payment to be searched

foo
state String Optional

State of payments to be searched. Example=success

foo
card_brand String Optional

Card brand used for payment. Example=master-card

foo
from_date String Optional

From date of payments to be searched (this date is inclusive). Example=2015-08-13T12:35:00Z

foo
to_date String Optional

To date of payments to be searched (this date is exclusive). Example=2015-08-14T12:35:00Z

foo
page String Optional

Page number requested for the search, should be a positive integer (optional, defaults to 1)

foo
display_size String Optional

Number of results to be shown per page, should be a positive integer (optional, defaults to 500)

foo

Responses

200 OK

OK

General Payment search results
{
  results: [
Array

Results

    {
    { ... }
Object

Payment For Search Result

      "amount": 1200,
Integer (Int64)

Amount

      "state": {
      "state": { ... }
Object

State

        "status": "created",
String *

Current progress of the payment in its lifecycle

        "finished": true,
Boolean *

Whether the payment has finished

        "message": "User cancelled the payment",
String *

What went wrong with the Payment if it finished with an error - English message

        "code": "P010"
String *

What went wrong with the Payment if it finished with an error - error code

      },
      "description": "Your Service Description",
String

Description

      "reference": "your-reference",
String

Reference

      "email": "your email",
String

Email

      "payment_id": "hu20sqlact5260q2nanm0q8u93",
String

Payment

      "payment_provider": "worldpay",
String

Payment Provider

      "return_url": "http://your.service.domain/your-reference",
String

Return Url

      "created_date": "2016-01-21T17:15:00Z",
String

Created Date

      "refund_summary": {
      "refund_summary": { ... }
Object

Refund Summary

        "status": "available",
String

Availability status of the refund

        "amount_available": "589170615283802112",
Integer (Int64)

Amount available for refund in pence

        "amount_submitted": "589170615283802112"
Integer (Int64)

Amount submitted for refunds on this Payment in pence

      },
      "settlement_summary": {
      "settlement_summary": { ... }
Object

Settlement Summary

        "capture_submit_time": "2016-01-21T17:15:00Z",
String

Date and time capture request has been submitted (may be null if capture request was not immediately acknowledged by payment gateway)

        "captured_date": "2016-01-21"
String

Date of the capture event

      },
      "card_details": {
      "card_details": { ... }
Object

Card Details

        "last_digits_card_number": "1234",
String

Last Digits Card Number

        "cardholder_name": "Mr. Card holder",
String

Cardholder Name

        "expiry_date": "12/20",
String

Expiry Date

        "billing_address": {
        "billing_address": { ... }
Object

Billing Address

          "line1": "address line 1",
String

Line1

          "line2": "address line 2",
String

Line2

          "postcode": "AB1 2CD",
String

Postcode

          "city": "address city",
String

City

          "country": "UK"
String

Country

        },
        "card_brand": "Visa"
String

Card Brand

      },
      "_links": {
      "_links": { ... }
Object

Links

        "self": {
        "self": { ... }
Object

self

          "href": "https://an.example.link/from/payment/platform",
String

Href

          "method": "GET"
String

Method

        },
        "cancel": {
        "cancel": { ... }
Object

cancel

          "type": "multipart/form-data",
String

Type

          "params": {
          "params": { ... }
Object

Params

          },
          "href": "https://an.example.link/from/payment/platform",
String

Href

          "method": "POST"
String

Method

        },
        "events": {
        "events": { ... }
Object

events

          "href": "https://an.example.link/from/payment/platform",
String

Href

          "method": "GET"
String

Method

        },
        "refunds": {
        "refunds": { ... }
Object

refunds

          "href": "https://an.example.link/from/payment/platform",
String

Href

          "method": "GET"
String

Method

        }
      },
      "card_brand": "Visa"
String

Card Brand

    }
  ]
}
401 Unauthorized

Credentials are required to access this resource

(Empty Response)
422 Unprocessable Entity

Invalid parameters: from_date, to_date, status. See Public API documentation for the correct data formats

{Payment Id} Payment error
{
  "field": "amount",
String

Field

  "code": "P0102",
String

Code

  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000"
String

Description

}
500 Internal Server Error

Downstream system error

{Payment Id} Payment error
{
  "field": "amount",
String

Field

  "code": "P0102",
String

Code

  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000"
String

Description

}

Create new payment

Open in API Explorer
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'

Example Request

Format:
curl --request POST \
  --url https://publicapi.payments.service.gov.uk/v1/payments \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR API KEY HERE' \
  --header 'content-type: application/json' \
  --data '{"amount":12000,"reference":"12345","description":"New passport application","return_url":"https://service-name.gov.uk/transactions/12345"}'
require 'uri'
require 'net/http'

url = URI("https://publicapi.payments.service.gov.uk/v1/payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer YOUR API KEY HERE'
request["content-type"] = 'application/json'
request.body = "{\"amount\":12000,\"reference\":\"12345\",\"description\":\"New passport application\",\"return_url\":\"https://service-name.gov.uk/transactions/12345\"}"

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "POST",
  "hostname": "publicapi.payments.service.gov.uk",
  "port": null,
  "path": "/v1/payments",
  "headers": {
    "accept": "application/json",
    "authorization": "Bearer YOUR API KEY HERE",
    "content-type": "application/json"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({ amount: 12000,
  reference: '12345',
  description: 'New passport application',
  return_url: 'https://service-name.gov.uk/transactions/12345' }));
req.end();
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://publicapi.payments.service.gov.uk/v1/payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"amount\":12000,\"reference\":\"12345\",\"description\":\"New passport application\",\"return_url\":\"https://service-name.gov.uk/transactions/12345\"}",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "authorization: Bearer YOUR API KEY HERE",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
import http.client

conn = http.client.HTTPSConnection("publicapi.payments.service.gov.uk")

payload = "{\"amount\":12000,\"reference\":\"12345\",\"description\":\"New passport application\",\"return_url\":\"https://service-name.gov.uk/transactions/12345\"}"

headers = {
    'accept': "application/json",
    'authorization': "Bearer YOUR API KEY HERE",
    'content-type': "application/json"
    }

conn.request("POST", "/v1/payments", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://publicapi.payments.service.gov.uk/v1/payments"

	payload := strings.NewReader("{\"amount\":12000,\"reference\":\"12345\",\"description\":\"New passport application\",\"return_url\":\"https://service-name.gov.uk/transactions/12345\"}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("accept", "application/json")
	req.Header.Add("authorization", "Bearer YOUR API KEY HERE")
	req.Header.Add("content-type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Request Body

Name Type Required Description Example
body Object Required

requestPayload

{
  "amount": 12000,
Integer (Int32) *

amount in pence

  "reference": "12345",
String *

payment reference

  "description": "New passport application",
String *

payment description

  "return_url": "https://service-name.gov.uk/transactions/12345"
String *

service return url

}

Responses

201 Created

Created

{Payment Id} Payment with all links
{
  "amount": 1200,
Integer (Int64)

Amount

  "state": {
  "state": { ... }
Object

State

    "status": "created",
String *

Current progress of the payment in its lifecycle

    "finished": true,
Boolean *

Whether the payment has finished

    "message": "User cancelled the payment",
String *

What went wrong with the Payment if it finished with an error - English message

    "code": "P010"
String *

What went wrong with the Payment if it finished with an error - error code

  },
  "description": "Your Service Description",
String

Description

  "reference": "your-reference",
String

Reference

  "email": "your email",
String

Email

  "payment_id": "hu20sqlact5260q2nanm0q8u93",
String

Payment

  "payment_provider": "worldpay",
String

Payment Provider

  "return_url": "http://your.service.domain/your-reference",
String

Return Url

  "created_date": "2016-01-21T17:15:00Z",
String

Created Date

  "refund_summary": {
  "refund_summary": { ... }
Object

Refund Summary

    "status": "available",
String

Availability status of the refund

    "amount_available": "589170615283802112",
Integer (Int64)

Amount available for refund in pence

    "amount_submitted": "589170615283802112"
Integer (Int64)

Amount submitted for refunds on this Payment in pence

  },
  "settlement_summary": {
  "settlement_summary": { ... }
Object

Settlement Summary

    "capture_submit_time": "2016-01-21T17:15:00Z",
String

Date and time capture request has been submitted (may be null if capture request was not immediately acknowledged by payment gateway)

    "captured_date": "2016-01-21"
String

Date of the capture event

  },
  "card_details": {
  "card_details": { ... }
Object

Card Details

    "last_digits_card_number": "1234",
String

Last Digits Card Number

    "cardholder_name": "Mr. Card holder",
String

Cardholder Name

    "expiry_date": "12/20",
String

Expiry Date

    "billing_address": {
    "billing_address": { ... }
Object

Billing Address

      "line1": "address line 1",
String

Line1

      "line2": "address line 2",
String

Line2

      "postcode": "AB1 2CD",
String

Postcode

      "city": "address city",
String

City

      "country": "UK"
String

Country

    },
    "card_brand": "Visa"
String

Card Brand

  },
  "_links": {
  "_links": { ... }
Object

Links

    "self": {
    "self": { ... }
Object

self

      "href": "https://an.example.link/from/payment/platform",
String

Href

      "method": "GET"
String

Method

    },
    "next_url": {
    "next_url": { ... }
Object

next_url

      "href": "https://an.example.link/from/payment/platform",
String

Href

      "method": "GET"
String

Method

    },
    "next_url_post": {
    "next_url_post": { ... }
Object

next_url_post

      "type": "multipart/form-data",
String

Type

      "params": {
      "params": { ... }
Object

Params

      },
      "href": "https://an.example.link/from/payment/platform",
String

Href

      "method": "POST"
String

Method

    },
    "events": {
    "events": { ... }
Object

events

      "href": "https://an.example.link/from/payment/platform",
String

Href

      "method": "GET"
String

Method

    },
    "refunds": {
    "refunds": { ... }
Object

refunds

      "href": "https://an.example.link/from/payment/platform",
String

Href

      "method": "GET"
String

Method

    },
    "cancel": {
    "cancel": { ... }
Object

cancel

      "type": "multipart/form-data",
String

Type

      "params": {
      "params": { ... }
Object

Params

      },
      "href": "https://an.example.link/from/payment/platform",
String

Href

      "method": "POST"
String

Method

    }
  },
  "card_brand": "Visa"
String

Card Brand

}
400 Bad Request

Bad request

{Payment Id} Payment error
{
  "field": "amount",
String

Field

  "code": "P0102",
String

Code

  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000"
String

Description

}
401 Unauthorized

Credentials are required to access this resource

(Empty Response)
422 Unprocessable Entity

Invalid attribute value: description. Must be less than or equal to 255 characters length

{Payment Id} Payment error
{
  "field": "amount",
String

Field

  "code": "P0102",
String

Code

  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000"
String

Description

}
500 Internal Server Error

Downstream system error

{Payment Id} Payment error
{
  "field": "amount",
String

Field

  "code": "P0102",
String

Code

  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000"
String

Description

}