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

GOV.UK Pay API v1.0.2

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

Default

searchPayments

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
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,
      "state": {
        "status": "created",
        "finished": true,
        "message": "User cancelled the payment",
        "code": "P010"
      },
      "description": "Your Service Description",
      "reference": "your-reference",
      "email": "your email",
      "language": "en",
      "payment_id": "hu20sqlact5260q2nanm0q8u93",
      "payment_provider": "worldpay",
      "return_url": "http://your.service.domain/your-reference",
      "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": "12/20",
        "billing_address": {
          "line1": "address line 1",
          "line2": "address line 2",
          "postcode": "AB1 2CD",
          "city": "address city",
          "country": "GB"
        },
        "card_brand": "Visa"
      },
      "delayed_capture": false,
      "corporate_card_surcharge": 250,
      "total_amount": 1450,
      "provider_id": "reference-from-payment-gateway",
      "_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

newPayment

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 = '{
  "amount": 12000,
  "reference": "12345",
  "return_url": "https://service-name.gov.uk/transactions/12345",
  "description": "New passport application",
  "language": "en"
}';
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

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

Parameters

Name In Type Required Description
body body CreatePaymentRequest 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",
  "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"
  }
}

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

getPayment

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,
  "state": {
    "status": "created",
    "finished": true,
    "message": "User cancelled the payment",
    "code": "P010"
  },
  "description": "Your Service Description",
  "reference": "your-reference",
  "email": "your email",
  "language": "en",
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "payment_provider": "worldpay",
  "return_url": "http://your.service.domain/your-reference",
  "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": "12/20",
    "billing_address": {
      "line1": "address line 1",
      "line2": "address line 2",
      "postcode": "AB1 2CD",
      "city": "address city",
      "country": "GB"
    },
    "card_brand": "Visa"
  },
  "delayed_capture": false,
  "corporate_card_surcharge": 250,
  "total_amount": 1450,
  "provider_id": "reference-from-payment-gateway",
  "_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

cancelPayment

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

capturePayment

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

getPaymentEvents

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

refunds

getRefunds

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

submitRefund

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

getRefundById

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

searchRefunds

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": "12/20",
  "billing_address": {
    "line1": "address line 1",
    "line2": "address line 2",
    "postcode": "AB1 2CD",
    "city": "address city",
    "country": "GB"
  },
  "card_brand": "Visa"
}

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 none
billing_address Address false none A structure representing the billing address of a card
card_brand string false read-only none

CreatePaymentRequest

{
  "amount": 12000,
  "reference": "12345",
  "return_url": "https://service-name.gov.uk/transactions/12345",
  "description": "New passport application",
  "language": "en",
  "delayed_capture": false
}

Properties

Name Type Required Restrictions Description
amount integer(int32) true none amount in pence
reference string true none payment reference
return_url string true none service return url
description string true none payment description
language string false none ISO-639-1 Alpha-2 code of a supported language to use on the payment pages
delayed_capture boolean false read-only delayed capture flag

Enumerated Values

Property Value
language en
language cy

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

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
refund_summary RefundSummary false none A structure representing the refunds availability
settlement_summary SettlementSummary false none A structure representing information about a settlement

Enumerated Values

Property Value
language ENGLISH
language WELSH

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,
  "state": {
    "status": "created",
    "finished": true,
    "message": "User cancelled the payment",
    "code": "P010"
  },
  "description": "Your Service Description",
  "reference": "your-reference",
  "email": "your email",
  "language": "en",
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "payment_provider": "worldpay",
  "return_url": "http://your.service.domain/your-reference",
  "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": "12/20",
    "billing_address": {
      "line1": "address line 1",
      "line2": "address line 2",
      "postcode": "AB1 2CD",
      "city": "address city",
      "country": "GB"
    },
    "card_brand": "Visa"
  },
  "delayed_capture": false,
  "corporate_card_surcharge": 250,
  "total_amount": 1450,
  "provider_id": "reference-from-payment-gateway",
  "_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
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
email string false none none
language string false none none
payment_id string false read-only none
payment_provider string false read-only none
return_url 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
provider_id 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

PaymentDetailForSearch

{
  "amount": 1200,
  "state": {
    "status": "created",
    "finished": true,
    "message": "User cancelled the payment",
    "code": "P010"
  },
  "description": "Your Service Description",
  "reference": "your-reference",
  "email": "your email",
  "language": "en",
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "payment_provider": "worldpay",
  "return_url": "http://your.service.domain/your-reference",
  "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": "12/20",
    "billing_address": {
      "line1": "address line 1",
      "line2": "address line 2",
      "postcode": "AB1 2CD",
      "city": "address city",
      "country": "GB"
    },
    "card_brand": "Visa"
  },
  "delayed_capture": false,
  "corporate_card_surcharge": 250,
  "total_amount": 1450,
  "provider_id": "reference-from-payment-gateway",
  "_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
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
email string false none none
language string false none none
payment_id string false read-only none
payment_provider string false read-only none
return_url 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
provider_id 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,
      "state": {
        "status": "created",
        "finished": true,
        "message": "User cancelled the payment",
        "code": "P010"
      },
      "description": "Your Service Description",
      "reference": "your-reference",
      "email": "your email",
      "language": "en",
      "payment_id": "hu20sqlact5260q2nanm0q8u93",
      "payment_provider": "worldpay",
      "return_url": "http://your.service.domain/your-reference",
      "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": "12/20",
        "billing_address": {
          "line1": "address line 1",
          "line2": "address line 2",
          "postcode": "AB1 2CD",
          "city": "address city",
          "country": "GB"
        },
        "card_brand": "Visa"
      },
      "delayed_capture": false,
      "corporate_card_surcharge": 250,
      "total_amount": 1450,
      "provider_id": "reference-from-payment-gateway",
      "_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

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

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