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 Authorise card payments API
  version: 1.0.3
servers:
- url: https://publicapi.payments.service.gov.uk
tags:
- name: Authorise card payments
paths:
  /v1/auth:
    post:
      description: You can use this endpoint to [authorise payments](https://docs.payments.service.gov.uk/moto_payments/moto_send_card_details_api/) you have created with `authorisation_mode` set to `moto_api`.
      operationId: Authorise a MOTO payment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorisationRequest'
        required: true
      responses:
        '204':
          description: Your authorisation request was successful.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: Your request is invalid. Check the `code` and `description` in the response to find out why your request failed.
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: The `card_number` you sent is not a valid card number or you chose not to accept this card type. Check the `code` and `description` fields in the response to find out why your request failed.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: A value you sent is invalid or missing. Check the `code` and `description` in the response to find out why your request failed.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: There is something wrong with GOV.UK Pay. If there are no issues on our status page (https://payments.statuspage.io), you can contact us with your error code and we'll investigate.
      summary: Send card details to authorise a MOTO payment
      tags:
      - Authorise card payments
components:
  schemas:
    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
    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
    AuthorisationRequest:
      type: object
      description: Contains the user's payment information. This information will be sent to the payment service provider to authorise the payment.
      properties:
        card_number:
          type: string
          description: The full card number from the paying user's card.
          example: '4242424242424242'
          maxLength: 19
          minLength: 12
        cardholder_name:
          type: string
          description: The name on the paying user's card.
          example: J. Citizen
          maxLength: 255
          minLength: 0
        cvc:
          type: string
          description: The card verification code (CVC) or card verification value (CVV) on the paying user's card.
          example: '123'
          maxLength: 4
          minLength: 3
        expiry_date:
          type: string
          description: The expiry date of the paying user's card. This value must be in `MM/YY` format.
          example: 09/22
          maxLength: 5
          minLength: 5
        one_time_token:
          type: string
          description: This single use token authorises your request and matches it to a payment. GOV.UK Pay generated the `one_time_token` when the payment was created.
          example: 12345-edsfr-6789-gtyu
          minLength: 1
      required:
      - card_number
      - cardholder_name
      - cvc
      - expiry_date
      - one_time_token
  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