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 Card payments API
  version: 1.0.3
servers:
- url: https://publicapi.payments.service.gov.uk
tags:
- name: Card payments
paths:
  /v1/payments:
    get:
      description: You can use this endpoint to [search for payments you’ve previously created](https://docs.payments.service.gov.uk/reporting/#search-payments/). Payments are sorted by date, with the most recently-created payment appearing first.
      operationId: Search payments
      parameters:
      - description: Returns payments with `reference` values exactly matching your specified value.
        in: query
        name: reference
        schema:
          type: string
      - description: Returns payments with matching `email` values. You can send full or partial email addresses. `email` is the paying user’s email address.
        in: query
        name: email
        schema:
          type: string
      - description: Returns payments in a matching `state`. `state` reflects where a payment is in the [payment status lifecycle](https://docs.payments.service.gov.uk/api_reference/#payment-status-lifecycle).
        example: success
        in: query
        name: state
        schema:
          type: string
          enum:
          - created
          - started
          - submitted
          - success
          - failed
          - cancelled
          - error
      - description: Returns payments paid with a particular card brand.
        in: query
        name: card_brand
        schema:
          type: string
      - description: Returns payments created on or after the `from_date`. Date and time must be 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 payments created before the `to_date`. Date and time must be 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 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 payments 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
      - description: Returns payments paid with cards under this cardholder name.
        in: query
        name: cardholder_name
        schema:
          type: string
      - description: Returns payments paid by cards beginning with the `first_digits_card_number` value. `first_digits_card_number` value must be 6 digits.
        in: query
        name: first_digits_card_number
        schema:
          type: string
      - description: Returns payments paid by cards ending with the `last_digits_card_number` value. `last_digits_card_number` value must be 4 digits.
        in: query
        name: last_digits_card_number
        schema:
          type: string
      - description: Returns payments settled on or after the `from_settled_date` value. You can only search by settled date if your payment service provider is Stripe. Date must be in ISO 8601 format to date-level accuracy - `YYYY-MM-DD`. Payments are settled when your payment service provider sends funds to your bank account.
        in: query
        name: from_settled_date
        schema:
          type: string
      - description: Returns payments settled before the `to_settled_date` value. You can only search by settled date if your payment service provider is Stripe. Date must be in ISO 8601 format to date-level accuracy - `YYYY-MM-DD`. Payments are settled when your payment service provider sends funds to your bank account.
        in: query
        name: to_settled_date
        schema:
          type: string
      - description: Returns payments that were authorised using the agreement with this `agreement_id`. Must be an exact match.
        example: abcefghjklmnopqr1234567890
        in: query
        name: agreement_id
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentSearchResults'
          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: from_date, to_date, status, display_size. See Public API documentation for the correct data formats'
        '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: Search payments
      tags:
      - Card payments
    post:
      description: You can use this endpoint to [create a new payment](https://docs.payments.service.gov.uk/making_payments/).
      operationId: Create a payment
      parameters:
      - in: header
        name: Idempotency-Key
        schema:
          type: string
          pattern: ^$|^[a-zA-Z0-9-]+$
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCardPaymentRequest'
        description: requestPayload
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentResult'
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: Bad request
        '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: Your request failed. Check the `code` and `description` in the response to find out why your request failed.
        '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: Create a payment
      tags:
      - Card payments
  /v1/payments/{paymentId}:
    get:
      description: You can use this endpoint to [get details about a single payment you’ve previously created](https://docs.payments.service.gov.uk/reporting/#get-information-about-a-single-payment).
      operationId: Get a payment
      parameters:
      - description: Returns the payment with the matching `payment_id`.
        example: hu20sqlact5260q2nanm0q8u93
        in: path
        name: paymentId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentWithAllLinks'
          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 single payment
      tags:
      - Card payments
  /v1/payments/{paymentId}/cancel:
    post:
      description: You can use this endpoint [to cancel an unfinished payment](https://docs.payments.service.gov.uk/making_payments/#cancel-a-payment-that-s-in-progress).
      operationId: Cancel a payment
      parameters:
      - description: The `payment_id` of the payment you’re cancelling.
        example: hu20sqlact5260q2nanm0q8u93
        in: path
        name: paymentId
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: Cancellation of payment failed
        '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
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: Conflict
        '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: Cancel payment
      tags:
      - Card payments
  /v1/payments/{paymentId}/capture:
    post:
      description: You can use this endpoint to [take (‘capture’) a delayed payment from the paying user’s bank account](https://docs.payments.service.gov.uk/delayed_capture/).
      operationId: Capture a payment
      parameters:
      - description: The `payment_id` of the payment you’re capturing.
        example: hu20sqlact5260q2nanm0q8u93
        in: path
        name: paymentId
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: Capture of payment failed
        '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
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: Conflict
        '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: Take a delayed payment
      tags:
      - Card payments
  /v1/payments/{paymentId}/events:
    get:
      description: You can use this endpoint to [get a list of a payment’s events](https://docs.payments.service.gov.uk/reporting/#get-a-payment-s-events). A payment event is when a payment’s `state` changes, such as when the payment is created, or when the paying user submits their details.
      operationId: Get events for a payment
      parameters:
      - description: Payment identifier
        example: hu20sqlact5260q2nanm0q8u93
        in: path
        name: paymentId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentEvents'
          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 a payment's events
      tags:
      - Card payments
components:
  schemas:
    AuthorisationSummary:
      type: object
      description: Object containing information about the authentication of the payment.
      properties:
        three_d_secure:
          $ref: '#/components/schemas/ThreeDSecure'
    RefundSummary:
      type: object
      description: A structure representing the refunds availability
      properties:
        amount_available:
          type: integer
          format: int64
          description: How much you can refund to the user, in pence.
          example: 100
          readOnly: true
        amount_submitted:
          type: integer
          format: int64
          description: How much you’ve already refunded to the user, in pence.
          readOnly: true
        status:
          type: string
          description: Whether you can [refund the payment](https://docs.payments.service.gov.uk/refunding_payments/#checking-the-status-of-a-refund-status).
          example: available
    PaymentLinksForEvents:
      type: object
      description: links for events resource
      properties:
        self:
          $ref: '#/components/schemas/Link'
    CardDetails:
      type: object
      description: A structure representing the payment card
      properties:
        billing_address:
          $ref: '#/components/schemas/Address'
        card_brand:
          type: string
          description: The brand of card the user paid with.
          example: Visa
          readOnly: true
        card_type:
          type: string
          description: The type of card the user paid with.`null` means your user paid with Google Pay or we did not recognise which type of card they paid with.
          enum:
          - debit
          - credit
          - 'null'
          example: debit
          readOnly: true
        cardholder_name:
          type: string
          example: Mr. Card holder
        expiry_date:
          type: string
          description: The expiry date of the card the user paid with in `MM/YY` format.
          example: 04/24
          readOnly: true
        first_digits_card_number:
          type: string
          example: '123456'
          readOnly: true
        last_digits_card_number:
          type: string
          example: '1234'
          readOnly: true
        wallet_type:
          type: string
          description: The digital wallet type that the user paid with
          enum:
          - Apple Pay
          - Google Pay
          example: Apple Pay
    PaymentSearchResults:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/SearchNavigationLinks'
        count:
          type: integer
          format: int32
          description: Number of payments on the current page of search results.
          example: 20
        page:
          type: integer
          format: int32
          description: The [page of results you’re viewing](https://docs.payments.service.gov.uk/api_reference/#pagination). To view other pages, make this request again using the `page` parameter.
          example: 1
        results:
          type: array
          description: Contains payments matching your search criteria.
          items:
            $ref: '#/components/schemas/PaymentDetailForSearch'
        total:
          type: integer
          format: int32
          description: Total number of payments matching your search criteria.
          example: 100
    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'
    PaymentWithAllLinks:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/PaymentLinks'
        agreement_payment_type:
          type: string
          description: When the customer initiates a standing order agreement transaction we have to include a customerInitiatedReason attribute. This can have a value of `instalment`, `recurring`, or `unscheduled`.
          enum:
          - instalment
          - recurring
          - unscheduled
        amount:
          type: integer
          format: int64
          description: The description assigned to the payment when it was created.
          example: 1200
        authorisation_mode:
          type: string
          description: How the payment will be authorised. Payments created in `web` mode require the paying user to visit the `next_url` to complete the payment.
          enum:
          - web
          - moto_api
          - external
        authorisation_summary:
          $ref: '#/components/schemas/AuthorisationSummary'
        card_brand:
          type: string
          deprecated: true
          description: This attribute is deprecated. Please use `card_details.card_brand` instead.
          example: Visa
          readOnly: true
        card_details:
          $ref: '#/components/schemas/CardDetails'
        corporate_card_surcharge:
          type: integer
          format: int64
          description: The [corporate card surcharge](https://docs.payments.service.gov.uk/corporate_card_surcharges/#add-corporate-card-fees) amount in pence.
          example: 250
          readOnly: true
        created_date:
          type: string
          example: '2016-01-21T17:15:00.000Z'
          readOnly: true
        delayed_capture:
          type: boolean
          description: '`delayed_capture` is `true` if you’re [controlling how long it takes GOV.UK Pay to take (‘capture’) a payment](https://docs.payments.service.gov.uk/delayed_capture).'
          example: false
          readOnly: true
        description:
          type: string
          description: The description assigned to the payment when it was created.
          example: Your Service Description
        email:
          type: string
          example: The paying user’s email address.
        exemption:
          $ref: '#/components/schemas/Exemption'
        fee:
          type: integer
          format: int64
          description: The [payment service provider’s (PSP) transaction fee](https://docs.payments.service.gov.uk/reporting/#psp-fees), in pence. `fee` only appears when we have taken (‘captured’) the payment from the user or if their payment fails after they submitted their card details. `fee` will not appear if your PSP is Worldpay or you are using an API key from a test service.
          example: 5
          readOnly: true
        language:
          type: string
          description: The ISO-6391 Alpha-2 code of the [language of the user's payment page](https://docs.payments.service.gov.uk/optional_features/welsh_language).
          enum:
          - en
          - cy
          example: en
        metadata:
          $ref: '#/components/schemas/ExternalMetadata'
        moto:
          type: boolean
          description: Indicates if this payment is a [Mail Order / Telephone Order (MOTO) payment](https://docs.payments.service.gov.uk/moto_payments).
          example: false
        net_amount:
          type: integer
          format: int64
          description: The amount, in pence, that will be paid into your bank account after your payment service provider takes the `fee`.
          example: 1195
          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
        payment_provider:
          type: string
          description: The payment service provider that processed this payment.
          example: worldpay
          readOnly: true
        provider_id:
          type: string
          description: The unique ID your payment service provider generated for this payment. This is not the same as the `payment_id`.
          example: reference-from-payment-gateway
          readOnly: true
        reference:
          type: string
          description: The reference associated with the payment when it was created. `reference` is not unique - multiple payments can have the same `reference` value.
          example: your-reference
        refund_summary:
          $ref: '#/components/schemas/RefundSummary'
        return_url:
          type: string
          description: The URL you direct the paying user to after their payment journey on GOV.UK Pay ends.
          example: http://your.service.domain/your-reference
          readOnly: true
        settlement_summary:
          $ref: '#/components/schemas/PaymentSettlementSummary'
        state:
          $ref: '#/components/schemas/PaymentState'
        total_amount:
          type: integer
          format: int64
          description: Amount your user paid in pence, including corporate card fees. `total_amount` only appears if you [added a corporate card surcharge to the payment](https://docs.payments.service.gov.uk/corporate_card_surcharges/#add-corporate-card-fees).
          example: 1450
          readOnly: true
    PaymentState:
      type: object
      description: A structure representing the current state of the payment in its lifecycle.
      properties:
        can_retry:
          type: boolean
          description: If `can_retry` is `true`, you can use this agreement to try to take another recurring payment. If `can_retry` is `false`, you cannot take another recurring payment with this agreement. `can_retry` only appears on failed payments that were attempted using an agreement for recurring payments.
          nullable: true
          readOnly: true
        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. `code` only appears if the payment failed.
          example: P010
          readOnly: true
        finished:
          type: boolean
          description: Indicates whether a payment journey is finished.
          readOnly: true
        message:
          type: string
          description: A description of what went wrong with this payment. `message` only appears if the payment failed.
          example: User cancelled the payment
          readOnly: true
        status:
          type: string
          description: Where the payment is in [the payment status lifecycle](https://docs.payments.service.gov.uk/api_reference/#payment-status-meanings).
          example: created
          readOnly: true
    PaymentSettlementSummary:
      type: object
      description: A structure representing information about a settlement
      properties:
        capture_submit_time:
          type: string
          description: The date and time GOV.UK Pay asked your payment service provider to take the payment from your user’s account. This value uses Coordinated Universal Time (UTC) and ISO 8601 format - `YYYY-MM-DDThh:mm:ss.SSSZ`
          example: '2016-01-21T17:15:00.000Z'
          readOnly: true
        captured_date:
          type: string
          description: The date your payment service provider took the payment from your user. This value uses ISO 8601 format - `YYYY-MM-DD`
          example: '2016-01-21'
          readOnly: true
        settled_date:
          type: string
          description: The date that the transaction was paid into the service's account.
          example: '2016-01-21'
          readOnly: true
    PrefilledCardholderDetails:
      type: object
      description: prefilled_cardholder_details
      properties:
        billing_address:
          $ref: '#/components/schemas/Address'
        cardholder_name:
          type: string
          description: The cardholder name you prefilled when you created this payment.
          example: J. Bogs
          maxLength: 255
          minLength: 0
    PostLink:
      type: object
      description: A POST 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
          example: POST
          readOnly: true
        params:
          type: object
          additionalProperties:
            type: object
            example:
              description: This is a value for a parameter called description
          example:
            description: This is a value for a parameter called description
        type:
          type: string
          example: application/x-www-form-urlencoded
    PaymentEvent:
      type: object
      description: A List of Payment Events information
      properties:
        _links:
          $ref: '#/components/schemas/PaymentEventLink'
        payment_id:
          type: string
          description: The unique ID GOV.UK Pay automatically associated with this payment when you created it.
          example: hu20sqlact5260q2nanm0q8u93
          readOnly: true
        state:
          $ref: '#/components/schemas/PaymentState'
        updated:
          type: string
          description: When this payment’s state changed. This value uses Coordinated Universal Time (UTC) and ISO-8601 format - `YYYY-MM-DDThh:mm:ss.SSSZ`.
          example: '2017-01-10T16:44:48.646Z'
          readOnly: true
    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
    PaymentLinksForSearch:
      type: object
      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'
    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
    PaymentEventLink:
      type: object
      description: Resource link for a payment of a payment event
      properties:
        payment_url:
          $ref: '#/components/schemas/Link'
    ExternalMetadata:
      type: object
      example: '{"property1": "value1", "property2": "value2"}"'
      properties:
        metadata:
          type: object
          additionalProperties:
            type: object
    CreateCardPaymentRequest:
      type: object
      description: The create payment request body
      properties:
        agreement_id:
          type: string
          description: The unique ID GOV.UK Pay automatically associated with a recurring payments agreement. Including `agreement_id` in your request tells the API to take this payment using the card details that are associated with this agreement. `agreement_id` must match an active agreement ID. You must set `authorisation_mode` to `agreement` for the API to accept `agreement_id`.
          example: abcefghjklmnopqr1234567890
          maxLength: 26
          minLength: 26
        agreement_payment_type:
          type: string
          description: When a standing order agreement transaction is initiated we have to include an initiated reason attribute.This can have a value of `instalment`, `recurring`, or `unscheduled`.We must have a `set_up_agreement` property or you set `authorisation_mode` to `agreement` for the API to accept the AgreementPaymentType.
          enum:
          - instalment
          - recurring
          - unscheduled
        amount:
          type: integer
          format: int32
          description: Sets the amount the user will pay, in pence.
          example: 12000
          maximum: 10000000
          minimum: 0
        authorisation_mode:
          type: string
          description: Sets how you intend to authorise the payment. Defaults to `web`. Payments created with `web` mode follow the [standard GOV.UK Pay payment journey](https://docs.payments.service.gov.uk/payment_flow/). Paying users visit the `next_url` in the response to complete their payment. Payments created with `agreement` mode are authorised with an agreement for recurring payments. If you create an `agreement` payment, you must also send an active `agreement_id`. You must not send `return_url`, `email`, or `prefilled_cardholder_details` or your request will fail. Payments created with `moto_api` mode return an `auth_url_post` object and a `one_time_token`. You can use `auth_url_post` and `one_time_token` to send the paying user’s card details through the API and complete the payment. If you create a `moto_api` payment, do not send a `return_url` in your request.
          enum:
          - web
          - agreement
          - moto_api
        delayed_capture:
          type: boolean
          description: You can use this parameter to [delay taking a payment from the paying user’s bank account](https://docs.payments.service.gov.uk/delayed_capture/#delay-taking-a-payment). For example, you might want to do your own anti-fraud checks on payments, or check that users are eligible for your service. Defaults to `false`.
          example: false
        description:
          type: string
          description: A human-readable description of the payment you’re creating. Paying users see this description on the payment pages. Service staff see the description in the GOV.UK Pay admin tool
          example: New passport application
          maxLength: 255
          minLength: 0
        email:
          type: string
          description: email
          example: Joe.Bogs@example.org
        language:
          type: string
          description: '[Sets the language of the user’s payment page](https://docs.payments.service.gov.uk/optional_features/welsh_language) with an ISO-6391 Alpha-2 code of a supported language.'
          enum:
          - en
          - cy
          example: en
        metadata:
          $ref: '#/components/schemas/ExternalMetadata'
        moto:
          type: boolean
          description: You can use this parameter to [designate a payment as a Mail Order / Telephone Order (MOTO) payment](https://docs.payments.service.gov.uk/moto_payments).
          example: false
        prefilled_cardholder_details:
          $ref: '#/components/schemas/PrefilledCardholderDetails'
        reference:
          type: string
          description: Associate a reference with this payment. `reference` is not unique - multiple payments can have identical `reference` values.
          example: '12345'
          maxLength: 255
          minLength: 0
        return_url:
          type: string
          description: The URL [the paying user is directed to after their payment journey on GOV.UK Pay ends](https://docs.payments.service.gov.uk/making_payments/#choose-the-return-url-and-match-your-users-to-payments).
          example: https://service-name.gov.uk/transactions/12345
          maxLength: 2000
          minLength: 0
        set_up_agreement:
          type: string
          description: Use this parameter to set up an existing agreement for recurring payments. The `set_up_agreement` value you send must be a valid `agreement_id`.
          example: abcefghjklmnopqr1234567890
          maxLength: 26
          minLength: 26
      required:
      - amount
      - description
      - reference
      - return_url
    Address:
      type: object
      description: A structure representing the billing address of a card
      properties:
        city:
          type: string
          description: The paying user's city.
          example: address city
          maxLength: 255
          minLength: 0
        country:
          type: string
          description: The paying user’s country, displayed as a 2-character ISO-3166-1-alpha-2 code.
          example: GB
        line1:
          type: string
          description: The first line of the paying user’s address.
          example: address line 1
          maxLength: 255
          minLength: 0
        line2:
          type: string
          description: The second line of the paying user’s address.
          example: address line 2
          maxLength: 255
          minLength: 0
        postcode:
          type: string
          description: The paying user's postcode.
          example: AB1 2CD
          maxLength: 25
          minLength: 0
    PaymentEvents:
      type: object
      description: A List of Payment Events information
      properties:
        _links:
          $ref: '#/components/schemas/PaymentLinksForEvents'
        events:
          type: array
          items:
            $ref: '#/components/schemas/PaymentEvent'
        payment_id:
          type: string
          description: The unique ID GOV.UK Pay automatically associated with this payment when you created it.
          example: hu20sqlact5260q2nanm0q8u93
          readOnly: true
    Exemption:
      type: object
      description: A structure representing that 3DS exemption was requested and the outcome of the exemption, if applicable.
      properties:
        outcome:
          $ref: '#/components/schemas/Outcome'
        requested:
          type: boolean
          description: Indicates whether an exemption was requested for the given payment.
          example: true
          readOnly: true
        type:
          type: string
          description: Indicates the type of exemption. Only present for corporate exemption
          example: corporate
          readOnly: true
    PaymentLinks:
      type: object
      description: links for payment
      properties:
        auth_url_post:
          $ref: '#/components/schemas/PostLink'
        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'
    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
    CardDetailsFromResponse:
      type: object
      properties:
        billing_address:
          $ref: '#/components/schemas/Address'
        card_brand:
          type: string
        card_type:
          type: string
        cardholder_name:
          type: string
        expiry_date:
          type: string
        first_digits_card_number:
          type: string
        last_digits_card_number:
          type: string
    ThreeDSecure:
      type: object
      description: Object containing information about the 3D Secure authentication of the payment.
      properties:
        required:
          type: boolean
          description: Indicates if this payment was authorised with 3D Secure authentication. `required` is `true` if the payment required 3D Secure authentication.
    CreatePaymentResult:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/PaymentLinks'
        amount:
          type: integer
          format: int64
          description: The amount, in pence, the user has paid or will pay. `amount` will match the value you sent in the request body.
          example: 1200
        card_details:
          $ref: '#/components/schemas/CardDetailsFromResponse'
        created_date:
          type: string
          description: The date you created the payment.
          example: '2016-01-21T17:15:00.000Z'
        delayed_capture:
          type: boolean
          description: '`delayed_capture` is `true` if you’re controlling [when GOV.UK Pay takes (‘captures’) the payment from the paying user’s bank account](https://docs.payments.service.gov.uk/delayed_capture).'
          example: false
          readOnly: true
        description:
          type: string
          description: The description you sent in the request body when creating this payment.
          example: New passport application
        email:
          type: string
          description: The paying user’s email address. The paying user’s email field will be prefilled with this value when they make their payment. `email` does not appear if you did not include it in the request body.
          example: citizen@example.org
        language:
          type: string
          description: The language of the user’s payment page.
          enum:
          - en
          - cy
          example: en
        metadata:
          $ref: '#/components/schemas/ExternalMetadata'
        moto:
          type: boolean
          description: Indicates if this payment is a [Mail Order / Telephone Order (MOTO) payment](https://docs.payments.service.gov.uk/moto_payments).
          example: false
        payment_id:
          type: string
          description: The unique ID GOV.UK Pay automatically associated with this payment when you created it.
          example: hu20sqlact5260q2nanm0q8u93
        payment_provider:
          type: string
          example: worldpay
        provider_id:
          type: string
          description: The reference number your payment service provider associated with the payment.
          example: 'null'
        reference:
          type: string
          description: The reference number you associated with this payment.
          example: '12345'
        refund_summary:
          $ref: '#/components/schemas/RefundSummary'
        return_url:
          type: string
          description: The URL you direct the paying user to after their payment journey on GOV.UK Pay ends.
          example: https://service-name.gov.uk/transactions/12345
        settlement_summary:
          $ref: '#/components/schemas/PaymentSettlementSummary'
        state:
          $ref: '#/components/schemas/PaymentState'
    Outcome:
      type: object
      description: A structure representing the outcome of a 3DS exemption, if known.
      properties:
        result:
          type: string
          description: The outcome of the requested exemption
          example: honoured
          readOnly: true
      readOnly: true
    PaymentDetailForSearch:
      type: object
      description: Contains payments matching your search criteria.
      properties:
        _links:
          $ref: '#/components/schemas/PaymentLinksForSearch'
        agreement_payment_type:
          type: string
          description: When the customer initiates a standing order agreement transaction we have to include a customerInitiatedReason attribute. This can have a value of `instalment`, `recurring`, or `unscheduled`.
          enum:
          - instalment
          - recurring
          - unscheduled
        amount:
          type: integer
          format: int64
          description: The description assigned to the payment when it was created.
          example: 1200
        authorisation_mode:
          type: string
          description: How the payment will be authorised. Payments created in `web` mode require the paying user to visit the `next_url` to complete the payment.
          enum:
          - web
          - moto_api
          - external
        authorisation_summary:
          $ref: '#/components/schemas/AuthorisationSummary'
        card_brand:
          type: string
          deprecated: true
          description: This attribute is deprecated. Please use `card_details.card_brand` instead.
          example: Visa
          readOnly: true
        card_details:
          $ref: '#/components/schemas/CardDetails'
        corporate_card_surcharge:
          type: integer
          format: int64
          description: The [corporate card surcharge](https://docs.payments.service.gov.uk/corporate_card_surcharges/#add-corporate-card-fees) amount in pence.
          example: 250
          readOnly: true
        created_date:
          type: string
          example: '2016-01-21T17:15:00.000Z'
          readOnly: true
        delayed_capture:
          type: boolean
          description: '`delayed_capture` is `true` if you’re [controlling how long it takes GOV.UK Pay to take (‘capture’) a payment](https://docs.payments.service.gov.uk/delayed_capture).'
          example: false
          readOnly: true
        description:
          type: string
          description: The description assigned to the payment when it was created.
          example: Your Service Description
        email:
          type: string
          example: The paying user’s email address.
        exemption:
          $ref: '#/components/schemas/Exemption'
        fee:
          type: integer
          format: int64
          description: The [payment service provider’s (PSP) transaction fee](https://docs.payments.service.gov.uk/reporting/#psp-fees), in pence. `fee` only appears when we have taken (‘captured’) the payment from the user or if their payment fails after they submitted their card details. `fee` will not appear if your PSP is Worldpay or you are using an API key from a test service.
          example: 5
          readOnly: true
        language:
          type: string
          description: The ISO-6391 Alpha-2 code of the [language of the user's payment page](https://docs.payments.service.gov.uk/optional_features/welsh_language).
          enum:
          - en
          - cy
          example: en
        metadata:
          $ref: '#/components/schemas/ExternalMetadata'
        moto:
          type: boolean
          description: Indicates if this payment is a [Mail Order / Telephone Order (MOTO) payment](https://docs.payments.service.gov.uk/moto_payments).
          example: false
        net_amount:
          type: integer
          format: int64
          description: The amount, in pence, that will be paid into your bank account after your payment service provider takes the `fee`.
          example: 1195
          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
        payment_provider:
          type: string
          description: The payment service provider that processed this payment.
          example: worldpay
          readOnly: true
        provider_id:
          type: string
          description: The unique ID your payment service provider generated for this payment. This is not the same as the `payment_id`.
          example: reference-from-payment-gateway
          readOnly: true
        reference:
          type: string
          description: The reference associated with the payment when it was created. `reference` is not unique - multiple payments can have the same `reference` value.
          example: your-reference
        refund_summary:
          $ref: '#/components/schemas/RefundSummary'
        return_url:
          type: string
          description: The URL you direct the paying user to after their payment journey on GOV.UK Pay ends.
          example: http://your.service.domain/your-reference
          readOnly: true
        settlement_summary:
          $ref: '#/components/schemas/PaymentSettlementSummary'
        state:
          $ref: '#/components/schemas/PaymentState'
        total_amount:
          type: integer
          format: int64
          description: Amount your user paid in pence, including corporate card fees. `total_amount` only appears if you [added a corporate card surcharge to the payment](https://docs.payments.service.gov.uk/corporate_card_surcharges/#add-corporate-card-fees).
          example: 1450
          readOnly: true
  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