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=your-payment-reference&email=foo&state=SUCCEEDED&card_brand=foo&from_date=2016-01-21T17%3A15%3A00Z&to_date=2016-01-25T00%3A00%3A00Z&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=your-payment-reference&email=foo&state=SUCCEEDED&card_brand=foo&from_date=2016-01-21T17%3A15%3A00Z&to_date=2016-01-25T00%3A00%3A00Z&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=your-payment-reference&email=foo&state=SUCCEEDED&card_brand=foo&from_date=2016-01-21T17%3A15%3A00Z&to_date=2016-01-25T00%3A00%3A00Z&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=your-payment-reference&email=foo&state=SUCCEEDED&card_brand=foo&from_date=2016-01-21T17%3A15%3A00Z&to_date=2016-01-25T00%3A00%3A00Z&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=your-payment-reference&email=foo&state=SUCCEEDED&card_brand=foo&from_date=2016-01-21T17%3A15%3A00Z&to_date=2016-01-25T00%3A00%3A00Z&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=your-payment-reference&email=foo&state=SUCCEEDED&card_brand=foo&from_date=2016-01-21T17%3A15%3A00Z&to_date=2016-01-25T00%3A00%3A00Z&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

your-payment-reference
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

SUCCEEDED
card_brand String Optional

Card brand used for payment. Example=master-card

foo
from_date String (date-time) Optional

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

2016-01-21T17%3A15%3A00Z
to_date String (date-time) Optional

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

2016-01-25T00%3A00%3A00Z
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, max 500)

foo

Responses

200 OK

OK

General Payment search results
{
  results: [
Array

Results

    {
    { ... }
Object

Card Payment

      "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

      },
      "amount": 1200,
Integer (Int64)

Amount

      "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

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

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

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

Description

      "card_brand": "Visa",
String

Card Brand

      "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

    }
  ]
}
401 Unauthorized

Credentials are required to access this resource

(Empty Response)
422 Unprocessable Entity

Invalid parameters: from_date, to_date, status, display_size. 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
{
  "payment": {
  "payment": { ... }
Object

Payment

    "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

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

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

}