GOV.UK Pay Refunding card payments API

openapi: 3.0.1
info:
  description: The GOV.UK Pay REST API. Read [our documentation](https://docs.payments.service.gov.uk/) for more details.
  title: GOV.UK Pay Agreements Refunding card payments API
  version: 1.0.3
servers:
- url: https://publicapi.payments.service.gov.uk
tags:
- name: Refunding card payments
paths:
  /v1/payments/{paymentId}/refunds:
    get:
      description: You can use this endpoint to [get a list of refunds for a payment](https://docs.payments.service.gov.uk/refunding_payments/#get-all-refunds-for-a-single-payment).
      operationId: Get all refunds for a payment
      parameters:
      - description: The unique `payment_id` of the payment you want a list of refunds for.
        in: path
        name: paymentId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundForSearchResult'
          description: OK - your request was successful.
        '401':
          description: Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: Not found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: Downstream system error
      security:
      - BearerAuth: []
      summary: Get information about a payment’s refunds
      tags:
      - Refunding card payments
    post:
      description: You can use this endpoint to [fully or partially refund a payment](https://docs.payments.service.gov.uk/refunding_payments).
      operationId: Submit a refund for a payment
      parameters:
      - description: The unique `payment_id` of the payment you want to refund.
        in: path
        name: paymentId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRefundRequest'
        description: requestPayload
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
          description: successful operation
        '202':
          description: ACCEPTED
        '401':
          description: Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: Not found
        '412':
          description: Refund amount available mismatch
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: Downstream system error
      security:
      - BearerAuth: []
      summary: Refund a payment
      tags:
      - Refunding card payments
  /v1/payments/{paymentId}/refunds/{refundId}:
    get:
      description: You can use this endpoint to [get details about an individual refund](https://docs.payments.service.gov.uk/refunding_payments/#checking-the-status-of-a-refund).
      operationId: Get a payment refund
      parameters:
      - description: The unique `payment_id` of the payment you want to view a refund of.
        in: path
        name: paymentId
        required: true
        schema:
          type: string
      - description: The unique `refund_id` of the refund you want to view. If one payment has multiple refunds, each refund has a different `refund_id`.
        in: path
        name: refundId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
          description: OK - your request was successful.
        '401':
          description: Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: Not found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: Downstream system error
      security:
      - BearerAuth: []
      summary: Check the status of a refund
      tags:
      - Refunding card payments
  /v1/refunds:
    get:
      description: You can use this endpoint to [search refunds you’ve previously created](https://docs.payments.service.gov.uk/refunding_payments/#searching-refunds). The refunds are sorted by date, with the most recently created refunds appearing first.
      operationId: Search refunds
      parameters:
      - description: Returns refunds created on or after the `from_date`. Date and time must use Coordinated Universal Time (UTC) and ISO 8601 format to second-level accuracy - `YYYY-MM-DDThh:mm:ssZ`.
        example: '2015-08-13T12:35:00Z'
        in: query
        name: from_date
        schema:
          type: string
      - description: Returns refunds created before the `to_date`. Date and time must use Coordinated Universal Time (UTC) and ISO 8601 format to second-level accuracy - `YYYY-MM-DDThh:mm:ssZ`.
        example: '2015-08-13T12:35:00Z'
        in: query
        name: to_date
        schema:
          type: string
      - description: Returns refunds settled on or after the `from_settled_date` value. You can only use `from_settled_date` if your payment service provider is Stripe. Date must use ISO 8601 format to date-level accuracy - `YYYY-MM-DD`. Refunds are settled when Stripe takes the refund from your account balance.
        example: '2022-08-13'
        in: query
        name: from_settled_date
        schema:
          type: string
      - description: Returns refunds settled before the `to_settled_date` value. You can only use `to_settled_date` if your payment service provider is Stripe. Date must use ISO 8601 format to date-level accuracy - `YYYY-MM-DD`. Refunds are settled when Stripe takes the refund from your account balance.
        example: '2022-08-13'
        in: query
        name: to_settled_date
        schema:
          type: string
      - description: Returns a [specific page of results](https://docs.payments.service.gov.uk/api_reference/#pagination). Defaults to `1`.
        in: query
        name: page
        schema:
          type: string
      - description: The number of refunds returned [per results page](https://docs.payments.service.gov.uk/api_reference/#pagination). Defaults to `500`. Maximum value is `500`.
        in: query
        name: display_size
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundSearchResults'
          description: OK - your request was successful.
        '401':
          description: Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: Invalid parameters. See Public API documentation for the correct data formats
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: Downstream system error
      security:
      - BearerAuth: []
      summary: Search refunds
      tags:
      - Refunding card payments
components:
  schemas:
    PaymentRefundRequest:
      type: object
      description: The Payment Refund Request Payload
      properties:
        amount:
          type: integer
          format: int32
          description: The amount you want to [refund to your user](https://docs.payments.service.gov.uk/refunding_payments/) in pence.
          example: 150000
          maximum: 10000000
          minimum: 1
        refund_amount_available:
          type: integer
          format: int32
          description: Amount in pence. Total amount still available before issuing the refund
          example: 200000
          maximum: 10000000
          minimum: 1
      required:
      - amount
    Refund:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/RefundLinksForSearch'
        amount:
          type: integer
          format: int64
          description: The amount refunded to the user in pence.
          example: 120
          readOnly: true
        created_date:
          type: string
          description: The date and time you created this refund. This value uses Coordinated Universal Time (UTC) and ISO 8601 format - `YYYY-MM-DDThh:mm:ss.SSSZ`.
          example: '2017-01-10T16:52:07.855Z'
          readOnly: true
        payment_id:
          type: string
          description: The unique ID GOV.UK Pay automatically associated with this payment when you created it.
          example: hu20sqlact5260q2nanm0q8u93
          readOnly: true
        refund_id:
          type: string
          description: The unique ID GOV.UK Pay automatically associated with this refund when you created it.
          example: act4c33g40j3edfmi8jknab84x
          readOnly: true
        settlement_summary:
          $ref: '#/components/schemas/RefundSettlementSummary'
        status:
          type: string
          description: The [status of the refund](https://docs.payments.service.gov.uk/refunding_payments/#checking-the-status-of-a-refund-status).
          enum:
          - submitted
          - success
          - error
          example: success
          readOnly: true
    EmbeddedRefunds:
      type: object
      properties:
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
    ErrorResponse:
      type: object
      description: An error response
      properties:
        code:
          type: string
          description: A GOV.UK Pay API error code. You can [find out more about this code in our documentation](https://docs.payments.service.gov.uk/api_reference/#gov-uk-pay-api-error-codes).
          example: P0900
        description:
          type: string
          description: Additional details about the error
          example: Too many requests
    RefundSearchResults:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/SearchNavigationLinks'
        count:
          type: integer
          format: int32
          description: Number of refunds on the current page of search results.
          example: 20
        page:
          type: integer
          format: int32
          description: The [page of results](payments.service.gov.uk/api_reference/#pagination) you’re viewing. To view other pages, make this request again using the `page` parameter.
          example: 1
        results:
          type: array
          description: Contains the refunds matching your search criteria.
          items:
            $ref: '#/components/schemas/RefundDetailForSearch'
        total:
          type: integer
          format: int32
          description: Number of refunds matching your search criteria.
          example: 100
    RefundDetailForSearch:
      type: object
      description: Contains the refunds matching your search criteria.
      properties:
        _links:
          $ref: '#/components/schemas/RefundLinksForSearch'
        amount:
          type: integer
          format: int64
          description: The amount refunded to the user in pence.
          example: 120
          readOnly: true
        created_date:
          type: string
          description: The date and time you created this refund. This value uses Coordinated Universal Time (UTC) and ISO 8601 format - `YYYY-MM-DDThh:mm:ss.SSSZ`.
          example: '2017-01-10T16:52:07.855Z'
          readOnly: true
        payment_id:
          type: string
          description: The unique ID GOV.UK Pay automatically associated with this payment when you created it.
          example: hu20sqlact5260q2nanm0q8u93
          readOnly: true
        refund_id:
          type: string
          description: The unique ID GOV.UK Pay automatically associated with this refund when you created it.
          example: act4c33g40j3edfmi8jknab84x
          readOnly: true
        settlement_summary:
          $ref: '#/components/schemas/RefundSettlementSummary'
        status:
          type: string
          description: The [status of the refund](https://docs.payments.service.gov.uk/refunding_payments/#checking-the-status-of-a-refund-status).
          enum:
          - submitted
          - success
          - error
          example: success
          readOnly: true
    RefundLinksForSearch:
      type: object
      description: links for search refunds resource
      properties:
        payment:
          $ref: '#/components/schemas/Link'
        self:
          $ref: '#/components/schemas/Link'
    RefundForSearchResult:
      type: object
      properties:
        _embedded:
          $ref: '#/components/schemas/EmbeddedRefunds'
        _links:
          $ref: '#/components/schemas/RefundLinksForSearch'
        payment_id:
          type: string
          description: The unique ID GOV.UK Pay associated with this payment when you created it.
          example: hu20sqlact5260q2nanm0q8u93
    RequestError:
      type: object
      description: A Request Error response
      properties:
        code:
          type: string
          description: An [API error code](https://docs.payments.service.gov.uk/api_reference/#gov-uk-pay-api-error-codes)that explains why the payment failed.<br><br>`code` only appears if the payment failed.
          example: P0102
        description:
          type: string
          description: Additional details about the error.
          example: 'Invalid attribute value: amount. Must be less than or equal to 10000000'
        field:
          type: string
          description: The parameter in your request that's causing the error.
          example: amount
        header:
          type: string
          description: The header in your request that's causing the error.
          example: Idempotency-Key
    Link:
      type: object
      description: A link related to a payment
      properties:
        href:
          type: string
          description: A URL that lets you perform additional actions to this payment when combined with the associated `method`.
          example: https://an.example.link/from/payment/platform
          readOnly: true
        method:
          type: string
          description: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
          example: GET
          readOnly: true
    RefundSettlementSummary:
      type: object
      description: A structure representing information about a settlement for refunds
      properties:
        settled_date:
          type: string
          description: The date Stripe took the refund from a payout to your bank account. `settled_date` only appears if Stripe has taken the refund. This value uses Coordinated Universal Time (UTC) and ISO 8601 format - `YYYY-MM-DD`.
          example: '2016-01-21'
          readOnly: true
      readOnly: true
    SearchNavigationLinks:
      type: object
      description: Links to navigate through pages of your search.
      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'
  securitySchemes:
    BearerAuth:
      description: 'GOV.UK Pay authenticates API calls with [OAuth2 HTTP bearer tokens](http://tools.ietf.org/html/rfc6750). You need to use an `"Authorization"` HTTP header to provide your API key, with a `"Bearer"` prefix. For example: `Authorization: Bearer {YOUR_API_KEY_HERE}`'
      scheme: bearer
      type: http