Created
September 4, 2018 11:25
-
-
Save heathd/9b7d0ce371e3f094ef5a0d1439cc8b31 to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| openapi: 3.0.0 | |
| info: | |
| description: GOV.UK Pay API | |
| version: 1.0.0 | |
| title: GOV.UK Pay API | |
| tags: | |
| - name: refunds | |
| description: Public Api Endpoints for Refunds | |
| paths: | |
| /v1/payments: | |
| get: | |
| summary: Search payments | |
| 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: searchPayments | |
| parameters: | |
| - name: reference | |
| in: query | |
| description: Your payment reference to search | |
| required: false | |
| schema: | |
| type: string | |
| - name: email | |
| in: query | |
| description: The user email used in the payment to be searched | |
| required: false | |
| schema: | |
| type: string | |
| - name: state | |
| in: query | |
| description: State of payments to be searched. Example=success | |
| required: false | |
| schema: | |
| type: string | |
| enum: | |
| - 'range[created' | |
| - started | |
| - submitted | |
| - success | |
| - failed | |
| - cancelled | |
| - error | |
| - name: card_brand | |
| in: query | |
| description: Card brand used for payment. Example=master-card | |
| required: false | |
| schema: | |
| type: string | |
| - name: from_date | |
| in: query | |
| description: >- | |
| From date of payments to be searched (this date is inclusive). | |
| Example=2015-08-13T12:35:00Z | |
| required: false | |
| schema: | |
| type: string | |
| - name: to_date | |
| in: query | |
| description: >- | |
| To date of payments to be searched (this date is exclusive). | |
| Example=2015-08-14T12:35:00Z | |
| required: false | |
| schema: | |
| type: string | |
| - name: page | |
| in: query | |
| description: >- | |
| Page number requested for the search, should be a positive integer | |
| (optional, defaults to 1) | |
| required: false | |
| schema: | |
| type: string | |
| - name: display_size | |
| in: query | |
| description: >- | |
| Number of results to be shown per page, should be a positive integer | |
| (optional, defaults to 500, max 500) | |
| 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' | |
| post: | |
| summary: Create new payment | |
| 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: newPayment | |
| responses: | |
| '201': | |
| description: Created | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/PaymentWithAllLinks' | |
| '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' | |
| requestBody: | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/ValidCreatePaymentRequest' | |
| description: requestPayload | |
| required: true | |
| '/v1/payments/{paymentId}': | |
| get: | |
| summary: Find payment by ID | |
| 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: getPayment | |
| parameters: | |
| - name: paymentId | |
| in: path | |
| required: true | |
| schema: | |
| type: string | |
| responses: | |
| '200': | |
| description: OK | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/PaymentWithAllLinks' | |
| '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' | |
| '/v1/payments/{paymentId}/cancel': | |
| post: | |
| summary: Cancel payment | |
| 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: cancelPayment | |
| parameters: | |
| - name: paymentId | |
| in: path | |
| required: true | |
| 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' | |
| '/v1/payments/{paymentId}/events': | |
| get: | |
| summary: Return payment events by ID | |
| 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: getPaymentEvents | |
| parameters: | |
| - name: paymentId | |
| in: path | |
| required: true | |
| 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' | |
| '/v1/payments/{paymentId}/refunds': | |
| get: | |
| tags: | |
| - refunds | |
| summary: Get all refunds for a payment. | |
| 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: getRefunds | |
| parameters: | |
| - name: paymentId | |
| in: path | |
| required: true | |
| schema: | |
| type: string | |
| responses: | |
| '200': | |
| description: OK | |
| '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' | |
| post: | |
| tags: | |
| - refunds | |
| summary: Submit a refund for a payment | |
| description: >- | |
| Return issued refund information. The Authorisation token needs to be | |
| specified in the 'authorization' header as 'authorization: Bearer | |
| YOUR_API_KEY_HERE' | |
| operationId: submitRefund | |
| parameters: | |
| - name: paymentId | |
| in: path | |
| description: paymentId | |
| required: true | |
| schema: | |
| type: string | |
| responses: | |
| '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' | |
| requestBody: | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/CreatePaymentRefundRequest' | |
| description: requestPayload | |
| required: true | |
| '/v1/payments/{paymentId}/refunds/{refundId}': | |
| get: | |
| tags: | |
| - refunds | |
| summary: Find payment refund by ID | |
| 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: getRefundById | |
| parameters: | |
| - name: paymentId | |
| in: path | |
| required: true | |
| schema: | |
| type: string | |
| - name: refundId | |
| in: path | |
| required: true | |
| schema: | |
| type: string | |
| responses: | |
| '200': | |
| description: OK | |
| '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' | |
| servers: | |
| - url: 'https://publicapi.payments.service.gov.uk/' | |
| components: | |
| schemas: | |
| Address: | |
| type: object | |
| properties: | |
| line1: | |
| type: string | |
| example: address line 1 | |
| readOnly: true | |
| line2: | |
| type: string | |
| example: address line 2 | |
| readOnly: true | |
| postcode: | |
| type: string | |
| example: AB1 2CD | |
| readOnly: true | |
| city: | |
| type: string | |
| example: address city | |
| readOnly: true | |
| country: | |
| type: string | |
| example: UK | |
| readOnly: true | |
| description: A structure representing the billing address of a card | |
| CardDetails: | |
| type: object | |
| properties: | |
| last_digits_card_number: | |
| type: string | |
| example: '1234' | |
| readOnly: true | |
| cardholder_name: | |
| type: string | |
| example: Mr. Card holder | |
| readOnly: true | |
| expiry_date: | |
| type: string | |
| example: 12/20 | |
| readOnly: true | |
| billing_address: | |
| readOnly: true | |
| $ref: '#/components/schemas/Address' | |
| card_brand: | |
| type: string | |
| example: Visa | |
| readOnly: true | |
| description: A structure representing the payment card | |
| CardPayment: | |
| allOf: | |
| - $ref: '#/components/schemas/Payment' | |
| - type: object | |
| properties: | |
| refund_summary: | |
| readOnly: true | |
| $ref: '#/components/schemas/RefundSummary' | |
| settlement_summary: | |
| readOnly: true | |
| $ref: '#/components/schemas/SettlementSummary' | |
| card_details: | |
| readOnly: true | |
| $ref: '#/components/schemas/CardDetails' | |
| card_brand: | |
| type: string | |
| example: Visa | |
| description: Card Brand | |
| readOnly: true | |
| CreatePaymentRefundRequest: | |
| type: object | |
| required: | |
| - amount | |
| properties: | |
| amount: | |
| type: integer | |
| format: int32 | |
| example: 150000 | |
| description: Amount in pence. Can't be more than the available amount for refunds | |
| minimum: 1 | |
| maximum: 10000000 | |
| refund_amount_available: | |
| type: integer | |
| format: int32 | |
| example: 200000 | |
| description: >- | |
| Amount in pence. Total amount still available before issuing the | |
| refund | |
| readOnly: true | |
| minimum: 1 | |
| maximum: 10000000 | |
| description: The Payment Refund Request Payload | |
| DirectDebitPayment: | |
| allOf: | |
| - $ref: '#/components/schemas/Payment' | |
| - type: object | |
| ErrorResponse: | |
| type: object | |
| properties: | |
| code: | |
| type: string | |
| example: P0900 | |
| description: | |
| type: string | |
| example: Too many requests | |
| description: An error response | |
| Link: | |
| type: object | |
| properties: | |
| href: | |
| type: string | |
| example: 'https://an.example.link/from/payment/platform' | |
| readOnly: true | |
| method: | |
| type: string | |
| example: GET | |
| readOnly: true | |
| description: A link related to a payment | |
| Payment: | |
| type: object | |
| discriminator: | |
| propertyName: paymentType | |
| properties: | |
| amount: | |
| type: integer | |
| format: int64 | |
| example: 1200 | |
| state: | |
| $ref: '#/components/schemas/PaymentState' | |
| description: | |
| type: string | |
| example: Your Service Description | |
| reference: | |
| type: string | |
| example: your-reference | |
| email: | |
| type: string | |
| example: your email | |
| payment_id: | |
| type: string | |
| example: hu20sqlact5260q2nanm0q8u93 | |
| readOnly: true | |
| payment_provider: | |
| type: string | |
| example: worldpay | |
| readOnly: true | |
| return_url: | |
| type: string | |
| example: 'http://your.service.domain/your-reference' | |
| readOnly: true | |
| created_date: | |
| type: string | |
| example: '2016-01-21T17:15:00Z' | |
| readOnly: true | |
| PaymentError: | |
| type: object | |
| properties: | |
| field: | |
| type: string | |
| example: amount | |
| code: | |
| type: string | |
| example: P0102 | |
| description: | |
| type: string | |
| example: >- | |
| Invalid attribute value: amount. Must be less than or equal to | |
| 10000000 | |
| description: A Payment Error response | |
| PaymentEvent: | |
| type: object | |
| properties: | |
| payment_id: | |
| type: string | |
| example: hu20sqlact5260q2nanm0q8u93 | |
| readOnly: true | |
| state: | |
| description: state | |
| readOnly: true | |
| $ref: '#/components/schemas/PaymentState' | |
| updated: | |
| type: string | |
| example: updated_date | |
| description: updated | |
| readOnly: true | |
| _links: | |
| readOnly: true | |
| $ref: '#/components/schemas/PaymentEventLink' | |
| description: A List of Payment Events information | |
| PaymentEventLink: | |
| type: object | |
| properties: | |
| payment_url: | |
| description: payment_url | |
| readOnly: true | |
| $ref: '#/components/schemas/Link' | |
| description: Resource link for a payment of a payment event | |
| PaymentEvents: | |
| type: object | |
| properties: | |
| events: | |
| type: array | |
| items: | |
| $ref: '#/components/schemas/PaymentEvent' | |
| payment_id: | |
| type: string | |
| example: hu20sqlact5260q2nanm0q8u93 | |
| readOnly: true | |
| _links: | |
| $ref: '#/components/schemas/PaymentLinks' | |
| description: A List of Payment Events information | |
| PaymentLinks: | |
| type: object | |
| properties: | |
| self: | |
| description: self | |
| readOnly: true | |
| $ref: '#/components/schemas/Link' | |
| next_url: | |
| description: next_url | |
| readOnly: true | |
| $ref: '#/components/schemas/Link' | |
| next_url_post: | |
| description: next_url_post | |
| readOnly: true | |
| $ref: '#/components/schemas/PostLink' | |
| events: | |
| description: events | |
| readOnly: true | |
| $ref: '#/components/schemas/Link' | |
| refunds: | |
| description: refunds | |
| readOnly: true | |
| $ref: '#/components/schemas/Link' | |
| cancel: | |
| description: cancel | |
| readOnly: true | |
| $ref: '#/components/schemas/PostLink' | |
| description: 'self,events and next links of a Payment' | |
| PaymentLinksForSearch: | |
| type: object | |
| properties: | |
| self: | |
| description: self | |
| readOnly: true | |
| $ref: '#/components/schemas/Link' | |
| cancel: | |
| description: cancel | |
| readOnly: true | |
| $ref: '#/components/schemas/PostLink' | |
| events: | |
| description: events | |
| readOnly: true | |
| $ref: '#/components/schemas/Link' | |
| refunds: | |
| description: refunds | |
| readOnly: true | |
| $ref: '#/components/schemas/Link' | |
| description: links for search payment resource | |
| PaymentSearchResults: | |
| type: object | |
| properties: | |
| results: | |
| type: array | |
| readOnly: true | |
| items: | |
| $ref: '#/components/schemas/CardPayment' | |
| PaymentState: | |
| type: object | |
| properties: | |
| status: | |
| type: string | |
| example: created | |
| description: Current progress of the payment in its lifecycle | |
| readOnly: true | |
| finished: | |
| type: boolean | |
| description: Whether the payment has finished | |
| readOnly: true | |
| message: | |
| type: string | |
| example: User cancelled the payment | |
| description: >- | |
| What went wrong with the Payment if it finished with an error - | |
| English message | |
| readOnly: true | |
| code: | |
| type: string | |
| example: P010 | |
| description: >- | |
| What went wrong with the Payment if it finished with an error - | |
| error code | |
| readOnly: true | |
| description: >- | |
| A structure representing the current state of the payment in its | |
| lifecycle. | |
| PaymentWithAllLinks: | |
| type: object | |
| properties: | |
| payment: | |
| $ref: '#/components/schemas/Payment' | |
| _links: | |
| readOnly: true | |
| $ref: '#/components/schemas/PaymentLinks' | |
| PostLink: | |
| type: object | |
| properties: | |
| type: | |
| type: string | |
| example: multipart/form-data | |
| params: | |
| type: object | |
| example: '"description":"This is a value for a parameter called description"' | |
| additionalProperties: | |
| type: object | |
| href: | |
| type: string | |
| example: 'https://an.example.link/from/payment/platform' | |
| readOnly: true | |
| method: | |
| type: string | |
| example: POST | |
| readOnly: true | |
| description: A POST link related to a payment | |
| RefundSummary: | |
| type: object | |
| properties: | |
| status: | |
| type: string | |
| example: available | |
| description: Availability status of the refund | |
| amount_available: | |
| type: integer | |
| format: int64 | |
| description: Amount available for refund in pence | |
| readOnly: true | |
| amount_submitted: | |
| type: integer | |
| format: int64 | |
| description: Amount submitted for refunds on this Payment in pence | |
| readOnly: true | |
| description: A structure representing the refunds availability | |
| SettlementSummary: | |
| type: object | |
| properties: | |
| capture_submit_time: | |
| type: string | |
| example: '2016-01-21T17:15:00Z' | |
| description: >- | |
| Date and time capture request has been submitted (may be null if | |
| capture request was not immediately acknowledged by payment gateway) | |
| readOnly: true | |
| captured_date: | |
| type: string | |
| example: '2016-01-21' | |
| description: Date of the capture event | |
| readOnly: true | |
| description: A structure representing information about a settlement | |
| ValidCreatePaymentRequest: | |
| type: object | |
| properties: | |
| amount: | |
| type: integer | |
| format: int32 | |
| reference: | |
| type: string | |
| description: | |
| type: string | |
| returnUrl: | |
| type: string |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment