NAV Navigation
Shell HTTP JavaScript Node.JS Ruby Python Java Go

GOV.UK Pay API v1.0.3

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

GOV.UK Pay API

Base URLs:

Authentication

Card payments

Search payments

Code samples

# You can also use wget
curl -X GET https://publicapi.payments.service.gov.uk/v1/payments \
  -H 'Accept: application/json' \
  -H 'Authorization: API_KEY'

GET https://publicapi.payments.service.gov.uk/v1/payments HTTP/1.1
Host: publicapi.payments.service.gov.uk
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

$.ajax({
  url: 'https://publicapi.payments.service.gov.uk/v1/payments',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

fetch('https://publicapi.payments.service.gov.uk/v1/payments',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'API_KEY'
}

result = RestClient.get 'https://publicapi.payments.service.gov.uk/v1/payments',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'API_KEY'
}

r = requests.get('https://publicapi.payments.service.gov.uk/v1/payments', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://publicapi.payments.service.gov.uk/v1/payments");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://publicapi.payments.service.gov.uk/v1/payments", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /v1/payments

Search 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'

Parameters

Name In Type Required Description
reference query string false Your payment reference to search (exact match, case insensitive)
email query string false The user email used in the payment to be searched
state query string false State of payments to be searched. Example=success
card_brand query string false Card brand used for payment. Example=master-card
from_date query string false From date of payments to be searched (this date is inclusive). Example=2015-08-13T12:35:00Z
to_date query string false To date of payments to be searched (this date is exclusive). Example=2015-08-14T12:35:00Z
page query string false Page number requested for the search, should be a positive integer (optional, defaults to 1)
display_size query string false Number of results to be shown per page, should be a positive integer (optional, defaults to 500, max 500)
cardholder_name query string false Name on card used to make payment
first_digits_card_number query string false First six digits of the card used to make payment
last_digits_card_number query string false Last four digits of the card used to make payment

Enumerated Values

Parameter Value
state created
state started
state submitted
state success
state failed
state cancelled
state error

Example responses

200 Response

{
  "total": 100,
  "count": 20,
  "page": 1,
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "first_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "last_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "prev_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "next_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "results": [
    {
      "amount": 1200,
      "description": "Your Service Description",
      "reference": "your-reference",
      "language": "en",
      "metadata": {
        "property1": "string",
        "property2": "string"
      },
      "email": "your email",
      "state": {
        "status": "created",
        "finished": true,
        "message": "User cancelled the payment",
        "code": "P010"
      },
      "payment_id": "hu20sqlact5260q2nanm0q8u93",
      "payment_provider": "worldpay",
      "created_date": "2016-01-21T17:15:000Z",
      "refund_summary": {
        "status": "available",
        "amount_available": 100,
        "amount_submitted": 0
      },
      "settlement_summary": {
        "capture_submit_time": "2016-01-21T17:15:000Z",
        "captured_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"
      },
      "delayed_capture": false,
      "corporate_card_surcharge": 250,
      "total_amount": 1450,
      "fee": 5,
      "net_amount": 1195,
      "provider_id": "reference-from-payment-gateway",
      "return_url": "http://your.service.domain/your-reference",
      "_links": {
        "self": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        },
        "cancel": {
          "type": "application/x-www-form-urlencoded",
          "params": "\"description\":\"This is a value for a parameter called description\"",
          "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"
        },
        "capture": {
          "type": "application/x-www-form-urlencoded",
          "params": "\"description\":\"This is a value for a parameter called description\"",
          "href": "https://an.example.link/from/payment/platform",
          "method": "POST"
        }
      },
      "card_brand": "Visa"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK PaymentSearchResults
401 Unauthorized Credentials are required to access this resource None
422 Unprocessable Entity Invalid parameters: from_date, to_date, status, display_size. See Public API documentation for the correct data formats PaymentError
429 Too Many Requests Too many requests ErrorResponse
500 Internal Server Error Downstream system error PaymentError

Create a payment

Code samples

# You can also use wget
curl -X POST https://publicapi.payments.service.gov.uk/v1/payments \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: API_KEY'

POST https://publicapi.payments.service.gov.uk/v1/payments HTTP/1.1
Host: publicapi.payments.service.gov.uk
Content-Type: application/json
Accept: application/json

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

$.ajax({
  url: 'https://publicapi.payments.service.gov.uk/v1/payments',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');
const inputBody = '{
  "prefilled_cardholder_details": {
    "cardholder_name": "J. Bogs",
    "billing_address": {}
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

fetch('https://publicapi.payments.service.gov.uk/v1/payments',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'API_KEY'
}

result = RestClient.post 'https://publicapi.payments.service.gov.uk/v1/payments',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'API_KEY'
}

r = requests.post('https://publicapi.payments.service.gov.uk/v1/payments', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://publicapi.payments.service.gov.uk/v1/payments");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://publicapi.payments.service.gov.uk/v1/payments", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /v1/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'

Body parameter

{
  "prefilled_cardholder_details": {
    "cardholder_name": "J. Bogs",
    "billing_address": {}
  }
}

Parameters

Name In Type Required Description
body body CreateCardPaymentRequest true requestPayload

Example responses

201 Response

{
  "amount": 1200,
  "state": {
    "status": "created",
    "finished": true,
    "message": "User cancelled the payment",
    "code": "P010"
  },
  "description": "Your Service Description",
  "reference": "your-reference",
  "language": "en",
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "payment_provider": "worldpay",
  "return_url": "http://your.service.domain/your-reference",
  "created_date": "2016-01-21T17:15:00Z",
  "delayed_capture": true,
  "_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",
      "params": "\"description\":\"This is a value for a parameter called description\"",
      "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",
      "params": "\"description\":\"This is a value for a parameter called description\"",
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST"
    },
    "capture": {
      "type": "application/x-www-form-urlencoded",
      "params": "\"description\":\"This is a value for a parameter called description\"",
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST"
    }
  },
  "provider_id": "null",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "email": "citizen@example.org",
  "refund_summary": {
    "status": "available",
    "amount_available": 100,
    "amount_submitted": 0
  },
  "settlement_summary": {
    "capture_submit_time": "2016-01-21T17:15:000Z",
    "captured_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"
  }
}

Responses

Status Meaning Description Schema
201 Created Created CreatePaymentResult
400 Bad Request Bad request PaymentError
401 Unauthorized Credentials are required to access this resource None
422 Unprocessable Entity Invalid attribute value: description. Must be less than or equal to 255 characters length PaymentError
429 Too Many Requests Too many requests ErrorResponse
500 Internal Server Error Downstream system error PaymentError

Get a payment

Code samples

# You can also use wget
curl -X GET https://publicapi.payments.service.gov.uk/v1/payments/{paymentId} \
  -H 'Accept: application/json' \
  -H 'Authorization: API_KEY'

GET https://publicapi.payments.service.gov.uk/v1/payments/{paymentId} HTTP/1.1
Host: publicapi.payments.service.gov.uk
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

$.ajax({
  url: 'https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

fetch('https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'API_KEY'
}

result = RestClient.get 'https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'API_KEY'
}

r = requests.get('https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /v1/payments/{paymentId}

Find payment by ID

Return information about the payment The Authorisation token needs to be specified in the 'authorization' header as 'authorization: Bearer YOUR_API_KEY_HERE'

Parameters

Name In Type Required Description
paymentId path string true Payment identifier

Example responses

200 Response

{
  "amount": 1200,
  "description": "Your Service Description",
  "reference": "your-reference",
  "language": "en",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "email": "your email",
  "state": {
    "status": "created",
    "finished": true,
    "message": "User cancelled the payment",
    "code": "P010"
  },
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "payment_provider": "worldpay",
  "created_date": "2016-01-21T17:15:000Z",
  "refund_summary": {
    "status": "available",
    "amount_available": 100,
    "amount_submitted": 0
  },
  "settlement_summary": {
    "capture_submit_time": "2016-01-21T17:15:000Z",
    "captured_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"
  },
  "delayed_capture": false,
  "corporate_card_surcharge": 250,
  "total_amount": 1450,
  "fee": 5,
  "net_amount": 1195,
  "provider_id": "reference-from-payment-gateway",
  "return_url": "http://your.service.domain/your-reference",
  "_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",
      "params": "\"description\":\"This is a value for a parameter called description\"",
      "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",
      "params": "\"description\":\"This is a value for a parameter called description\"",
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST"
    },
    "capture": {
      "type": "application/x-www-form-urlencoded",
      "params": "\"description\":\"This is a value for a parameter called description\"",
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST"
    }
  },
  "card_brand": "Visa"
}

Responses

Status Meaning Description Schema
200 OK OK GetPaymentResult
401 Unauthorized Credentials are required to access this resource None
404 Not Found Not found PaymentError
429 Too Many Requests Too many requests ErrorResponse
500 Internal Server Error Downstream system error PaymentError

Cancel a payment

Code samples

# You can also use wget
curl -X POST https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/cancel \
  -H 'Accept: application/json' \
  -H 'Authorization: API_KEY'

POST https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/cancel HTTP/1.1
Host: publicapi.payments.service.gov.uk
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

$.ajax({
  url: 'https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/cancel',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

fetch('https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/cancel',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'API_KEY'
}

result = RestClient.post 'https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/cancel',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'API_KEY'
}

r = requests.post('https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/cancel', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/cancel");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/cancel", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /v1/payments/{paymentId}/cancel

Cancel payment

Cancel a payment based on the provided payment ID and the Authorisation token. The Authorisation token needs to be specified in the 'authorization' header as 'authorization: Bearer YOUR_API_KEY_HERE'. A payment can only be cancelled if it's in a state that isn't finished.

Parameters

Name In Type Required Description
paymentId path string true Payment identifier

Example responses

400 Response

{
  "field": "amount",
  "code": "P0102",
  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000"
}

Responses

Status Meaning Description Schema
204 No Content No Content None
400 Bad Request Cancellation of payment failed PaymentError
401 Unauthorized Credentials are required to access this resource None
404 Not Found Not found PaymentError
409 Conflict Conflict PaymentError
429 Too Many Requests Too many requests ErrorResponse
500 Internal Server Error Downstream system error PaymentError

Capture a payment

Code samples

# You can also use wget
curl -X POST https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/capture \
  -H 'Accept: application/json' \
  -H 'Authorization: API_KEY'

POST https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/capture HTTP/1.1
Host: publicapi.payments.service.gov.uk
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

$.ajax({
  url: 'https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/capture',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

fetch('https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/capture',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'API_KEY'
}

result = RestClient.post 'https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/capture',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'API_KEY'
}

r = requests.post('https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/capture', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/capture");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/capture", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /v1/payments/{paymentId}/capture

Capture payment

Capture a payment based on the provided payment ID and the Authorisation token. The Authorisation token needs to be specified in the 'authorization' header as 'authorization: Bearer YOUR_API_KEY_HERE'. A payment can only be captured if it's in 'submitted' state

Parameters

Name In Type Required Description
paymentId path string true Payment identifier

Example responses

400 Response

{
  "field": "amount",
  "code": "P0102",
  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000"
}

Responses

Status Meaning Description Schema
204 No Content No Content None
400 Bad Request Capture of payment failed PaymentError
401 Unauthorized Credentials are required to access this resource None
404 Not Found Not found PaymentError
409 Conflict Conflict PaymentError
429 Too Many Requests Too many requests ErrorResponse
500 Internal Server Error Downstream system error PaymentError

Get events for a payment

Code samples

# You can also use wget
curl -X GET https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/events \
  -H 'Accept: application/json' \
  -H 'Authorization: API_KEY'

GET https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/events HTTP/1.1
Host: publicapi.payments.service.gov.uk
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

$.ajax({
  url: 'https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/events',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

fetch('https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/events',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'API_KEY'
}

result = RestClient.get 'https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/events',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'API_KEY'
}

r = requests.get('https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/events', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/events");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/events", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /v1/payments/{paymentId}/events

Return payment events by ID

Return payment events information about a certain payment The Authorisation token needs to be specified in the 'authorization' header as 'authorization: Bearer YOUR_API_KEY_HERE'

Parameters

Name In Type Required Description
paymentId path string true Payment identifier

Example responses

200 Response

{
  "events": [
    {
      "payment_id": "hu20sqlact5260q2nanm0q8u93",
      "state": {
        "status": "created",
        "finished": true,
        "message": "User cancelled the payment",
        "code": "P010"
      },
      "updated": "2017-01-10T16:44:48.646Z",
      "_links": {
        "payment_url": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        }
      }
    }
  ],
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  }
}

Responses

Status Meaning Description Schema
200 OK OK PaymentEvents
401 Unauthorized Credentials are required to access this resource None
404 Not Found Not found PaymentError
429 Too Many Requests Too many requests ErrorResponse
500 Internal Server Error Downstream system error PaymentError

Direct Debit

Search mandates

Code samples

# You can also use wget
curl -X GET https://publicapi.payments.service.gov.uk/v1/directdebit/mandates \
  -H 'Accept: application/json' \
  -H 'Authorization: API_KEY'

GET https://publicapi.payments.service.gov.uk/v1/directdebit/mandates HTTP/1.1
Host: publicapi.payments.service.gov.uk
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

$.ajax({
  url: 'https://publicapi.payments.service.gov.uk/v1/directdebit/mandates',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

fetch('https://publicapi.payments.service.gov.uk/v1/directdebit/mandates',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'API_KEY'
}

result = RestClient.get 'https://publicapi.payments.service.gov.uk/v1/directdebit/mandates',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'API_KEY'
}

r = requests.get('https://publicapi.payments.service.gov.uk/v1/directdebit/mandates', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://publicapi.payments.service.gov.uk/v1/directdebit/mandates");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://publicapi.payments.service.gov.uk/v1/directdebit/mandates", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /v1/directdebit/mandates

Search mandates

Searches for mandates with the parameters provided. The Authorisation token needs to be specified in the 'Authorization' header as 'Authorization: Bearer YOUR_API_KEY_HERE'

Parameters

Name In Type Required Description
reference query string false none
state query string false none
bank_statement_reference query string false none
email query string false none
name query string false none
from_date query string false From date of mandates to be searched (this date is inclusive). Example=2015-08-13T12:35:00Z
to_date query string false To date of mandates to be searched (this date is exclusive). Example=2015-08-13T12:35:00Z
page query integer(int32) false Page number requested for the search, should be a positive integer (optional, defaults to 1)
display_size query integer(int32) false Number of results to be shown per page, should be a positive integer (optional, defaults to 500, max 500)

Example responses

200 Response

{
  "total": 0,
  "count": 0,
  "page": 0,
  "results": [
    {
      "mandate_id": "jhjcvaiqlediuhh23d89hd3",
      "provider_id": "jhjcvaiqlediuhh23d89hd3",
      "reference": "jhjcvaiqlediuhh23d89hd3",
      "return_url": "https://service-name.gov.uk/transactions/12345",
      "state": {
        "status": "string",
        "details": "string"
      },
      "_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",
          "params": "\"description\":\"This is a value for a parameter called description\"",
          "href": "https://an.example.link/from/payment/platform",
          "method": "POST"
        },
        "payments": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        }
      },
      "bank_statement_reference": "string",
      "created_date": "string",
      "description": "string",
      "payment_provider": "string",
      "payer": {
        "name": "string",
        "email": "string"
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "first_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "last_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "prev_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "next_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  }
}

Responses

Status Meaning Description Schema
200 OK OK SearchMandateResponse
401 Unauthorized Credentials are required to access this resource None
404 Not Found Not found MandateError
422 Unprocessable Entity Invalid parameters: from_date, to_date, state, page, display_size. See Public API documentation for the correct data formats PaymentError
429 Too Many Requests Too many requests ErrorResponse
500 Internal Server Error Downstream system error MandateError

Create a mandate

Code samples

# You can also use wget
curl -X POST https://publicapi.payments.service.gov.uk/v1/directdebit/mandates \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: API_KEY'

POST https://publicapi.payments.service.gov.uk/v1/directdebit/mandates HTTP/1.1
Host: publicapi.payments.service.gov.uk
Content-Type: application/json
Accept: application/json

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

$.ajax({
  url: 'https://publicapi.payments.service.gov.uk/v1/directdebit/mandates',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');
const inputBody = '{}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

fetch('https://publicapi.payments.service.gov.uk/v1/directdebit/mandates',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'API_KEY'
}

result = RestClient.post 'https://publicapi.payments.service.gov.uk/v1/directdebit/mandates',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'API_KEY'
}

r = requests.post('https://publicapi.payments.service.gov.uk/v1/directdebit/mandates', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://publicapi.payments.service.gov.uk/v1/directdebit/mandates");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://publicapi.payments.service.gov.uk/v1/directdebit/mandates", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /v1/directdebit/mandates

Create a new mandate

Create a new mandate 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'

Body parameter

{}

Parameters

Name In Type Required Description
body body CreateMandateRequest true requestPayload

Example responses

201 Response

{
  "mandate_id": "jhjcvaiqlediuhh23d89hd3",
  "provider_id": "jhjcvaiqlediuhh23d89hd3",
  "reference": "jhjcvaiqlediuhh23d89hd3",
  "return_url": "https://service-name.gov.uk/transactions/12345",
  "state": {
    "status": "string",
    "details": "string"
  },
  "_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",
      "params": "\"description\":\"This is a value for a parameter called description\"",
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST"
    },
    "payments": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "bank_statement_reference": "string",
  "created_date": "string",
  "description": "string",
  "payment_provider": "string",
  "payer": {
    "name": "string",
    "email": "string"
  }
}

Responses

Status Meaning Description Schema
201 Created Created MandateResponse
400 Bad Request Bad request PaymentError
401 Unauthorized Credentials are required to access this resource None
429 Too Many Requests Too many requests ErrorResponse
500 Internal Server Error Downstream system error PaymentError

Get a mandate

Code samples

# You can also use wget
curl -X GET https://publicapi.payments.service.gov.uk/v1/directdebit/mandates/{mandateId} \
  -H 'Accept: application/json' \
  -H 'Authorization: API_KEY'

GET https://publicapi.payments.service.gov.uk/v1/directdebit/mandates/{mandateId} HTTP/1.1
Host: publicapi.payments.service.gov.uk
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

$.ajax({
  url: 'https://publicapi.payments.service.gov.uk/v1/directdebit/mandates/{mandateId}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

fetch('https://publicapi.payments.service.gov.uk/v1/directdebit/mandates/{mandateId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'API_KEY'
}

result = RestClient.get 'https://publicapi.payments.service.gov.uk/v1/directdebit/mandates/{mandateId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'API_KEY'
}

r = requests.get('https://publicapi.payments.service.gov.uk/v1/directdebit/mandates/{mandateId}', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://publicapi.payments.service.gov.uk/v1/directdebit/mandates/{mandateId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://publicapi.payments.service.gov.uk/v1/directdebit/mandates/{mandateId}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /v1/directdebit/mandates/{mandateId}

Find mandate by ID

Return information about the mandate. The Authorisation token needs to be specified in the 'Authorization' header as 'Authorization: Bearer YOUR_API_KEY_HERE'

Parameters

Name In Type Required Description
mandateId path string true none

Example responses

200 Response

{
  "mandate_id": "jhjcvaiqlediuhh23d89hd3",
  "provider_id": "jhjcvaiqlediuhh23d89hd3",
  "reference": "jhjcvaiqlediuhh23d89hd3",
  "return_url": "https://service-name.gov.uk/transactions/12345",
  "state": {
    "status": "string",
    "details": "string"
  },
  "_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",
      "params": "\"description\":\"This is a value for a parameter called description\"",
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST"
    },
    "payments": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "bank_statement_reference": "string",
  "created_date": "string",
  "description": "string",
  "payment_provider": "string",
  "payer": {
    "name": "string",
    "email": "string"
  }
}

Responses

Status Meaning Description Schema
200 OK OK MandateResponse
401 Unauthorized Credentials are required to access this resource None
404 Not Found Not found MandateError
429 Too Many Requests Too many requests ErrorResponse
500 Internal Server Error Downstream system error MandateError

Search Direct Debit payments

Code samples

# You can also use wget
curl -X GET https://publicapi.payments.service.gov.uk/v1/directdebit/payments \
  -H 'Accept: application/json' \
  -H 'Authorization: API_KEY'

GET https://publicapi.payments.service.gov.uk/v1/directdebit/payments HTTP/1.1
Host: publicapi.payments.service.gov.uk
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

$.ajax({
  url: 'https://publicapi.payments.service.gov.uk/v1/directdebit/payments',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

fetch('https://publicapi.payments.service.gov.uk/v1/directdebit/payments',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'API_KEY'
}

result = RestClient.get 'https://publicapi.payments.service.gov.uk/v1/directdebit/payments',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'API_KEY'
}

r = requests.get('https://publicapi.payments.service.gov.uk/v1/directdebit/payments', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://publicapi.payments.service.gov.uk/v1/directdebit/payments");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://publicapi.payments.service.gov.uk/v1/directdebit/payments", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /v1/directdebit/payments

Search Direct Debit payments

Search Direct Debit payments by reference, state, mandate id, and 'from' and 'to' dates. The Authorisation token needs to be specified in the 'Authorization' header as 'Authorization: Bearer YOUR_API_KEY_HERE'

Parameters

Name In Type Required Description
reference query string false Your payment reference to search
state query string false State of payments to be searched. Example=success
mandate_id query string false The GOV.UK Pay identifier for the mandate
from_date query string false From date of Direct Debit payments to be searched (this date is inclusive). Example=2015-08-13T12:35:00Z
to_date query string false To date of Direct Debit payments to be searched (this date is exclusive). Example=2015-08-13T12:35:00Z
page query integer(int32) false Page number requested for the search, should be a positive integer (optional, defaults to 1)
display_size query integer(int32) false Number of results to be shown per page, should be a positive integer (optional, defaults to 500, max 500)

Example responses

200 Response

{
  "total": 0,
  "count": 0,
  "page": 0,
  "results": [
    {
      "amount": 0,
      "state": {
        "details": "string",
        "status": "string"
      },
      "description": "string",
      "reference": "string",
      "mandate_id": "string",
      "payment_id": "string",
      "payment_provider": "string",
      "created_date": "string",
      "provider_id": "string"
    }
  ],
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "first_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "last_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "prev_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "next_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  }
}

Responses

Status Meaning Description Schema
200 OK OK DirectDebitSearchResponse
401 Unauthorized Credentials are required to access this resource None
422 Unprocessable Entity Invalid parameter. See Public API documentation for the correct data formats PaymentError
429 Too Many Requests Too many requests ErrorResponse
500 Internal Server Error Downstream system error PaymentError

Collect a Direct Debit payment

Code samples

# You can also use wget
curl -X POST https://publicapi.payments.service.gov.uk/v1/directdebit/payments \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: API_KEY'

POST https://publicapi.payments.service.gov.uk/v1/directdebit/payments HTTP/1.1
Host: publicapi.payments.service.gov.uk
Content-Type: application/json
Accept: application/json

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

$.ajax({
  url: 'https://publicapi.payments.service.gov.uk/v1/directdebit/payments',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');
const inputBody = '{}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

fetch('https://publicapi.payments.service.gov.uk/v1/directdebit/payments',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'API_KEY'
}

result = RestClient.post 'https://publicapi.payments.service.gov.uk/v1/directdebit/payments',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'API_KEY'
}

r = requests.post('https://publicapi.payments.service.gov.uk/v1/directdebit/payments', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://publicapi.payments.service.gov.uk/v1/directdebit/payments");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://publicapi.payments.service.gov.uk/v1/directdebit/payments", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /v1/directdebit/payments

Create new Direct Debit payment

Create a new Direct Debit 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'

Body parameter

{}

Parameters

Name In Type Required Description
body body CreateDirectDebitPaymentRequest true requestPayload

Example responses

201 Response

{
  "amount": 1200,
  "description": "Your Service Description",
  "reference": "your-reference",
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "payment_provider": "worldpay",
  "created_date": "2016-01-21T17:15:000Z",
  "mandate_id": "string",
  "provider_id": "string",
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "mandate": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "state": {
    "details": "string",
    "status": "string"
  }
}

Responses

Status Meaning Description Schema
201 Created Created DirectDebitPayment
400 Bad Request Bad request PaymentError
401 Unauthorized Credentials are required to access this resource None
422 Unprocessable Entity Invalid parameters: amount, reference, description, mandate id. See Public API documentation for the correct data formats PaymentError
429 Too Many Requests Too many requests ErrorResponse
500 Internal Server Error Downstream system error PaymentError

Get a Direct Debit payment

Code samples

# You can also use wget
curl -X GET https://publicapi.payments.service.gov.uk/v1/directdebit/payments/{paymentId} \
  -H 'Accept: application/json' \
  -H 'Authorization: API_KEY'

GET https://publicapi.payments.service.gov.uk/v1/directdebit/payments/{paymentId} HTTP/1.1
Host: publicapi.payments.service.gov.uk
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

$.ajax({
  url: 'https://publicapi.payments.service.gov.uk/v1/directdebit/payments/{paymentId}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

fetch('https://publicapi.payments.service.gov.uk/v1/directdebit/payments/{paymentId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'API_KEY'
}

result = RestClient.get 'https://publicapi.payments.service.gov.uk/v1/directdebit/payments/{paymentId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'API_KEY'
}

r = requests.get('https://publicapi.payments.service.gov.uk/v1/directdebit/payments/{paymentId}', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://publicapi.payments.service.gov.uk/v1/directdebit/payments/{paymentId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://publicapi.payments.service.gov.uk/v1/directdebit/payments/{paymentId}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /v1/directdebit/payments/{paymentId}

Find Direct Debit payment by ID

Return information about the Direct Debit payment. The Authorisation token needs to be specified in the 'Authorization' header as 'Authorization: Bearer YOUR_API_KEY_HERE'

Parameters

Name In Type Required Description
paymentId path string true Payment identifier

Example responses

200 Response

{
  "amount": 1200,
  "description": "Your Service Description",
  "reference": "your-reference",
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "payment_provider": "worldpay",
  "created_date": "2016-01-21T17:15:000Z",
  "mandate_id": "string",
  "provider_id": "string",
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "mandate": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "state": {
    "details": "string",
    "status": "string"
  }
}

Responses

Status Meaning Description Schema
200 OK OK DirectDebitPayment
401 Unauthorized Credentials are required to access this resource None
404 Not Found Not found PaymentError
429 Too Many Requests Too many requests ErrorResponse
500 Internal Server Error Downstream system error PaymentError

Refunding card payments

Get all refunds for a payment

Code samples

# You can also use wget
curl -X GET https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds \
  -H 'Accept: application/json' \
  -H 'Authorization: API_KEY'

GET https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds HTTP/1.1
Host: publicapi.payments.service.gov.uk
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

$.ajax({
  url: 'https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

fetch('https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'API_KEY'
}

result = RestClient.get 'https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'API_KEY'
}

r = requests.get('https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /v1/payments/{paymentId}/refunds

Get all refunds for a payment

Return refunds for a payment. The Authorisation token needs to be specified in the 'authorization' header as 'authorization: Bearer YOUR_API_KEY_HERE'

Parameters

Name In Type Required Description
paymentId path string true none

Example responses

200 Response

{
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "payment": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "_embedded": {
    "refunds": [
      {
        "refund_id": "act4c33g40j3edfmi8jknab84x",
        "created_date": "2017-01-10T16:52:07.855Z",
        "amount": 120,
        "_links": {
          "self": {
            "href": "https://an.example.link/from/payment/platform",
            "method": "GET"
          },
          "payment": {
            "href": "https://an.example.link/from/payment/platform",
            "method": "GET"
          }
        },
        "status": "success"
      }
    ]
  }
}

Responses

Status Meaning Description Schema
200 OK OK RefundForSearchResult
401 Unauthorized Credentials are required to access this resource None
404 Not Found Not found PaymentError
429 Too Many Requests Too many requests ErrorResponse
500 Internal Server Error Downstream system error PaymentError

Submit a refund for a payment

Code samples

# You can also use wget
curl -X POST https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: API_KEY'

POST https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds HTTP/1.1
Host: publicapi.payments.service.gov.uk
Content-Type: application/json
Accept: application/json

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

$.ajax({
  url: 'https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');
const inputBody = '{
  "amount": 150000
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

fetch('https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'API_KEY'
}

result = RestClient.post 'https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'API_KEY'
}

r = requests.post('https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /v1/payments/{paymentId}/refunds

Submit a refund for a payment

Return issued refund information. The Authorisation token needs to be specified in the 'authorization' header as 'authorization: Bearer YOUR_API_KEY_HERE'

Body parameter

{
  "amount": 150000
}

Parameters

Name In Type Required Description
paymentId path string true paymentId
body body PaymentRefundRequest true requestPayload

Example responses

200 Response

{
  "refund_id": "act4c33g40j3edfmi8jknab84x",
  "created_date": "2017-01-10T16:52:07.855Z",
  "amount": 120,
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "payment": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "status": "success"
}

Responses

Status Meaning Description Schema
200 OK successful operation Refund
202 Accepted ACCEPTED None
401 Unauthorized Credentials are required to access this resource None
404 Not Found Not found PaymentError
412 Precondition Failed Refund amount available mismatch None
429 Too Many Requests Too many requests ErrorResponse
500 Internal Server Error Downstream system error PaymentError

Get a payment refund

Code samples

# You can also use wget
curl -X GET https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds/{refundId} \
  -H 'Accept: application/json' \
  -H 'Authorization: API_KEY'

GET https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds/{refundId} HTTP/1.1
Host: publicapi.payments.service.gov.uk
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

$.ajax({
  url: 'https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds/{refundId}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

fetch('https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds/{refundId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'API_KEY'
}

result = RestClient.get 'https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds/{refundId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'API_KEY'
}

r = requests.get('https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds/{refundId}', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds/{refundId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/refunds/{refundId}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /v1/payments/{paymentId}/refunds/{refundId}

Find payment refund by ID

Return payment refund information by Refund ID The Authorisation token needs to be specified in the 'authorization' header as 'authorization: Bearer YOUR_API_KEY_HERE'

Parameters

Name In Type Required Description
paymentId path string true none
refundId path string true none

Example responses

200 Response

{
  "refund_id": "act4c33g40j3edfmi8jknab84x",
  "created_date": "2017-01-10T16:52:07.855Z",
  "amount": 120,
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "payment": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "status": "success"
}

Responses

Status Meaning Description Schema
200 OK OK Refund
401 Unauthorized Credentials are required to access this resource None
404 Not Found Not found PaymentError
429 Too Many Requests Too many requests ErrorResponse
500 Internal Server Error Downstream system error PaymentError

Search refunds

Code samples

# You can also use wget
curl -X GET https://publicapi.payments.service.gov.uk/v1/refunds \
  -H 'Accept: application/json' \
  -H 'Authorization: API_KEY'

GET https://publicapi.payments.service.gov.uk/v1/refunds HTTP/1.1
Host: publicapi.payments.service.gov.uk
Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

$.ajax({
  url: 'https://publicapi.payments.service.gov.uk/v1/refunds',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'API_KEY'

};

fetch('https://publicapi.payments.service.gov.uk/v1/refunds',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'API_KEY'
}

result = RestClient.get 'https://publicapi.payments.service.gov.uk/v1/refunds',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'API_KEY'
}

r = requests.get('https://publicapi.payments.service.gov.uk/v1/refunds', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://publicapi.payments.service.gov.uk/v1/refunds");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"API_KEY"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://publicapi.payments.service.gov.uk/v1/refunds", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /v1/refunds

Search refunds

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

Parameters

Name In Type Required Description
from_date query string false From date of refunds to be searched (this date is inclusive). Example=2015-08-13T12:35:00Z
to_date query string false To date of refunds to be searched (this date is exclusive). Example=2015-08-14T12:35:00Z
page query string false Page number requested for the search, should be a positive integer (optional, defaults to 1)
display_size query string false Number of results to be shown per page, should be a positive integer (optional, defaults to 500, max 500)

Example responses

200 Response

{
  "total": 100,
  "count": 20,
  "page": 1,
  "results": [
    {
      "refund_id": "act4c33g40j3edfmi8jknab84x",
      "created_date": "2017-01-10T16:52:07.855Z",
      "amount": 120,
      "_links": {
        "self": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        },
        "payment": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        }
      },
      "status": "success"
    }
  ],
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "first_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "last_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "prev_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "next_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  }
}

Responses

Status Meaning Description Schema
200 OK OK RefundSearchResults
401 Unauthorized Credentials are required to access this resource None
422 Unprocessable Entity Invalid parameters. See Public API documentation for the correct data formats RefundError
500 Internal Server Error Downstream system error RefundError

Schemas

Address

{
  "line1": "address line 1",
  "line2": "address line 2",
  "postcode": "AB1 2CD",
  "city": "address city",
  "country": "GB"
}

A structure representing the billing address of a card

Properties

Name Type Required Restrictions Description
line1 string false read-only none
line2 string false read-only none
postcode string false read-only none
city string false read-only none
country string false read-only none

CardDetails

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

A structure representing the payment card

Properties

Name Type Required Restrictions Description
last_digits_card_number string false read-only none
first_digits_card_number string false read-only none
cardholder_name string false read-only none
expiry_date string false read-only The expiry date of the card in MM/yy format
billing_address Address false none A structure representing the billing address of a card
card_brand string false read-only none
card_type string false read-only The card type, debit or credit or null if not able to determine

Enumerated Values

Property Value
card_type debit
card_type credit
card_type null

CreateCardPaymentRequest

{
  "amount": 12000,
  "reference": "12345",
  "description": "New passport application",
  "language": "en",
  "email": "Joe.Bogs@example.org",
  "return_url": "https://service-name.gov.uk/transactions/12345",
  "delayed_capture": false,
  "metadata": "{\"ledger_code\":\"123\", \"reconciled\": true}",
  "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"
    }
  }
}

The Payment Request Payload

Properties

Name Type Required Restrictions Description
amount integer(int32) true read-only amount in pence
reference string true read-only payment reference
description string true read-only payment description
language string false read-only ISO-639-1 Alpha-2 code of a supported language to use on the payment pages
email string false read-only email
return_url string true read-only service return url
delayed_capture boolean false read-only delayed capture flag
metadata object false read-only 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.
» additionalProperties object false none none
prefilled_cardholder_details PrefilledCardholderDetails false none prefilled_cardholder_details

Enumerated Values

Property Value
language en
language cy

CreateDirectDebitPaymentRequest

{
  "amount": 12000,
  "reference": "12345",
  "description": "New passport application",
  "mandate_id": "33890b55-b9ea-4e2f-90fd-77ae0e9009e2"
}

The Direct Debit Payment Request Payload

Properties

Name Type Required Restrictions Description
amount integer(int32) true read-only amount in pence
reference string true read-only payment reference
description string true read-only payment description
mandate_id string false read-only ID of the mandates being used to collect the payment

CreateMandateRequest

{
  "return_url": "https://service-name.gov.uk/transactions/12345",
  "reference": "test_service_reference",
  "description": "string"
}

The Payload to create a new Mandate

Properties

Name Type Required Restrictions Description
return_url string true read-only mandate return url
reference string true read-only mandate reference
description string false read-only mandate description

CreatePaymentResult

{
  "amount": 1200,
  "state": {
    "status": "created",
    "finished": true,
    "message": "User cancelled the payment",
    "code": "P010"
  },
  "description": "Your Service Description",
  "reference": "your-reference",
  "language": "en",
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "payment_provider": "worldpay",
  "return_url": "http://your.service.domain/your-reference",
  "created_date": "2016-01-21T17:15:00Z",
  "delayed_capture": true,
  "_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",
      "params": "\"description\":\"This is a value for a parameter called description\"",
      "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",
      "params": "\"description\":\"This is a value for a parameter called description\"",
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST"
    },
    "capture": {
      "type": "application/x-www-form-urlencoded",
      "params": "\"description\":\"This is a value for a parameter called description\"",
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST"
    }
  },
  "provider_id": "null",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "email": "citizen@example.org",
  "refund_summary": {
    "status": "available",
    "amount_available": 100,
    "amount_submitted": 0
  },
  "settlement_summary": {
    "capture_submit_time": "2016-01-21T17:15:000Z",
    "captured_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"
  }
}

Properties

Name Type Required Restrictions Description
amount integer(int64) false none none
state PaymentState false none A structure representing the current state of the payment in its lifecycle.
description string false none none
reference string false none none
language string false none none
payment_id string false none none
payment_provider string false none none
return_url string false none none
created_date string false none none
delayed_capture boolean false none none
_links PaymentLinks false none links for payment
provider_id string false none none
metadata object false none none
» additionalProperties string false none none
email string false none none
refund_summary RefundSummary false none A structure representing the refunds availability
settlement_summary SettlementSummary false none A structure representing information about a settlement
card_details CardDetails false none A structure representing the payment card

Enumerated Values

Property Value
language en
language cy

DirectDebitConnectorPaymentResponse

{
  "amount": 0,
  "state": {
    "details": "string",
    "status": "string"
  },
  "description": "string",
  "reference": "string",
  "mandate_id": "string",
  "payment_id": "string",
  "payment_provider": "string",
  "created_date": "string",
  "provider_id": "string"
}

Properties

Name Type Required Restrictions Description
amount integer(int64) false read-only none
state DirectDebitPaymentState false none none
description string false read-only none
reference string false read-only none
mandate_id string false read-only none
payment_id string false read-only none
payment_provider string false read-only none
created_date string false read-only none
provider_id string false read-only none

DirectDebitPayment

{
  "amount": 1200,
  "description": "Your Service Description",
  "reference": "your-reference",
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "payment_provider": "worldpay",
  "created_date": "2016-01-21T17:15:000Z",
  "mandate_id": "string",
  "provider_id": "string",
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "mandate": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "state": {
    "details": "string",
    "status": "string"
  }
}

Properties

Name Type Required Restrictions Description
amount integer(int64) false none none
description string false none none
reference string false none none
payment_id string false read-only none
payment_provider string false read-only none
created_date string false read-only none
mandate_id string false read-only none
provider_id string false read-only none
_links DirectDebitPaymentLinks false none links for payment
state DirectDebitPaymentState false none none

{
  "self": {
    "href": "https://an.example.link/from/payment/platform",
    "method": "GET"
  },
  "mandate": {
    "href": "https://an.example.link/from/payment/platform",
    "method": "GET"
  }
}

links for payment

Properties

Name Type Required Restrictions Description
self Link false none A link related to a payment
mandate Link false none A link related to a payment

DirectDebitPaymentState

{
  "details": "string",
  "status": "string"
}

Properties

Name Type Required Restrictions Description
details string false none none
status string false none none

DirectDebitSearchResponse

{
  "total": 0,
  "count": 0,
  "page": 0,
  "results": [
    {
      "amount": 0,
      "state": {
        "details": "string",
        "status": "string"
      },
      "description": "string",
      "reference": "string",
      "mandate_id": "string",
      "payment_id": "string",
      "payment_provider": "string",
      "created_date": "string",
      "provider_id": "string"
    }
  ],
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "first_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "last_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "prev_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "next_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  }
}

Properties

Name Type Required Restrictions Description
total integer(int32) false read-only none
count integer(int32) false read-only none
page integer(int32) false read-only none
results [DirectDebitConnectorPaymentResponse] false read-only none
_links SearchNavigationLinks false none Links to navigate through pages

EmbeddedRefunds

{
  "refunds": [
    {
      "refund_id": "act4c33g40j3edfmi8jknab84x",
      "created_date": "2017-01-10T16:52:07.855Z",
      "amount": 120,
      "_links": {
        "self": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        },
        "payment": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        }
      },
      "status": "success"
    }
  ]
}

Properties

Name Type Required Restrictions Description
refunds [Refund] false none none

ErrorResponse

{
  "code": "P0900",
  "description": "Too many requests"
}

An error response

Properties

Name Type Required Restrictions Description
code string false none none
description string false none none

GetPaymentResult

{
  "amount": 1200,
  "description": "Your Service Description",
  "reference": "your-reference",
  "language": "en",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "email": "your email",
  "state": {
    "status": "created",
    "finished": true,
    "message": "User cancelled the payment",
    "code": "P010"
  },
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "payment_provider": "worldpay",
  "created_date": "2016-01-21T17:15:000Z",
  "refund_summary": {
    "status": "available",
    "amount_available": 100,
    "amount_submitted": 0
  },
  "settlement_summary": {
    "capture_submit_time": "2016-01-21T17:15:000Z",
    "captured_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"
  },
  "delayed_capture": false,
  "corporate_card_surcharge": 250,
  "total_amount": 1450,
  "fee": 5,
  "net_amount": 1195,
  "provider_id": "reference-from-payment-gateway",
  "return_url": "http://your.service.domain/your-reference",
  "_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",
      "params": "\"description\":\"This is a value for a parameter called description\"",
      "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",
      "params": "\"description\":\"This is a value for a parameter called description\"",
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST"
    },
    "capture": {
      "type": "application/x-www-form-urlencoded",
      "params": "\"description\":\"This is a value for a parameter called description\"",
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST"
    }
  },
  "card_brand": "Visa"
}

Properties

Name Type Required Restrictions Description
amount integer(int64) false none none
description string false none none
reference string false none none
language string false none none
metadata object false none none
» additionalProperties string false none none
email string false none none
state PaymentState false none A structure representing the current state of the payment in its lifecycle.
payment_id string false read-only none
payment_provider string false read-only none
created_date string false read-only none
refund_summary RefundSummary false none A structure representing the refunds availability
settlement_summary SettlementSummary false none A structure representing information about a settlement
card_details CardDetails false none A structure representing the payment card
delayed_capture boolean false read-only delayed capture flag
corporate_card_surcharge integer(int64) false read-only none
total_amount integer(int64) false read-only none
fee integer(int64) false read-only processing fee taken by the GOV.UK Pay platform, in pence. Only available depending on payment service provider
net_amount integer(int64) false read-only amount including all surcharges and less all fees, in pence. Only available depending on payment service provider
provider_id string false read-only none
return_url string false read-only none
_links PaymentLinks false none links for payment
card_brand string false read-only Card Brand

Enumerated Values

Property Value
language en
language cy

{
  "href": "https://an.example.link/from/payment/platform",
  "method": "GET"
}

A link related to a payment

Properties

Name Type Required Restrictions Description
href string false read-only none
method string false read-only none

MandateError

{
  "field": "return_url",
  "code": "P0102",
  "description": "Invalid attribute value: return_url. Must be a valid url."
}

A Mandate Error response

Properties

Name Type Required Restrictions Description
field string false none none
code string false none none
description string false none none

{
  "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",
    "params": "\"description\":\"This is a value for a parameter called description\"",
    "href": "https://an.example.link/from/payment/platform",
    "method": "POST"
  },
  "payments": {
    "href": "https://an.example.link/from/payment/platform",
    "method": "GET"
  }
}

payment, events, self and next links of a Mandate

Properties

Name Type Required Restrictions Description
self Link false none self
next_url Link false none next_url
next_url_post PostLink false none next_url_post
payments Link false none payments

MandateResponse

{
  "mandate_id": "jhjcvaiqlediuhh23d89hd3",
  "provider_id": "jhjcvaiqlediuhh23d89hd3",
  "reference": "jhjcvaiqlediuhh23d89hd3",
  "return_url": "https://service-name.gov.uk/transactions/12345",
  "state": {
    "status": "string",
    "details": "string"
  },
  "_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",
      "params": "\"description\":\"This is a value for a parameter called description\"",
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST"
    },
    "payments": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "bank_statement_reference": "string",
  "created_date": "string",
  "description": "string",
  "payment_provider": "string",
  "payer": {
    "name": "string",
    "email": "string"
  }
}

Properties

Name Type Required Restrictions Description
mandate_id string false read-only mandate id
provider_id string false read-only provider id
reference string false read-only service reference
return_url string false read-only service return url
state MandateStatus false none mandate state
_links MandateLinks false none links
bank_statement_reference string false read-only This value comes from GoCardless when a mandate has been created.
created_date string false read-only mandate created date
description string false read-only description
payment_provider string false read-only payment_provider
payer Payer false none payer

MandateStatus

{
  "status": "string",
  "details": "string"
}

Properties

Name Type Required Restrictions Description
status string false none none
details string false none none

Payer

{
  "name": "string",
  "email": "string"
}

Properties

Name Type Required Restrictions Description
name string false read-only none
email string false read-only none

PaymentDetailForSearch

{
  "amount": 1200,
  "description": "Your Service Description",
  "reference": "your-reference",
  "language": "en",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "email": "your email",
  "state": {
    "status": "created",
    "finished": true,
    "message": "User cancelled the payment",
    "code": "P010"
  },
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "payment_provider": "worldpay",
  "created_date": "2016-01-21T17:15:000Z",
  "refund_summary": {
    "status": "available",
    "amount_available": 100,
    "amount_submitted": 0
  },
  "settlement_summary": {
    "capture_submit_time": "2016-01-21T17:15:000Z",
    "captured_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"
  },
  "delayed_capture": false,
  "corporate_card_surcharge": 250,
  "total_amount": 1450,
  "fee": 5,
  "net_amount": 1195,
  "provider_id": "reference-from-payment-gateway",
  "return_url": "http://your.service.domain/your-reference",
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "cancel": {
      "type": "application/x-www-form-urlencoded",
      "params": "\"description\":\"This is a value for a parameter called description\"",
      "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"
    },
    "capture": {
      "type": "application/x-www-form-urlencoded",
      "params": "\"description\":\"This is a value for a parameter called description\"",
      "href": "https://an.example.link/from/payment/platform",
      "method": "POST"
    }
  },
  "card_brand": "Visa"
}

Properties

Name Type Required Restrictions Description
amount integer(int64) false none none
description string false none none
reference string false none none
language string false none none
metadata object false none none
» additionalProperties string false none none
email string false none none
state PaymentState false none A structure representing the current state of the payment in its lifecycle.
payment_id string false read-only none
payment_provider string false read-only none
created_date string false read-only none
refund_summary RefundSummary false none A structure representing the refunds availability
settlement_summary SettlementSummary false none A structure representing information about a settlement
card_details CardDetails false none A structure representing the payment card
delayed_capture boolean false read-only delayed capture flag
corporate_card_surcharge integer(int64) false read-only none
total_amount integer(int64) false read-only none
fee integer(int64) false read-only processing fee taken by the GOV.UK Pay platform, in pence. Only available depending on payment service provider
net_amount integer(int64) false read-only amount including all surcharges and less all fees, in pence. Only available depending on payment service provider
provider_id string false read-only none
return_url string false read-only none
_links PaymentLinksForSearch false none links for search payment resource
card_brand string false read-only Card Brand

Enumerated Values

Property Value
language en
language cy

PaymentError

{
  "field": "amount",
  "code": "P0102",
  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000"
}

A Payment Error response

Properties

Name Type Required Restrictions Description
field string false none none
code string false none none
description string false none none

PaymentEvent

{
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "state": {
    "status": "created",
    "finished": true,
    "message": "User cancelled the payment",
    "code": "P010"
  },
  "updated": "2017-01-10T16:44:48.646Z",
  "_links": {
    "payment_url": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  }
}

A List of Payment Events information

Properties

Name Type Required Restrictions Description
payment_id string false read-only none
state PaymentState false none state
updated string false read-only updated
_links PaymentEventLink false none Resource link for a payment of a payment event

{
  "payment_url": {
    "href": "https://an.example.link/from/payment/platform",
    "method": "GET"
  }
}

Resource link for a payment of a payment event

Properties

Name Type Required Restrictions Description
payment_url Link false none payment_url

PaymentEvents

{
  "events": [
    {
      "payment_id": "hu20sqlact5260q2nanm0q8u93",
      "state": {
        "status": "created",
        "finished": true,
        "message": "User cancelled the payment",
        "code": "P010"
      },
      "updated": "2017-01-10T16:44:48.646Z",
      "_links": {
        "payment_url": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        }
      }
    }
  ],
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  }
}

A List of Payment Events information

Properties

Name Type Required Restrictions Description
events [PaymentEvent] false none [A List of Payment Events information]
payment_id string false read-only none
_links PaymentLinksForEvents false none links for events resource

{
  "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",
    "params": "\"description\":\"This is a value for a parameter called description\"",
    "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",
    "params": "\"description\":\"This is a value for a parameter called description\"",
    "href": "https://an.example.link/from/payment/platform",
    "method": "POST"
  },
  "capture": {
    "type": "application/x-www-form-urlencoded",
    "params": "\"description\":\"This is a value for a parameter called description\"",
    "href": "https://an.example.link/from/payment/platform",
    "method": "POST"
  }
}

links for payment

Properties

Name Type Required Restrictions Description
self Link false none self
next_url Link false none next_url
next_url_post PostLink false none next_url_post
events Link false none events
refunds Link false none refunds
cancel PostLink false none cancel
capture PostLink false none capture

PaymentLinksForEvents

{
  "self": {
    "href": "https://an.example.link/from/payment/platform",
    "method": "GET"
  }
}

links for events resource

Properties

Name Type Required Restrictions Description
self Link false none self

PaymentLinksForSearch

{
  "self": {
    "href": "https://an.example.link/from/payment/platform",
    "method": "GET"
  },
  "cancel": {
    "type": "application/x-www-form-urlencoded",
    "params": "\"description\":\"This is a value for a parameter called description\"",
    "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"
  },
  "capture": {
    "type": "application/x-www-form-urlencoded",
    "params": "\"description\":\"This is a value for a parameter called description\"",
    "href": "https://an.example.link/from/payment/platform",
    "method": "POST"
  }
}

links for search payment resource

Properties

Name Type Required Restrictions Description
self Link false none self
cancel PostLink false none cancel
events Link false none events
refunds Link false none refunds
capture PostLink false none capture

PaymentRefundRequest

{
  "amount": 150000,
  "refund_amount_available": 200000
}

The Payment Refund Request Payload

Properties

Name Type Required Restrictions Description
amount integer(int32) true none Amount in pence. Can't be more than the available amount for refunds
refund_amount_available integer(int32) false read-only Amount in pence. Total amount still available before issuing the refund

PaymentSearchResults

{
  "total": 100,
  "count": 20,
  "page": 1,
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "first_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "last_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "prev_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "next_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "results": [
    {
      "amount": 1200,
      "description": "Your Service Description",
      "reference": "your-reference",
      "language": "en",
      "metadata": {
        "property1": "string",
        "property2": "string"
      },
      "email": "your email",
      "state": {
        "status": "created",
        "finished": true,
        "message": "User cancelled the payment",
        "code": "P010"
      },
      "payment_id": "hu20sqlact5260q2nanm0q8u93",
      "payment_provider": "worldpay",
      "created_date": "2016-01-21T17:15:000Z",
      "refund_summary": {
        "status": "available",
        "amount_available": 100,
        "amount_submitted": 0
      },
      "settlement_summary": {
        "capture_submit_time": "2016-01-21T17:15:000Z",
        "captured_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"
      },
      "delayed_capture": false,
      "corporate_card_surcharge": 250,
      "total_amount": 1450,
      "fee": 5,
      "net_amount": 1195,
      "provider_id": "reference-from-payment-gateway",
      "return_url": "http://your.service.domain/your-reference",
      "_links": {
        "self": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        },
        "cancel": {
          "type": "application/x-www-form-urlencoded",
          "params": "\"description\":\"This is a value for a parameter called description\"",
          "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"
        },
        "capture": {
          "type": "application/x-www-form-urlencoded",
          "params": "\"description\":\"This is a value for a parameter called description\"",
          "href": "https://an.example.link/from/payment/platform",
          "method": "POST"
        }
      },
      "card_brand": "Visa"
    }
  ]
}

Properties

Name Type Required Restrictions Description
total integer(int32) false none none
count integer(int32) false none none
page integer(int32) false none none
_links SearchNavigationLinks false none Links to navigate through pages
results [PaymentDetailForSearch] false none none

PaymentState

{
  "status": "created",
  "finished": true,
  "message": "User cancelled the payment",
  "code": "P010"
}

A structure representing the current state of the payment in its lifecycle.

Properties

Name Type Required Restrictions Description
status string false read-only Current progress of the payment in its lifecycle
finished boolean false read-only Whether the payment has finished
message string false read-only What went wrong with the Payment if it finished with an error - English message
code string false read-only What went wrong with the Payment if it finished with an error - error code

{
  "type": "application/x-www-form-urlencoded",
  "params": "\"description\":\"This is a value for a parameter called description\"",
  "href": "https://an.example.link/from/payment/platform",
  "method": "POST"
}

A POST link related to a payment

Properties

Name Type Required Restrictions Description
type string false none none
params object false none none
» additionalProperties object false none none
href string false read-only none
method string false read-only none

PrefilledCardholderDetails

{
  "cardholder_name": "J. Bogs",
  "billing_address": {
    "line1": "address line 1",
    "line2": "address line 2",
    "postcode": "AB1 2CD",
    "city": "address city",
    "country": "GB"
  }
}

Properties

Name Type Required Restrictions Description
cardholder_name string false none prefilled cardholder name
billing_address Address false none prefilled billing address

Refund

{
  "refund_id": "act4c33g40j3edfmi8jknab84x",
  "created_date": "2017-01-10T16:52:07.855Z",
  "amount": 120,
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "payment": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "status": "success"
}

Properties

Name Type Required Restrictions Description
refund_id string false read-only none
created_date string false read-only none
amount integer(int64) false read-only none
_links RefundLinksForSearch false none links for search refunds resource
status string false read-only none

Enumerated Values

Property Value
status submitted
status success
status error

RefundDetailForSearch

{
  "refund_id": "act4c33g40j3edfmi8jknab84x",
  "created_date": "2017-01-10T16:52:07.855Z",
  "amount": 120,
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "payment": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "status": "success"
}

Properties

Name Type Required Restrictions Description
refund_id string false read-only none
created_date string false read-only none
amount integer(int64) false read-only none
_links RefundLinksForSearch false none links for search refunds resource
status string false read-only none

Enumerated Values

Property Value
status submitted
status success
status error

RefundError

{
  "field": "amount_submitted",
  "code": "P0102",
  "description": "Invalid attribute value: amountSubmitted. Must be less than or equal to 10000000"
}

A Refund Error response

Properties

Name Type Required Restrictions Description
field string false none none
code string false none none
description string false none none

RefundForSearchResult

{
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "payment": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "_embedded": {
    "refunds": [
      {
        "refund_id": "act4c33g40j3edfmi8jknab84x",
        "created_date": "2017-01-10T16:52:07.855Z",
        "amount": 120,
        "_links": {
          "self": {
            "href": "https://an.example.link/from/payment/platform",
            "method": "GET"
          },
          "payment": {
            "href": "https://an.example.link/from/payment/platform",
            "method": "GET"
          }
        },
        "status": "success"
      }
    ]
  }
}

Properties

Name Type Required Restrictions Description
payment_id string false none none
_links RefundLinksForSearch false none links for search refunds resource
_embedded EmbeddedRefunds false none none

RefundLinksForSearch

{
  "self": {
    "href": "https://an.example.link/from/payment/platform",
    "method": "GET"
  },
  "payment": {
    "href": "https://an.example.link/from/payment/platform",
    "method": "GET"
  }
}

links for search refunds resource

Properties

Name Type Required Restrictions Description
self Link false none self
payment Link false none payment

RefundSearchResults

{
  "total": 100,
  "count": 20,
  "page": 1,
  "results": [
    {
      "refund_id": "act4c33g40j3edfmi8jknab84x",
      "created_date": "2017-01-10T16:52:07.855Z",
      "amount": 120,
      "_links": {
        "self": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        },
        "payment": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        }
      },
      "status": "success"
    }
  ],
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "first_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "last_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "prev_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "next_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  }
}

Properties

Name Type Required Restrictions Description
total integer(int32) false none none
count integer(int32) false none none
page integer(int32) false none none
results [RefundDetailForSearch] false none none
_links SearchNavigationLinks false none Links to navigate through pages

RefundSummary

{
  "status": "available",
  "amount_available": 100,
  "amount_submitted": 0
}

A structure representing the refunds availability

Properties

Name Type Required Restrictions Description
status string false none Availability status of the refund
amount_available integer(int64) false read-only Amount available for refund in pence
amount_submitted integer(int64) false read-only Amount submitted for refunds on this Payment in pence

SearchMandateResponse

{
  "total": 0,
  "count": 0,
  "page": 0,
  "results": [
    {
      "mandate_id": "jhjcvaiqlediuhh23d89hd3",
      "provider_id": "jhjcvaiqlediuhh23d89hd3",
      "reference": "jhjcvaiqlediuhh23d89hd3",
      "return_url": "https://service-name.gov.uk/transactions/12345",
      "state": {
        "status": "string",
        "details": "string"
      },
      "_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",
          "params": "\"description\":\"This is a value for a parameter called description\"",
          "href": "https://an.example.link/from/payment/platform",
          "method": "POST"
        },
        "payments": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        }
      },
      "bank_statement_reference": "string",
      "created_date": "string",
      "description": "string",
      "payment_provider": "string",
      "payer": {
        "name": "string",
        "email": "string"
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "first_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "last_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "prev_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "next_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  }
}

Properties

Name Type Required Restrictions Description
total integer(int32) false read-only none
count integer(int32) false read-only none
page integer(int32) false read-only none
results [MandateResponse] false read-only none
_links SearchNavigationLinks false none Links to navigate through pages

{
  "self": {
    "href": "https://an.example.link/from/payment/platform",
    "method": "GET"
  },
  "first_page": {
    "href": "https://an.example.link/from/payment/platform",
    "method": "GET"
  },
  "last_page": {
    "href": "https://an.example.link/from/payment/platform",
    "method": "GET"
  },
  "prev_page": {
    "href": "https://an.example.link/from/payment/platform",
    "method": "GET"
  },
  "next_page": {
    "href": "https://an.example.link/from/payment/platform",
    "method": "GET"
  }
}

Links to navigate through pages

Properties

Name Type Required Restrictions Description
self Link false none A link related to a payment
first_page Link false none A link related to a payment
last_page Link false none A link related to a payment
prev_page Link false none A link related to a payment
next_page Link false none A link related to a payment

SettlementSummary

{
  "capture_submit_time": "2016-01-21T17:15:000Z",
  "captured_date": "2016-01-21"
}

A structure representing information about a settlement

Properties

Name Type Required Restrictions Description
capture_submit_time string false read-only Date and time capture request has been submitted (may be null if capture request was not immediately acknowledged by payment gateway)
captured_date string false read-only Date of the capture event