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://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
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
