GOV.UK Pay API
GOV
COMMUNITYAPI KEY0 INSTALLS
OpenAPI Specificationv3.0
{
"swagger": "2.0",
"schemes": [
"https"
],
"host": "publicapi.payments.service.gov.uk",
"info": {
"contact": {
"x-twitter": "GOVUK"
},
"description": "GOV.UK Pay API (This version is no longer maintained. See openapi/publicapi_spec.json for latest API specification)",
"title": "GOV.UK Pay API",
"version": "1.0.3",
"x-apisguru-categories": [
"financial"
],
"x-logo": {
"url": "https://api.apis.guru/v2/cache/logo/https_twitter.com_GOVUK_profile_image.jpeg"
},
"x-origin": [
{
"format": "swagger",
"url": "https://raw.githubusercontent.com/alphagov/pay-publicapi/master/swagger/swagger.json",
"version": "2.0"
}
],
"x-providerName": "payments.service.gov.uk",
"x-serviceName": "payments"
},
"securityDefinitions": {
"Authorization": {
"in": "header",
"name": "Authorization",
"type": "apiKey"
}
},
"tags": [
{
"name": "Card payments"
},
{
"name": "Refunding card payments"
}
],
"paths": {
"/v1/payments": {
"get": {
"description": "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'",
"operationId": "Search payments",
"parameters": [
{
"description": "Your payment reference to search (exact match, case insensitive)",
"in": "query",
"name": "reference",
"required": false,
"type": "string"
},
{
"description": "The user email used in the payment to be searched",
"in": "query",
"name": "email",
"required": false,
"type": "string"
},
{
"description": "State of payments to be searched. Example=success",
"enum": [
"created",
"started",
"submitted",
"success",
"failed",
"cancelled",
"error"
],
"in": "query",
"name": "state",
"required": false,
"type": "string"
},
{
"description": "Card brand used for payment. Example=master-card",
"in": "query",
"name": "card_brand",
"required": false,
"type": "string"
},
{
"description": "From date of payments to be searched (this date is inclusive). Example=2015-08-13T12:35:00Z",
"in": "query",
"name": "from_date",
"required": false,
"type": "string"
},
{
"description": "To date of payments to be searched (this date is exclusive). Example=2015-08-14T12:35:00Z",
"in": "query",
"name": "to_date",
"required": false,
"type": "string"
},
{
"description": "Page number requested for the search, should be a positive integer (optional, defaults to 1)",
"in": "query",
"name": "page",
"required": false,
"type": "string"
},
{
"description": "Number of results to be shown per page, should be a positive integer (optional, defaults to 500, max 500)",
"in": "query",
"name": "display_size",
"required": false,
"type": "string"
},
{
"description": "Name on card used to make payment",
"in": "query",
"name": "cardholder_name",
"required": false,
"type": "string"
},
{
"description": "First six digits of the card used to make payment",
"in": "query",
"name": "first_digits_card_number",
"required": false,
"type": "string"
},
{
"description": "Last four digits of the card used to make payment",
"in": "query",
"name": "last_digits_card_number",
"required": false,
"type": "string"
},
{
"description": "From settled date of payment to be searched (this date is inclusive). Example=2015-08-13",
"in": "query",
"name": "from_settled_date",
"required": false,
"type": "string"
},
{
"description": "To settled date of payment to be searched (this date is inclusive). Example=2015-08-14",
"in": "query",
"name": "to_settled_date",
"required": false,
"type": "string"
}
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/PaymentSearchResults"
}
},
"401": {
"description": "Credentials are required to access this resource"
},
"422": {
"description": "Invalid parameters: from_date, to_date, status, display_size. See Public API documentation for the correct data formats",
"schema": {
"$ref": "#/definitions/PaymentError"
}
},
"429": {
"description": "Too many requests",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
},
"500": {
"description": "Downstream system error",
"schema": {
"$ref": "#/definitions/PaymentError"
}
}
},
"security": [
{
"Authorization": []
}
],
"summary": "Search payments",
"tags": [
"Card payments"
]
},
"post": {
"consumes": [
"application/json"
],
"description": "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'",
"operationId": "Create a payment",
"parameters": [
{
"description": "requestPayload",
"in": "body",
"name": "body",
"required": true,
"schema": {
"$ref": "#/definitions/CreateCardPaymentRequest"
}
}
],
"produces": [
"application/json"
],
"responses": {
"201": {
"description": "Created",
"schema": {
"$ref": "#/definitions/CreatePaymentResult"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/PaymentError"
}
},
"401": {
"description": "Credentials are required to access this resource"
},
"422": {
"description": "Invalid attribute value: description. Must be less than or equal to 255 characters length",
"schema": {
"$ref": "#/definitions/PaymentError"
}
},
"429": {
"description": "Too many requests",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
},
"500": {
"description": "Downstream system error",
"schema": {
"$ref": "#/definitions/PaymentError"
}
}
},
"security": [
{
"Authorization": []
}
],
"summary": "Create new payment",
"tags": [
"Card payments"
]
}
},
"/v1/payments/{paymentId}": {
"get": {
"description": "Return information about the payment The Authorisation token needs to be specified in the 'authorization' header as 'authorization: Bearer YOUR_API_KEY_HERE'",
"operationId": "Get a payment",
"parameters": [
{
"description": "Payment identifier",
"in": "path",
"name": "paymentId",
"required": true,
"type": "string",
"x-example": "hu20sqlact5260q2nanm0q8u93"
}
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/GetPaymentResult"
}
},
"401": {
"description": "Credentials are required to access this resource"
},
"404": {
"description": "Not found",
"schema": {
"$ref": "#/definitions/PaymentError"
}
},
"429": {
"description": "Too many requests",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
},
"500": {
"description": "Downstream system error",
"schema": {
"$ref": "#/definitions/PaymentError"
}
}
},
"security": [
{
"Authorization": []
}
],
"summary": "Find payment by ID",
"tags": [
"Card payments"
]
}
},
"/v1/payments/{paymentId}/cancel": {
"post": {
"description": "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.",
"operationId": "Cancel a payment",
"parameters": [
{
"description": "Payment identifier",
"in": "path",
"name": "paymentId",
"required": true,
"type": "string",
"x-example": "hu20sqlact5260q2nanm0q8u93"
}
],
"produces": [
"application/json"
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Cancellation of payment failed",
"schema": {
"$ref": "#/definitions/PaymentError"
}
},
"401": {
"description": "Credentials are required to access this resource"
},
"404": {
"description": "Not found",
"schema": {
"$ref": "#/definitions/PaymentError"
}
},
"409": {
"description": "Conflict",
"schema": {
"$ref": "#/definitions/PaymentError"
}
},
"429": {
"description": "Too many requests",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
},
"500": {
"description": "Downstream system error",
"schema": {
"$ref": "#/definitions/PaymentError"
}
}
},
"security": [
{
"Authorization": []
}
],
"summary": "Cancel payment",
"tags": [
"Card payments"
]
}
},
"/v1/payments/{paymentId}/capture": {
"post": {
"description": "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",
"operationId": "Capture a payment",
"parameters": [
{
"description": "Payment identifier",
"in": "path",
"name": "paymentId",
"required": true,
"type": "string",
"x-example": "hu20sqlact5260q2nanm0q8u93"
}
],
"produces": [
"application/json"
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Capture of payment failed",
"schema": {
"$ref": "#/definitions/PaymentError"
}
},
"401": {
"description": "Credentials are required to access this resource"
},
"404": {
"description": "Not found",
"schema": {
"$ref": "#/definitions/PaymentError"
}
},
"409": {
"description": "Conflict",
"schema": {
"$ref": "#/definitions/PaymentError"
}
},
"429": {
"description": "Too many requests",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
},
"500": {
"description": "Downstream system error",
"schema": {
"$ref": "#/definitions/PaymentError"
}
}
},
"security": [
{
"Authorization": []
}
],
"summary": "Capture payment",
"tags": [
"Card payments"
]
}
},
"/v1/payments/{paymentId}/events": {
"get": {
"description": "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'",
"operationId": "Get events for a payment",
"parameters": [
{
"description": "Payment identifier",
"in": "path",
"name": "paymentId",
"required": true,
"type": "string",
"x-example": "hu20sqlact5260q2nanm0q8u93"
}
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/PaymentEvents"
}
},
"401": {
"description": "Credentials are required to access this resource"
},
"404": {
"description": "Not found",
"schema": {
"$ref": "#/definitions/PaymentError"
}
},
"429": {
"description": "Too many requests",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
},
"500": {
"description": "Downstream system error",
"schema": {
"$ref": "#/definitions/PaymentError"
}
}
},
"security": [
{
"Authorization": []
}
],
"summary": "Return payment events by ID",
"tags": [
"Card payments"
]
}
},
"/v1/payments/{paymentId}/refunds": {
"get": {
"description": "Return refunds for a payment. The Authorisation token needs to be specified in the 'authorization' header as 'authorization: Bearer YOUR_API_KEY_HERE'",
"operationId": "Get all refunds for a payment",
"parameters": [
{
"in": "path",
"name": "paymentId",
"required": true,
"type": "string"
}
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/RefundForSearchResult"
}
},
"401": {
"description": "Credentials are required to access this resource"
},
"404": {
"description": "Not found",
"schema": {
"$ref": "#/definitions/PaymentError"
}
},
"429": {
"description": "Too many requests",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
},
"500": {
"description": "Downstream system error",
"schema": {
"$ref": "#/definitions/PaymentError"
}
}
},
"security": [
{
"Authorization": []
}
],
"summary": "Get all refunds for a payment",
"tags": [
"Refunding card payments"
]
},
"post": {
"consumes": [
"application/json"
],
"description": "Return issued refund information. The Authorisation token needs to be specified in the 'authorization' header as 'authorization: Bearer YOUR_API_KEY_HERE'",
"operationId": "Submit a refund for a payment",
"parameters": [
{
"description": "paymentId",
"in": "path",
"name": "paymentId",
"required": true,
"type": "string"
},
{
"description": "requestPayload",
"in": "body",
"name": "body",
"required": true,
"schema": {
"$ref": "#/definitions/PaymentRefundRequest"
}
}
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "successful operation",
"schema": {
"$ref": "#/definitions/Refund"
}
},
"202": {
"description": "ACCEPTED"
},
"401": {
"description": "Credentials are required to access this resource"
},
"404": {
"description": "Not found",
"schema": {
"$ref": "#/definitions/PaymentError"
}
},
"412": {
"description": "Refund amount available mismatch"
},
"429": {
"description": "Too many requests",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
},
"500": {
"description": "Downstream system error",
"schema": {
"$ref": "#/definitions/PaymentError"
}
}
},
"security": [
{
"Authorization": []
}
],
"summary": "Submit a refund for a payment",
"tags": [
"Refunding card payments"
]
}
},
"/v1/payments/{paymentId}/refunds/{refundId}": {
"get": {
"description": "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'",
"operationId": "Get a payment refund",
"parameters": [
{
"in": "path",
"name": "paymentId",
"required": true,
"type": "string"
},
{
"in": "path",
"name": "refundId",
"required": true,
"type": "string"
}
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/Refund"
}
},
"401": {
"description": "Credentials are required to access this resource"
},
"404": {
"description": "Not found",
"schema": {
"$ref": "#/definitions/PaymentError"
}
},
"429": {
"description": "Too many requests",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
},
"500": {
"description": "Downstream system error",
"schema": {
"$ref": "#/definitions/PaymentError"
}
}
},
"security": [
{
"Authorization": []
}
],
"summary": "Find payment refund by ID",
"tags": [
"Refunding card payments"
]
}
},
"/v1/refunds": {
"get": {
"description": "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'",
"operationId": "Search refunds",
"parameters": [
{
"description": "From date of refunds to be searched (this date is inclusive). Example=2015-08-13T12:35:00Z",
"in": "query",
"name": "from_date",
"required": false,
"type": "string"
},
{
"description": "To date of refunds to be searched (this date is exclusive). Example=2015-08-14T12:35:00Z",
"in": "query",
"name": "to_date",
"required": false,
"type": "string"
},
{
"description": "From settled date of refund to be searched (this date is inclusive). Example=2015-08-13",
"in": "query",
"name": "from_settled_date",
"required": false,
"type": "string"
},
{
"description": "To settled date of refund to be searched (this date is inclusive). Example=2015-08-13",
"in": "query",
"name": "to_settled_date",
"required": false,
"type": "string"
},
{
"description": "Page number requested for the search, should be a positive integer (optional, defaults to 1)",
"in": "query",
"name": "page",
"required": false,
"type": "string"
},
{
"description": "Number of results to be shown per page, should be a positive integer (optional, defaults to 500, max 500)",
"in": "query",
"name": "display_size",
"required": false,
"type": "string"
}
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/RefundSearchResults"
}
},
"401": {
"description": "Credentials are required to access this resource"
},
"422": {
"description": "Invalid parameters. See Public API documentation for the correct data formats",
"schema": {
"$ref": "#/definitions/RefundError"
}
},
"500": {
"description": "Downstream system error",
"schema": {
"$ref": "#/definitions/RefundError"
}
}
},
"security": [
{
"Authorization": []
}
],
"summary": "Search refunds",
"tags": [
"Refunding card payments"
]
}
}
},
"definitions": {
"Address": {
"description": "A structure representing the billing address of a card",
"properties": {
"city": {
"example": "address city",
"maxLength": 255,
"minLength": 0,
"readOnly": true,
"type": "string"
},
"country": {
"example": "GB",
"readOnly": true,
"type": "string"
},
"line1": {
"example": "address line 1",
"maxLength": 255,
"minLength": 0,
"readOnly": true,
"type": "string"
},
"line2": {
"example": "address line 2",
"maxLength": 255,
"minLength": 0,
"readOnly": true,
"type": "string"
},
"postcode": {
"example": "AB1 2CD",
"maxLength": 25,
"minLength": 0,
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"CardDetails": {
"description": "A structure representing the payment card",
"properties": {
"billing_address": {
"$ref": "#/definitions/Address",
"readOnly": true
},
"card_brand": {
"example": "Visa",
"readOnly": true,
"type": "string"
},
"card_type": {
"description": "The card type, `debit` or `credit` or `null` if not able to determine",
"enum": [
"debit",
"credit",
"null"
],
"example": "debit",
"readOnly": true,
"type": "string"
},
"cardholder_name": {
"example": "Mr. Card holder",
"readOnly": true,
"type": "string"
},
"expiry_date": {
"description": "The expiry date of the card in MM/yy format",
"example": "04/24",
"readOnly": true,
"type": "string"
},
"first_digits_card_number": {
"example": "123456",
"readOnly": true,
"type": "string"
},
"last_digits_card_number": {
"example": "1234",
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"CreateCardPaymentRequest": {
"description": "The Payment Request Payload",
"properties": {
"amount": {
"description": "amount in pence",
"example": 12000,
"format": "int32",
"maximum": 10000000,
"minimum": 0,
"readOnly": true,
"type": "integer"
},
"delayed_capture": {
"description": "delayed capture flag",
"example": false,
"readOnly": true,
"type": "boolean"
},
"description": {
"description": "payment description",
"example": "New passport application",
"maxLength": 255,
"minLength": 0,
"readOnly": true,
"type": "string"
},
"email": {
"description": "email",
"example": "Joe.Bogs@example.org",
"readOnly": true,
"type": "string"
},
"language": {
"description": "ISO-639-1 Alpha-2 code of a supported language to use on the payment pages",
"enum": [
"en",
"cy"
],
"example": "en",
"readOnly": true,
"type": "string"
},
"metadata": {
"additionalProperties": {
"type": "object"
},
"description": "Additional metadata - up to 10 name/value pairs - on the payment. Each key must be between 1 and 30 characters long. The value, if a string, must be no greater than 50 characters long. Other permissible value types: boolean, number.",
"example": "{\"ledger_code\":\"123\", \"reconciled\": true}",
"readOnly": true,
"type": "object"
},
"moto": {
"description": "Mail Order / Telephone Order (MOTO) payment flag",
"example": false,
"readOnly": true,
"type": "boolean"
},
"prefilled_cardholder_details": {
"$ref": "#/definitions/PrefilledCardholderDetails",
"description": "prefilled_cardholder_details",
"readOnly": true
},
"reference": {
"description": "payment reference",
"example": "12345",
"maxLength": 255,
"minLength": 0,
"readOnly": true,
"type": "string"
},
"return_url": {
"description": "service return url",
"example": "https://service-name.gov.uk/transactions/12345",
"maxLength": 2000,
"minLength": 0,
"readOnly": true,
"type": "string"
}
},
"required": [
"amount",
"description",
"reference",
"return_url"
],
"type": "object"
},
"CreatePaymentResult": {
"properties": {
"_links": {
"$ref": "#/definitions/PaymentLinks",
"description": "API endpoints related to the payment."
},
"amount": {
"description": "The amount in pence.",
"example": 1200,
"format": "int64",
"type": "integer"
},
"card_details": {
"$ref": "#/definitions/CardDetails"
},
"created_date": {
"description": "The date you created the payment.",
"example": "2016-01-21T17:15:00Z",
"type": "string"
},
"delayed_capture": {
"description": "Whether to [delay capturing](https://docs.payments.service.gov.uk/optional_features/delayed_capture/) this payment.",
"example": false,
"type": "boolean"
},
"description": {
"description": "The human-readable description you gave the payment.",
"example": "New passport application",
"type": "string"
},
"email": {
"description": "The email address of your user.",
"example": "citizen@example.org",
"type": "string"
},
"language": {
"description": "Which language your users will see on the payment pages when they make a payment.",
"enum": [
"en",
"cy"
],
"example": "en",
"type": "string"
},
"metadata": {
"additionalProperties": {
"type": "string"
},
"description": "[Custom metadata](https://docs.payments.service.gov.uk/optional_features/custom_metadata/) you added to the payment.",
"type": "object"
},
"moto": {
"description": "Mail Order / Telephone Order (MOTO) payment flag.",
"example": false,
"type": "boolean"
},
"payment_id": {
"description": "The unique identifier of the payment.",
"example": "hu20sqlact5260q2nanm0q8u93",
"type": "string"
},
"payment_provider": {
"example": "worldpay",
"type": "string"
},
"provider_id": {
"description": "The reference number the payment gateway associated with the payment.",
"example": "null",
"type": "string"
},
"reference": {
"description": "The reference number you associated with this payment.",
"example": "12345",
"type": "string"
},
"refund_summary": {
"$ref": "#/definitions/RefundSummary"
},
"return_url": {
"description": "An HTTPS URL on your site that your user will be sent back to once they have completed their payment attempt on GOV.UK Pay.",
"example": "https://service-name.gov.uk/transactions/12345",
"type": "string"
},
"settlement_summary": {
"$ref": "#/definitions/PaymentSettlementSummary"
},
"state": {
"$ref": "#/definitions/PaymentState"
}
},
"type": "object"
},
"EmbeddedRefunds": {
"properties": {
"refunds": {
"items": {
"$ref": "#/definitions/Refund"
},
"type": "array"
}
},
"type": "object"
},
"ErrorResponse": {
"description": "An error response",
"properties": {
"code": {
"example": "P0900",
"type": "string"
},
"description": {
"example": "Too many requests",
"type": "string"
}
},
"type": "object"
},
"GetPaymentResult": {
"properties": {
"_links": {
"$ref": "#/definitions/PaymentLinks"
},
"amount": {
"example": 1200,
"format": "int64",
"type": "integer"
},
"card_brand": {
"description": "Card Brand",
"example": "Visa",
"readOnly": true,
"type": "string"
},
"card_details": {
"$ref": "#/definitions/CardDetails",
"readOnly": true
},
"corporate_card_surcharge": {
"example": 250,
"format": "int64",
"readOnly": true,
"type": "integer"
},
"created_date": {
"example": "2016-01-21T17:15:000Z",
"readOnly": true,
"type": "string"
},
"delayed_capture": {
"description": "delayed capture flag",
"example": false,
"readOnly": true,
"type": "boolean"
},
"description": {
"example": "Your Service Description",
"type": "string"
},
"email": {
"example": "your email",
"type": "string"
},
"fee": {
"description": "processing fee taken by the GOV.UK Pay platform, in pence. Only available depending on payment service provider",
"example": 5,
"format": "int64",
"readOnly": true,
"type": "integer"
},
"language": {
"enum": [
"en",
"cy"
],
"example": "en",
"type": "string"
},
"metadata": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"moto": {
"description": "Mail Order / Telephone Order (MOTO) payment flag",
"example": false,
"readOnly": true,
"type": "boolean"
},
"net_amount": {
"description": "amount including all surcharges and less all fees, in pence. Only available depending on payment service provider",
"example": 1195,
"format": "int64",
"readOnly": true,
"type": "integer"
},
"payment_id": {
"example": "hu20sqlact5260q2nanm0q8u93",
"readOnly": true,
"type": "string"
},
"payment_provider": {
"example": "worldpay",
"readOnly": true,
"type": "string"
},
"provider_id": {
"example": "reference-from-payment-gateway",
"readOnly": true,
"type": "string"
},
"reference": {
"example": "your-reference",
"type": "string"
},
"refund_summary": {
"$ref": "#/definitions/RefundSummary",
"readOnly": true
},
"return_url": {
"example": "http://your.service.domain/your-reference",
"readOnly": true,
"type": "string"
},
"settlement_summary": {
"$ref": "#/definitions/PaymentSettlementSummary",
"readOnly": true
},
"state": {
"$ref": "#/definitions/PaymentState"
},
"total_amount": {
"example": 1450,
"format": "int64",
"readOnly": true,
"type": "integer"
}
},
"type": "object"
},
"Link": {
"description": "A link related to a payment",
"properties": {
"href": {
"example": "https://an.example.link/from/payment/platform",
"readOnly": true,
"type": "string"
},
"method": {
"example": "GET",
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"Payer": {
"properties": {
"email": {
"readOnly": true,
"type": "string"
},
"name": {
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"PaymentDetailForSearch": {
"properties": {
"_links": {
"$ref": "#/definitions/PaymentLinksForSearch",
"readOnly": true
},
"amount": {
"example": 1200,
"format": "int64",
"type": "integer"
},
"card_brand": {
"description": "Card Brand",
"example": "Visa",
"readOnly": true,
"type": "string"
},
"card_details": {
"$ref": "#/definitions/CardDetails",
"readOnly": true
},
"corporate_card_surcharge": {
"example": 250,
"format": "int64",
"readOnly": true,
"type": "integer"
},
"created_date": {
"example": "2016-01-21T17:15:000Z",
"readOnly": true,
"type": "string"
},
"delayed_capture": {
"description": "delayed capture flag",
"example": false,
"readOnly": true,
"type": "boolean"
},
"description": {
"example": "Your Service Description",
"type": "string"
},
"email": {
"example": "your email",
"type": "string"
},
"fee": {
"description": "processing fee taken by the GOV.UK Pay platform, in pence. Only available depending on payment service provider",
"example": 5,
"format": "int64",
"readOnly": true,
"type": "integer"
},
"language": {
"enum": [
"en",
"cy"
],
"example": "en",
"type": "string"
},
"metadata": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"moto": {
"description": "Mail Order / Telephone Order (MOTO) payment flag",
"example": false,
"readOnly": true,
"type": "boolean"
},
"net_amount": {
"description": "amount including all surcharges and less all fees, in pence. Only available depending on payment service provider",
"example": 1195,
"format": "int64",
"readOnly": true,
"type": "integer"
},
"payment_id": {
"example": "hu20sqlact5260q2nanm0q8u93",
"readOnly": true,
"type": "string"
},
"payment_provider": {
"example": "worldpay",
"readOnly": true,
"type": "string"
},
"provider_id": {
"example": "reference-from-payment-gateway",
"readOnly": true,
"type": "string"
},
"reference": {
"example": "your-reference",
"type": "string"
},
"refund_summary": {
"$ref": "#/definitions/RefundSummary",
"readOnly": true
},
"return_url": {
"example": "http://your.service.domain/your-reference",
"readOnly": true,
"type": "string"
},
"settlement_summary": {
"$ref": "#/definitions/PaymentSettlementSummary",
"readOnly": true
},
"state": {
"$ref": "#/definitions/PaymentState"
},
"total_amount": {
"example": 1450,
"format": "int64",
"readOnly": true,
"type": "integer"
}
},
"type": "object"
},
"PaymentError": {
"description": "A Payment Error response",
"properties": {
"code": {
"example": "P0102",
"type": "string"
},
"description": {
"example": "Invalid attribute value: amount. Must be less than or equal to 10000000",
"type": "string"
},
"field": {
"example": "amount",
"type": "string"
}
},
"type": "object"
},
"PaymentEvent": {
"description": "A List of Payment Events information",
"properties": {
"_links": {
"$ref": "#/definitions/PaymentEventLink",
"readOnly": true
},
"payment_id": {
"example": "hu20sqlact5260q2nanm0q8u93",
"readOnly": true,
"type": "string"
},
"state": {
"$ref": "#/definitions/PaymentState",
"description": "state",
"readOnly": true
},
"updated": {
"description": "updated",
"example": "2017-01-10T16:44:48.646Z",
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"PaymentEventLink": {
"description": "Resource link for a payment of a payment event",
"properties": {
"payment_url": {
"$ref": "#/definitions/Link",
"description": "payment_url",
"readOnly": true
}
},
"type": "object"
},
"PaymentEvents": {
"description": "A List of Payment Events information",
"properties": {
"_links": {
"$ref": "#/definitions/PaymentLinksForEvents",
"readOnly": true
},
"events": {
"items": {
"$ref": "#/definitions/PaymentEvent"
},
"type": "array"
},
"payment_id": {
"example": "hu20sqlact5260q2nanm0q8u93",
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"PaymentLinks": {
"description": "links for payment",
"properties": {
"cancel": {
"$ref": "#/definitions/PostLink",
"description": "cancel",
"readOnly": true
},
"capture": {
"$ref": "#/definitions/PostLink",
"description": "capture",
"readOnly": true
},
"events": {
"$ref": "#/definitions/Link",
"description": "events",
"readOnly": true
},
"next_url": {
"$ref": "#/definitions/Link",
"description": "next_url",
"readOnly": true
},
"next_url_post": {
"$ref": "#/definitions/PostLink",
"description": "next_url_post",
"readOnly": true
},
"refunds": {
"$ref": "#/definitions/Link",
"description": "refunds",
"readOnly": true
},
"self": {
"$ref": "#/definitions/Link",
"description": "self",
"readOnly": true
}
},
"type": "object"
},
"PaymentLinksForEvents": {
"description": "links for events resource",
"properties": {
"self": {
"$ref": "#/definitions/Link",
"description": "self",
"readOnly": true
}
},
"type": "object"
},
"PaymentLinksForSearch": {
"description": "links for search payment resource",
"properties": {
"cancel": {
"$ref": "#/definitions/PostLink",
"description": "cancel",
"readOnly": true
},
"capture": {
"$ref": "#/definitions/PostLink",
"description": "capture",
"readOnly": true
},
"events": {
"$ref": "#/definitions/Link",
"description": "events",
"readOnly": true
},
"refunds": {
"$ref": "#/definitions/Link",
"description": "refunds",
"readOnly": true
},
"self": {
"$ref": "#/definitions/Link",
"description": "self",
"readOnly": true
}
},
"type": "object"
},
"PaymentRefundRequest": {
"description": "The Payment Refund Request Payload",
"properties": {
"amount": {
"description": "Amount in pence. Can't be more than the available amount for refunds",
"example": 150000,
"format": "int32",
"maximum": 10000000,
"minimum": 1,
"type": "integer"
},
"refund_amount_available": {
"description": "Amount in pence. Total amount still available before issuing the refund",
"example": 200000,
"format": "int32",
"maximum": 10000000,
"minimum": 1,
"readOnly": true,
"type": "integer"
}
},
"required": [
"amount"
],
"type": "object"
},
"PaymentSearchResults": {
"properties": {
"_links": {
"$ref": "#/definitions/SearchNavigationLinks"
},
"count": {
"example": 20,
"format": "int32",
"type": "integer"
},
"page": {
"example": 1,
"format": "int32",
"type": "integer"
},
"results": {
"items": {
"$ref": "#/definitions/PaymentDetailForSearch"
},
"type": "array"
},
"total": {
"example": 100,
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"PaymentSettlementSummary": {
"description": "A structure representing information about a settlement",
"properties": {
"capture_submit_time": {
"description": "Date and time capture request has been submitted. May be null if capture request was not immediately acknowledged by payment gateway.",
"example": "2016-01-21T17:15:000Z",
"readOnly": true,
"type": "string"
},
"captured_date": {
"description": "Date of the capture event.",
"example": "2016-01-21",
"readOnly": true,
"type": "string"
},
"settled_date": {
"description": "The date that the transaction was paid into the service's account.",
"example": "2016-01-21",
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"PaymentState": {
"description": "A structure representing the current state of the payment in its lifecycle.",
"properties": {
"code": {
"description": "What went wrong with the Payment if it finished with an error - error code",
"example": "P010",
"readOnly": true,
"type": "string"
},
"finished": {
"description": "Whether the payment has finished",
"readOnly": true,
"type": "boolean"
},
"message": {
"description": "What went wrong with the Payment if it finished with an error - English message",
"example": "User cancelled the payment",
"readOnly": true,
"type": "string"
},
"status": {
"description": "Current progress of the payment in its lifecycle",
"example": "created",
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"PostLink": {
"description": "A POST link related to a payment",
"properties": {
"href": {
"example": "https://an.example.link/from/payment/platform",
"readOnly": true,
"type": "string"
},
"method": {
"example": "POST",
"readOnly": true,
"type": "string"
},
"params": {
"additionalProperties": {
"type": "object"
},
"example": "\"description\":\"This is a value for a parameter called description\"",
"type": "object"
},
"type": {
"example": "application/x-www-form-urlencoded",
"type": "string"
}
},
"type": "object"
},
"PrefilledCardholderDetails": {
"properties": {
"billing_address": {
"$ref": "#/definitions/Address",
"description": "prefilled billing address",
"readOnly": true
},
"cardholder_name": {
"description": "prefilled cardholder name",
"example": "J. Bogs",
"maxLength": 255,
"minLength": 0,
"type": "string"
}
},
"type": "object"
},
"Refund": {
"properties": {
"_links": {
"$ref": "#/definitions/RefundLinksForSearch"
},
"amount": {
"example": 120,
"format": "int64",
"readOnly": true,
"type": "integer"
},
"created_date": {
"example": "2017-01-10T16:52:07.855Z",
"readOnly": true,
"type": "string"
},
"refund_id": {
"example": "act4c33g40j3edfmi8jknab84x",
"readOnly": true,
"type": "string"
},
"settlement_summary": {
"$ref": "#/definitions/RefundSettlementSummary",
"readOnly": true
},
"status": {
"enum": [
"submitted",
"success",
"error"
],
"example": "success",
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"RefundDetailForSearch": {
"properties": {
"_links": {
"$ref": "#/definitions/RefundLinksForSearch",
"readOnly": true
},
"amount": {
"example": 120,
"format": "int64",
"readOnly": true,
"type": "integer"
},
"created_date": {
"example": "2017-01-10T16:52:07.855Z",
"readOnly": true,
"type": "string"
},
"refund_id": {
"example": "act4c33g40j3edfmi8jknab84x",
"readOnly": true,
"type": "string"
},
"settlement_summary": {
"$ref": "#/definitions/RefundSettlementSummary",
"readOnly": true
},
"status": {
"enum": [
"submitted",
"success",
"error"
],
"example": "success",
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"RefundError": {
"description": "A Refund Error response",
"properties": {
"code": {
"example": "P0102",
"type": "string"
},
"description": {
"example": "Invalid attribute value: amountSubmitted. Must be less than or equal to 10000000",
"type": "string"
},
"field": {
"example": "amount_submitted",
"type": "string"
}
},
"type": "object"
},
"RefundForSearchResult": {
"properties": {
"_embedded": {
"$ref": "#/definitions/EmbeddedRefunds",
"readOnly": true
},
"_links": {
"$ref": "#/definitions/RefundLinksForSearch"
},
"payment_id": {
"example": "hu20sqlact5260q2nanm0q8u93",
"type": "string"
}
},
"type": "object"
},
"RefundLinksForSearch": {
"description": "links for search refunds resource",
"properties": {
"payment": {
"$ref": "#/definitions/Link",
"description": "payment",
"readOnly": true
},
"self": {
"$ref": "#/definitions/Link",
"description": "self",
"readOnly": true
}
},
"type": "object"
},
"RefundSearchResults": {
"properties": {
"_links": {
"$ref": "#/definitions/SearchNavigationLinks",
"readOnly": true
},
"count": {
"example": 20,
"format": "int32",
"type": "integer"
},
"page": {
"example": 1,
"format": "int32",
"type": "integer"
},
"results": {
"items": {
"$ref": "#/definitions/RefundDetailForSearch"
},
"type": "array"
},
"total": {
"example": 100,
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"RefundSettlementSummary": {
"description": "A structure representing information about a settlement for refunds",
"properties": {
"settled_date": {
"description": "The date that the transaction was refunded from the service's account.",
"example": "2016-01-21",
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"RefundSummary": {
"description": "A structure representing the refunds availability",
"properties": {
"amount_available": {
"description": "Amount available for refund in pence",
"example": 100,
"format": "int64",
"readOnly": true,
"type": "integer"
},
"amount_submitted": {
"description": "Amount submitted for refunds on this Payment in pence",
"format": "int64",
"readOnly": true,
"type": "integer"
},
"status": {
"description": "Availability status of the refund",
"example": "available",
"type": "string"
}
},
"type": "object"
},
"SearchNavigationLinks": {
"description": "Links to navigate through pages",
"properties": {
"first_page": {
"$ref": "#/definitions/Link",
"readOnly": true
},
"last_page": {
"$ref": "#/definitions/Link",
"readOnly": true
},
"next_page": {
"$ref": "#/definitions/Link",
"readOnly": true
},
"prev_page": {
"$ref": "#/definitions/Link",
"readOnly": true
},
"self": {
"$ref": "#/definitions/Link",
"readOnly": true
}
},
"type": "object"
}
}
}