openapi-directory/api/payments.service.gov.uk/payments.json

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

{"openapi":"3.0.0","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://twitter.com/GOVUK/profile_image?size=original"},"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"},"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,"schema":{"type":"string"}},{"description":"The user email used in the payment to be searched","in":"query","name":"email","required":false,"schema":{"type":"string"}},{"description":"State of payments to be searched. Example=success","in":"query","name":"state","required":false,"schema":{"type":"string","enum":["created","started","submitted","success","failed","cancelled","error"]}},{"description":"Card brand used for payment. Example=master-card","in":"query","name":"card_brand","required":false,"schema":{"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,"schema":{"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,"schema":{"type":"string"}},{"description":"Page number requested for the search, should be a positive integer (optional, defaults to 1)","in":"query","name":"page","required":false,"schema":{"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,"schema":{"type":"string"}},{"description":"Name on card used to make payment","in":"query","name":"cardholder_name","required":false,"schema":{"type":"string"}},{"description":"First six digits of the card used to make payment","in":"query","name":"first_digits_card_number","required":false,"schema":{"type":"string"}},{"description":"Last four digits of the card used to make payment","in":"query","name":"last_digits_card_number","required":false,"schema":{"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,"schema":{"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,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Downstream system error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}},"security":[{"Authorization":[]}],"summary":"Search payments","tags":["Card payments"]},"post":{"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","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCardPaymentRequest"}}},"description":"requestPayload","required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentResult"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Downstream system error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/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,"example":"hu20sqlact5260q2nanm0q8u93","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPaymentResult"}}}},"401":{"description":"Credentials are required to access this resource"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Downstream system error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/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,"example":"hu20sqlact5260q2nanm0q8u93","schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"400":{"description":"Cancellation of payment failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"401":{"description":"Credentials are required to access this resource"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Downstream system error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/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,"example":"hu20sqlact5260q2nanm0q8u93","schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"400":{"description":"Capture of payment failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"401":{"description":"Credentials are required to access this resource"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Downstream system error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/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,"example":"hu20sqlact5260q2nanm0q8u93","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentEvents"}}}},"401":{"description":"Credentials are required to access this resource"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Downstream system error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/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,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundForSearchResult"}}}},"401":{"description":"Credentials are required to access this resource"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Downstream system error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}},"security":[{"Authorization":[]}],"summary":"Get all refunds for a payment","tags":["Refunding card payments"]},"post":{"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,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRefundRequest"}}},"description":"requestPayload","required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"202":{"description":"ACCEPTED"},"401":{"description":"Credentials are required to access this resource"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"412":{"description":"Refund amount available mismatch"},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Downstream system error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/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,"schema":{"type":"string"}},{"in":"path","name":"refundId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"401":{"description":"Credentials are required to access this resource"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Downstream system error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/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,"schema":{"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,"schema":{"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,"schema":{"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,"schema":{"type":"string"}},{"description":"Page number requested for the search, should be a positive integer (optional, defaults to 1)","in":"query","name":"page","required":false,"schema":{"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,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundSearchResults"}}}},"401":{"description":"Credentials are required to access this resource"},"422":{"description":"Invalid parameters. See Public API documentation for the correct data formats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundError"}}}},"500":{"description":"Downstream system error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundError"}}}}},"security":[{"Authorization":[]}],"summary":"Search refunds","tags":["Refunding card payments"]}}},"servers":[{"url":"https://publicapi.payments.service.gov.uk"}],"components":{"securitySchemes":{"Authorization":{"in":"header","name":"Authorization","type":"apiKey"}},"schemas":{"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":"#/components/schemas/Address"},"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":"#/components/schemas/PrefilledCardholderDetails"},"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":"#/components/schemas/PaymentLinks"},"amount":{"description":"The amount in pence.","example":1200,"format":"int64","type":"integer"},"card_details":{"$ref":"#/components/schemas/CardDetails"},"created_date":{"description":"The date you created the payment.","example":"2025-04-15T13:50:42.601Z","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":"#/components/schemas/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":"#/components/schemas/PaymentSettlementSummary"},"state":{"$ref":"#/components/schemas/PaymentState"}},"type":"object"},"EmbeddedRefunds":{"properties":{"refunds":{"items":{"$ref":"#/components/schemas/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":"#/components/schemas/PaymentLinks"},"amount":{"example":1200,"format":"int64","type":"integer"},"card_brand":{"description":"Card Brand","example":"Visa","readOnly":true,"type":"string"},"card_details":{"$ref":"#/components/schemas/CardDetails"},"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":"#/components/schemas/RefundSummary"},"return_url":{"example":"http://your.service.domain/your-reference","readOnly":true,"type":"string"},"settlement_summary":{"$ref":"#/components/schemas/PaymentSettlementSummary"},"state":{"$ref":"#/components/schemas/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":"#/components/schemas/PaymentLinksForSearch"},"amount":{"example":1200,"format":"int64","type":"integer"},"card_brand":{"description":"Card Brand","example":"Visa","readOnly":true,"type":"string"},"card_details":{"$ref":"#/components/schemas/CardDetails"},"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":"#/components/schemas/RefundSummary"},"return_url":{"example":"http://your.service.domain/your-reference","readOnly":true,"type":"string"},"settlement_summary":{"$ref":"#/components/schemas/PaymentSettlementSummary"},"state":{"$ref":"#/components/schemas/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":"#/components/schemas/PaymentEventLink"},"payment_id":{"example":"hu20sqlact5260q2nanm0q8u93","readOnly":true,"type":"string"},"state":{"$ref":"#/components/schemas/PaymentState"},"updated":{"description":"updated","example":"2025-04-15T13:50:42.601Z","readOnly":true,"type":"string"}},"type":"object"},"PaymentEventLink":{"description":"Resource link for a payment of a payment event","properties":{"payment_url":{"$ref":"#/components/schemas/Link"}},"type":"object"},"PaymentEvents":{"description":"A List of Payment Events information","properties":{"_links":{"$ref":"#/components/schemas/PaymentLinksForEvents"},"events":{"items":{"$ref":"#/components/schemas/PaymentEvent"},"type":"array"},"payment_id":{"example":"hu20sqlact5260q2nanm0q8u93","readOnly":true,"type":"string"}},"type":"object"},"PaymentLinks":{"description":"links for payment","properties":{"cancel":{"$ref":"#/components/schemas/PostLink"},"capture":{"$ref":"#/components/schemas/PostLink"},"events":{"$ref":"#/components/schemas/Link"},"next_url":{"$ref":"#/components/schemas/Link"},"next_url_post":{"$ref":"#/components/schemas/PostLink"},"refunds":{"$ref":"#/components/schemas/Link"},"self":{"$ref":"#/components/schemas/Link"}},"type":"object"},"PaymentLinksForEvents":{"description":"links for events resource","properties":{"self":{"$ref":"#/components/schemas/Link"}},"type":"object"},"PaymentLinksForSearch":{"description":"links for search payment resource","properties":{"cancel":{"$ref":"#/components/schemas/PostLink"},"capture":{"$ref":"#/components/schemas/PostLink"},"events":{"$ref":"#/components/schemas/Link"},"refunds":{"$ref":"#/components/schemas/Link"},"self":{"$ref":"#/components/schemas/Link"}},"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":"#/components/schemas/SearchNavigationLinks"},"count":{"example":20,"format":"int32","type":"integer"},"page":{"example":1,"format":"int32","type":"integer"},"results":{"items":{"$ref":"#/components/schemas/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":"2025-04-15T13:50:42.601Z","readOnly":true,"type":"string"},"settled_date":{"description":"The date that the transaction was paid into the service's account.","example":"2025-04-15T13:50:42.601Z","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":"#/components/schemas/Address"},"cardholder_name":{"description":"prefilled cardholder name","example":"J. Bogs","maxLength":255,"minLength":0,"type":"string"}},"type":"object"},"Refund":{"properties":{"_links":{"$ref":"#/components/schemas/RefundLinksForSearch"},"amount":{"example":120,"format":"int64","readOnly":true,"type":"integer"},"created_date":{"example":"2025-04-15T13:50:42.601Z","readOnly":true,"type":"string"},"refund_id":{"example":"act4c33g40j3edfmi8jknab84x","readOnly":true,"type":"string"},"settlement_summary":{"$ref":"#/components/schemas/RefundSettlementSummary"},"status":{"enum":["submitted","success","error"],"example":"success","readOnly":true,"type":"string"}},"type":"object"},"RefundDetailForSearch":{"properties":{"_links":{"$ref":"#/components/schemas/RefundLinksForSearch"},"amount":{"example":120,"format":"int64","readOnly":true,"type":"integer"},"created_date":{"example":"2025-04-15T13:50:42.601Z","readOnly":true,"type":"string"},"refund_id":{"example":"act4c33g40j3edfmi8jknab84x","readOnly":true,"type":"string"},"settlement_summary":{"$ref":"#/components/schemas/RefundSettlementSummary"},"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":"#/components/schemas/EmbeddedRefunds"},"_links":{"$ref":"#/components/schemas/RefundLinksForSearch"},"payment_id":{"example":"hu20sqlact5260q2nanm0q8u93","type":"string"}},"type":"object"},"RefundLinksForSearch":{"description":"links for search refunds resource","properties":{"payment":{"$ref":"#/components/schemas/Link"},"self":{"$ref":"#/components/schemas/Link"}},"type":"object"},"RefundSearchResults":{"properties":{"_links":{"$ref":"#/components/schemas/SearchNavigationLinks"},"count":{"example":20,"format":"int32","type":"integer"},"page":{"example":1,"format":"int32","type":"integer"},"results":{"items":{"$ref":"#/components/schemas/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":"2025-04-15T13:50:42.601Z","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":"#/components/schemas/Link"},"last_page":{"$ref":"#/components/schemas/Link"},"next_page":{"$ref":"#/components/schemas/Link"},"prev_page":{"$ref":"#/components/schemas/Link"},"self":{"$ref":"#/components/schemas/Link"}},"type":"object"}}}}