@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api GOV.UK Pay API
@base https://publicapi.payments.service.gov.uk
@version 1.0.3
@auth ApiKey Authorization in header
@endpoints 10
@toc payments(9), refunds(1)

@group payments
@endpoint GET /v1/payments
@desc Search payments
@optional {reference: any # Your payment reference to search (exact match, case insensitive), email: any # The user email used in the payment to be searched, state: any # State of payments to be searched. Example=success, card_brand: any # Card brand used for payment. Example=master-card, from_date: any # From date of payments to be searched (this date is inclusive). Example=2015-08-13T12:35:00Z, to_date: any # To date of payments to be searched (this date is exclusive). Example=2015-08-14T12:35:00Z, page: any # Page number requested for the search, should be a positive integer (optional, defaults to 1), display_size: any # Number of results to be shown per page, should be a positive integer (optional, defaults to 500, max 500), cardholder_name: any # Name on card used to make payment, first_digits_card_number: any # First six digits of the card used to make payment, last_digits_card_number: any # Last four digits of the card used to make payment, from_settled_date: any # From settled date of payment to be searched (this date is inclusive). Example=2015-08-13, to_settled_date: any # To settled date of payment to be searched (this date is inclusive). Example=2015-08-14}
@returns(200) OK
@errors {401: Credentials are required to access this resource, 422: Invalid parameters: from_date, to_date, status, display_size. See Public API documentation for the correct data formats, 429: Too many requests, 500: Downstream system error}

@endpoint POST /v1/payments
@desc Create new payment
@required {body: map # requestPayload}
@returns(201) Created
@errors {400: Bad request, 401: Credentials are required to access this resource, 422: Invalid attribute value: description. Must be less than or equal to 255 characters length, 429: Too many requests, 500: Downstream system error}

@endpoint GET /v1/payments/{paymentId}
@desc Find payment by ID
@required {paymentId: any # Payment identifier}
@returns(200) OK
@errors {401: Credentials are required to access this resource, 404: Not found, 429: Too many requests, 500: Downstream system error}

@endpoint POST /v1/payments/{paymentId}/cancel
@desc Cancel payment
@required {paymentId: any # Payment identifier}
@returns(204) No Content
@errors {400: Cancellation of payment failed, 401: Credentials are required to access this resource, 404: Not found, 409: Conflict, 429: Too many requests, 500: Downstream system error}

@endpoint POST /v1/payments/{paymentId}/capture
@desc Capture payment
@required {paymentId: any # Payment identifier}
@returns(204) No Content
@errors {400: Capture of payment failed, 401: Credentials are required to access this resource, 404: Not found, 409: Conflict, 429: Too many requests, 500: Downstream system error}

@endpoint GET /v1/payments/{paymentId}/events
@desc Return payment events by ID
@required {paymentId: any # Payment identifier}
@returns(200) OK
@errors {401: Credentials are required to access this resource, 404: Not found, 429: Too many requests, 500: Downstream system error}

@endpoint GET /v1/payments/{paymentId}/refunds
@desc Get all refunds for a payment
@required {paymentId: any}
@returns(200) OK
@errors {401: Credentials are required to access this resource, 404: Not found, 429: Too many requests, 500: Downstream system error}

@endpoint POST /v1/payments/{paymentId}/refunds
@desc Submit a refund for a payment
@required {paymentId: any # paymentId, body: map # requestPayload}
@returns(200) successful operation
@returns(202) ACCEPTED
@errors {401: Credentials are required to access this resource, 404: Not found, 412: Refund amount available mismatch, 429: Too many requests, 500: Downstream system error}

@endpoint GET /v1/payments/{paymentId}/refunds/{refundId}
@desc Find payment refund by ID
@required {paymentId: any, refundId: any}
@returns(200) OK
@errors {401: Credentials are required to access this resource, 404: Not found, 429: Too many requests, 500: Downstream system error}

@endgroup

@group refunds
@endpoint GET /v1/refunds
@desc Search refunds
@optional {from_date: any # From date of refunds to be searched (this date is inclusive). Example=2015-08-13T12:35:00Z, to_date: any # To date of refunds to be searched (this date is exclusive). Example=2015-08-14T12:35:00Z, from_settled_date: any # From settled date of refund to be searched (this date is inclusive). Example=2015-08-13, to_settled_date: any # To settled date of refund to be searched (this date is inclusive). Example=2015-08-13, page: any # Page number requested for the search, should be a positive integer (optional, defaults to 1), display_size: any # Number of results to be shown per page, should be a positive integer (optional, defaults to 500, max 500)}
@returns(200) OK
@errors {401: Credentials are required to access this resource, 422: Invalid parameters. See Public API documentation for the correct data formats, 500: Downstream system error}

@endgroup

@end