openapi: 3.0.2
servers:
  - url: https://api.sandbox.primer.io
  - url: https://api.primer.io
info:
  x-logo:
    url: https://apidocs.primer.io/docs/assets/images/primer-logo.svg
  title: Primer API
  version: '2.4'
  description: >-
    This API enforces a timeout of 90 seconds for all requests. A 504 response indicates
    a timeout occurred.

x-readme:
  explorer-enabled: true
  samples-languages: [curl, javascript, python, kotlin, swift]
  headers: [{key: X-API-VERSION, value: '2.4'}]
security:
  - ApiKeyAuth: []

tags:
  - name: Client Session API
  - name: Payments API
  - name: Payment Methods API
  - name: Observability API (beta)

paths:
  /client-session:
    post:
      tags:
        - Client Session API
      summary: Create a client session
      description: |
        Creating a client session generates a client token: a temporary key used to initialize [Universal Checkout](/docs/get-started/set-up-a-checkout) and authenticate it against your account.

        Universal Checkout automatically retrieves all the settings from the client session and the Dashboard to configure the payment methods and the checkout experience.

        <b>Note:</b>
        When creating a Client Session, please make sure to provide `currencyCode`, `orderId`, and at least one of `amount` or `lineItems`. 
        If any of these are not yet available, you can provide them when making the payment request.

        <code>POST /client-session</code> does not have required fields as all fields are not always known when a client session is created. 
        Use <code>PATCH /client-session</code> to update the parameters throughout the checkout session.

        Client tokens expire after 24 hours.

      operationId: create_client_side_token_client_session_post
      parameters:
        - $ref: '#/components/parameters/ApiVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientSessionAPIRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientSessionWithTokenAPIResponse'
        '400':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400ErrorResponse'
              examples:
                ClientSessionValidationError:
                  summary: The client token is invalid.
                  value:
                    error:
                      errorId: ClientSessionValidationError
                      description: The client token is invalid.
                      recoverySuggestion: Please provide a valid client token.
                      diagnosticsId: '1234567898'
                MetadataContainsEmptyKey:
                  summary: Metadata field contains empty string key.
                  value:
                    error:
                      errorId: MetadataContainsEmptyKey
                      description: Metadata field contains empty string key.
                      recoverySuggestion: >-
                        Either remove empty string keys or provide non-empty string
                        instead.
                      diagnosticsId: '1234567898'
        '422':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
              example:
                error:
                  errorId: RequestValidationError
                  description: >-
                    We were unable to validate your request, please check your payload
                    against /docs/api
                  diagnosticsId: '1234567898'
                  validationErrors: [{model: ClientSessionAPIRequest, errors: [{
                                path: $.customerId, description: Value must be a
                                valid string}]}]
    get:
      tags:
        - Client Session API
      summary: Retrieve a client session
      description: |
        This API call retrieves all the details associated with the client session corresponding to the client token that is provided in the request. The fields with empty values are excluded from the response.

      operationId: retrieve_client_side_token_client_session_get
      parameters:
        - description: Client token corresponding to the client session to 
            retrieve
          schema:
            title: Client Token
            type: string
            description: Client token
          name: clientToken
          in: query
        - $ref: '#/components/parameters/ApiVersionHeader'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientSessionAPIResponse'
        '400':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400ErrorResponse'
        '422':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
    patch:
      tags:
        - Client Session API
      summary: Update client session
      description: |
        You can update a clients session created earlier with the `PATCH /client-session` [API call](#operation/create_client_side_token_client_session_post).

        The only required field for the request is `clientToken`. Other supported request fields are same as for the `POST /client-session` [API call](#operation/create_client_side_token_client_session_post).

        You need to specify only the fields you wish to update. However, if the items to be updated are arrays (e.g.`lineItems`), you need to provide the entire array, including any new or modified items. Primer will replace the full array with whatever is sent in the request. If you want to keep existing items, make sure to include them in your request, anything omitted will be removed.

        If you wish to update nested fields on the client session, such as the customer `emailAddress` field, you can pass the `customer` object with only one field, `emailAddress`, to update.

        If you simply wish to clear the value of the field, pass `null` as your input.

        You can update `paymentMethod.vaultOnSuccess` field but updating of the `paymentMethod.options` field through `PATCH /client-session` is not supported.

        The response will contain all the fields of the client session including the ones that were changed.

      operationId: update_client_side_token_client_session_patch
      parameters:
        - $ref: '#/components/parameters/ApiVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientSessionUpdateAPIRequest'
              title: Request
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientSessionAPIResponse'
        '400':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400ErrorResponse'
              examples:
                ClientSessionValidationError:
                  summary: The client token is invalid.
                  value:
                    error:
                      errorId: ClientSessionValidationError
                      description: The client token is invalid.
                      recoverySuggestion: Please provide a valid client token.
                      diagnosticsId: '1234567898'
                MetadataContainsEmptyKey:
                  summary: Metadata field contains empty string key.
                  value:
                    error:
                      errorId: MetadataContainsEmptyKey
                      description: Metadata field contains empty string key.
                      recoverySuggestion: >-
                        Either remove empty string keys or provide non-empty string
                        instead.
                      diagnosticsId: '1234567898'
        '422':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'

  /payments:
    get:
      tags:
        - Payments API
      summary: Search & list payments
      description: |
        <p/>

        Retrieve a list of your payments.

        Results are paginated, they will only return up to 100 payments maximum.
        To access the next page of result, set the `cursor` query parameter to the value of `nextCursor` in
        your current result payload. Use `prevCursor` to go back to the previous page.

        **Note:** this endpoint returns a list of
        summarized payments. Not all payments attributes are present. You can use
        the query parameters to filter payments. You can separate multiple query parameters with the `&` symbol.
        Query parameters with types of the form "Array of strings" (such as the status parameter) can be specified as a comma-separated list.

        For example, if you wanted to get both `FAILED`  and `CANCELLED` payments, for customer `john-123`, you would use:
        ```bash
        curl --location --request GET 'https://api.primer.io/payments?status=FAILED,CANCELLED&customer_id=john-123' \
        --header 'X-Api-Key: <YOUR_API_KEY>'
        ```

        You can alternatively specify a list by repeating the parameter multiple times.

        **Note:** payments will be available within a minute from being created.

      operationId: list_payments_payments_get
      parameters:
        - description: Filter payments by their status.
          required: false
          schema:
            title: Payment status
            type: array
            items:
              $ref: '#/components/schemas/PaymentStatus'
            description: Filter payments by their status.
          name: status
          in: query
        - description: Filter payments by their payment method type.
          required: false
          schema:
            title: Payment method type
            type: array
            items:
              $ref: '#/components/schemas/PaymentMethodTypeEnum'
            description: Filter payments by their payment method type.
          name: payment_method_type
          in: query
        - description: Filter payments by their payment processor.
          required: false
          schema:
            title: Payment processor
            type: array
            items:
              type: string
            description: Filter payments by their payment processor.
          name: processor
          in: query
        - description: |
            Filter payments by their payment currency.
            e.g. use `USD` for US dollars.
          required: false
          schema:
            title: Payment currency
            type: array
            items:
              type: string
            description: |
              Filter payments by their payment currency.

              Use the 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).
              e.g. use `USD` for US dollars."
          name: currency_code
          in: query
        - description: Return only payments from this date (inclusive).
          required: false
          schema:
            title: Payment date
            type: string
            description: Return only payments from this date (inclusive).
            format: date-time
          name: from_date
          in: query
        - description: Return only payments up to this date (inclusive).
          required: false
          schema:
            title: Payment date
            type: string
            description: Return only payments up to this date (inclusive).
            format: date-time
          name: to_date
          in: query
        - description: Return payments related to this order ID.
          required: false
          schema:
            title: Payment order ID
            type: string
            description: Return payments related to this order ID.
          name: order_id
          in: query
        - description: Return payments of this amount minimum (inclusive).
          required: false
          schema:
            title: Payment amount
            type: integer
            format: int64
            description: Return payments of this amount minimum (inclusive).
          name: min_amount
          in: query
        - description: Return payments of this amount max (inclusive).
          required: false
          schema:
            title: Payment amount
            type: integer
            format: int64
            description: Return payments of this amount max (inclusive).
          name: max_amount
          in: query
        - description: ID of the customer that has made the payment.
          required: false
          schema:
            title: Customer ID
            type: array
            items:
              type: string
            description: ID of the customer that has made the payment.
          name: customer_id
          in: query
        - description: ID of the merchant involved in the payment.
          required: false
          schema:
            title: Merchant ID
            type: array
            items:
              type: string
            description: ID of the merchant involved in the payment.
          name: merchant_id
          in: query
        - description: Email of the customer that has made the payment.
          required: false
          schema:
            title: Customer email address
            type: array
            items:
              type: string
            description: Email of the customer that has made the payment.
          name: customer_email_address
          in: query
        - description: Last 4 digits of the card used for the payment.
          required: false
          schema:
            title: Last 4 digits
            type: array
            items:
              type: string
            description: Last 4 digits of the card used for the payment.
          name: last_4_digits
          in: query
        - description: Paypal email address associated with the payment.
          required: false
          schema:
            title: Paypal email
            type: array
            items:
              type: string
            description: Paypal email address associated with the payment.
          name: paypal_email
          in: query
        - description: Klarna email address associated with the payment.
          required: false
          schema:
            title: Klarna email
            type: array
            items:
              type: string
            description: Klarna email address associated with the payment.
          name: klarna_email
          in: query
        - description: Maximum number of payments to return per page.
          required: false
          schema:
            title: Limit result set
            maximum: 100.0
            minimum: 1.0
            type: integer
            format: int64
            description: Maximum number of payments to return per page.
            default: 100
          name: limit
          in: query
        - description: >-
            If results are paginated, pass the `nextCursor` to access next page.
          required: false
          schema:
            title: Page cursor
            type: string
            description: >-
              If results are paginated, pass the `nextCursor` to access next page.
          name: cursor
          in: query
        - $ref: '#/components/parameters/ApiVersionHeader'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentListAPIResponse'
        '422':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
              example:
                error:
                  errorId: RequestValidationError
                  description: Invalid type for `currencyCode`
                  recoverySuggestion: The currency code must be a valid value
                  diagnosticsId: '1234567898'
    post:
      tags:
        - Payments API
      summary: Create a payment
      description: |
        <p/>

        Create and authorize a payment for a given customer order. You
        should provide a payment method token here to avoid PCI implications.

        If only a payment method token is passed, the values passed with the Client Session is used to determine the amount, currency etc.
        Note: `amount`, `currencyCode` and `orderId` are required during payment creation. Make sure to pass these fields when creating a client session, or if not yet available, when creating a payment.

        All fields provided on this request will take preference over any field on the `order` associated with the client session. E.g. if you pass `amount` on this request, it will override the `amount` on the `order` associated with the Client Session.
        Parameters that are not on this request will be fetched from previously created Client Session and merged. E.g. if you specify `customer.billingAddress` in Client Session and then pass `customer.emailAddress` data with this request, it will automatically merge the `customer` fields and use both `billingAddress` and `emailAddress` for later calculations.

      operationId: create_payment_payments_post
      parameters:
        - $ref: '#/components/parameters/IdempotencyHeader'
        - $ref: '#/components/parameters/ApiVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCreationAPIRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentAPIResponse'
              example:
                id: kHdEw9EG
                date: '2021-02-21T15:36:16.367687'
                dateUpdated: '2021-02-21T15:36:17.133701'
                status: AUTHORIZED
                orderId: order-abc
                currencyCode: EUR
                amount: 42
                customerId: customer-123
                customer:
                  email: customer123@gmail.com
                cardTokenType: CARD_PAN
                paymentMethod:
                  paymentType: SUBSCRIPTION
                  paymentMethodToken: heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4
                  isVaulted: true
                  authorizationType: FINAL
                  descriptor: 'Purchase: Socks'
                  analyticsId: VtkMDAxZW5isH0HsbbNxZ3lo
                  paymentMethodType: PAYMENT_CARD
                  paymentMethodData:
                    first6Digits: '411111'
                    last4Digits: '1111'
                    expirationMonth: '12'
                    expirationYear: '2030'
                    cardholderName: John Biggins
                    network: Visa
                    isNetworkTokenized: false
                    binData:
                      network: VISA
                      regionalRestriction: UNKNOWN
                      accountNumberType: UNKNOWN
                      accountFundingType: UNKNOWN
                      prepaidReloadableIndicator: NOT_APPLICABLE
                      productUsageType: UNKNOWN
                      productCode: VISA
                      productName: VISA
                processor:
                  name: STRIPE
                  processorMerchantId: acct_stripe_1234
                  amountCaptured: 0
                  amountRefunded: 0
                transactions:
                  - type: SALE
                    processorStatus: AUTHORIZED
                    processorName: STRIPE
                    processorMerchantId: acct_stripe_1234
                    processorTransactionId: 54c4eb5b3ef8a
                    cardTokenType: CARD_PAN
                metadata:
                  productId: 123
                  merchantId: a13bsd62s
                riskData:
                  fraudChecks:
                    source: FRAUD_PROVIDER
                    preAuthorizationResult: THREE_DS
                    postAuthorizationResult: ACCEPT
                  cvvCheck:
                    source: PROCESSOR
                    result: MATCHED
                  avsCheck:
                    source: PROCESSOR
                    result:
                      streetAddress: NOT_MATCHED
                      postalCode: NOT_VERIFIED
        '400':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400ErrorResponse'
              examples:
                GenericError:
                  value:
                    error:
                      errorId: PaymentError
                      description: The payment could not be created.
                      diagnosticsId: '1234567898'
                IdempotencyError:
                  value:
                    error:
                      errorId: TransactionRequestIdempotencyKeyAlreadyExists
                      description: >-
                        Transaction request already exists with idempotency key 'IDEMPOTENCY_KEY'.
                      paymentId: 6gHJtooK6
                      paymentStatus: SETTLED
                      diagnosticsId: '1234567898'
                      validationErrors: []
                MetadataContainsEmptyKey:
                  summary: Metadata field contains empty string key.
                  value:
                    error:
                      errorId: MetadataContainsEmptyKey
                      description: Metadata field contains empty string key.
                      recoverySuggestion: >-
                        Either remove empty string keys or provide non-empty string
                        instead.
                      diagnosticsId: '1234567898'
        '422':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
              example:
                error:
                  errorId: RequestValidationError
                  description: Missing fields for payment.
                  recoverySuggestion: >-
                    When creating a payment `amount` must either be provided via the
                    Client Session or the Payment request.
                  diagnosticsId: '1234567898'
  /payments/{id}/authorize:
    post:
      tags:
        - Payments API
      summary: Authorize a payment
      description: |
        <p/>

        Manually authorize a payment using a provided processor. This is useful if you want to authorize a payment without a workflow action.
        The processor merchant ID must be provided which can be found on the [Integrations page](https://dashboard.primer.io/integrations).
        The processor name is optional but it must be provided if your account has multiple processors configured which share the same merchant IDs.
      operationId: authorize_payment_payments__id__authorize_post
      parameters:
        - required: true
          schema:
            title: Payment ID
            type: string
          name: id
          description: ID of the payment to authorize.
          in: path
        - $ref: '#/components/parameters/IdempotencyHeader'
        - $ref: '#/components/parameters/ApiVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentAuthorizationAPIRequest'
            example:
              processor:
                processorMerchantId: acct_myprocessor_1234
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentAPIResponse'
              example:
                id: kHdEw9EG
                date: '2021-02-21T15:36:16.367687'
                dateUpdated: '2021-02-21T15:36:17.133701'
                status: AUTHORIZED
                orderId: order-abc
                customerId: customer-123
                currencyCode: EUR
                amount: 42
                cardTokenType: CARD_PAN
                paymentMethod:
                  paymentType: SUBSCRIPTION
                  paymentMethodToken: heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4
                  isVaulted: true
                  authorizationType: FINAL
                  descriptor: 'Purchase: Socks'
                  analyticsId: VtkMDAxZW5isH0HsbbNxZ3lo
                  paymentMethodType: PAYMENT_CARD
                  paymentMethodData:
                    first6Digits: '411111'
                    last4Digits: '1111'
                    expirationMonth: '12'
                    expirationYear: '2030'
                    cardholderName: John Biggins
                    network: Visa
                    isNetworkTokenized: false
                    binData:
                      network: VISA
                      regionalRestriction: UNKNOWN
                      accountNumberType: UNKNOWN
                      accountFundingType: UNKNOWN
                      prepaidReloadableIndicator: NOT_APPLICABLE
                      productUsageType: UNKNOWN
                      productCode: VISA
                      productName: VISA
                processor:
                  name: MYPROCESSOR
                  processorMerchantId: acct_myprocessor_1234
                  amountCaptured: 42
                  amountRefunded: 0
                customer:
                  email: customer123@gmail.com
                metadata:
                  productId: 123
                  merchantId: a13bsd62s
                transactions:
                  - type: SALE
                    processorStatus: AUTHORIZED
                    processorName: MYPROCESSOR
                    processorMerchantId: acct_myprocessor_1234
                    processorTransactionId: 54c4eb5b3ef8a
                    cardTokenType: CARD_PAN
                riskData:
                  fraudChecks:
                    source: FRAUD_PROVIDER
                    preAuthorizationResult: THREE_DS
                    postAuthorizationResult: ACCEPT
                  cvvCheck:
                    source: PROCESSOR
                    result: MATCHED
                  avsCheck:
                    source: PROCESSOR
                    result:
                      streetAddress: NOT_MATCHED
                      postalCode: NOT_VERIFIED
        '400':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400ErrorResponse'
              examples:
                PaymentAlreadyAuthorized:
                  value:
                    error:
                      errorId: PaymentAlreadyAuthorized
                      description: The payment has already been authorized
                      diagnosticsId: '1234567898'
                InvalidPaymentStatus:
                  value:
                    error:
                      errorId: InvalidPaymentStatus
                      description: A settled payment cannot be authorized
                      diagnosticsId: '1234567898'
                MerchantAccountNotFound:
                  value:
                    error:
                      errorId: MerchantAccountNotFound
                      description: The merchant account could not be found
                      diagnosticsId: '1234567898'
                MerchantAccountConflict:
                  value:
                    error:
                      errorId: MerchantAccountConflict
                      description: >-
                        More than one merchant account was found for the provided
                        processor merchant ID
                      diagnosticsId: '1234567898'
        '404':
          description: Payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404ErrorResponse'
              example:
                error:
                  errorId: PaymentNotFoundError
                  description: The payment could not be found
                  diagnosticsId: '1234567898'
                  validationErrors: []
        '409':
          description: Idempotency key already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/409ErrorResponse'
              example:
                error:
                  errorId: IdempotencyKeyAlreadyExists
                  description: >-
                    The idempotency key "1234567898" already exists for transaction
                  diagnosticsId: '1234567898'
        '422':
          description: Request failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
              example:
                error:
                  errorId: RequestValidationError
                  description: >-
                    We were unable to validate your request, please check your payload
                    against /docs/api
                  diagnosticsId: '1234567898'
                  validationErrors:
                    - model: PaymentAuthorizationAPIRequest
                      errors:
                        - path: $.processor.processorMerchantId
                          description: Value must be a valid string
  /payments/{id}/capture:
    post:
      tags:
        - Payments API
      summary: Capture a payment
      description: |
        <p/>

        If you have successfully authorized a payment, you can now
        fully capture, or partially capture funds from the authorized payment, depending
        on whether your selected payment processor supports it. The payment will
        be updated to `SETTLED` or `SETTLING`, depending on the payment method type.

        The payload sent in this capture request is completely optional. If you don't
        send a payload with the capture request, the full amount that was authorized
        will be sent for capture. Below are the available payload attributes, which
        give you more granular control when capturing funds, if you require it.
      operationId: capture_payment_payments__id__capture_post
      parameters:
        - required: true
          schema:
            title: Payment ID
            type: string
          name: id
          description: ID of the payment to capture.
          in: path
        - $ref: '#/components/parameters/IdempotencyHeader'
        - $ref: '#/components/parameters/ApiVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCaptureAPIRequest'
              title: Data
              default:
                final: true
            examples:
              Basic:
                value:
                  amount: 42
              Using Metadata:
                value:
                  amount: 42
                  metadata:
                    extraField: Text value
              Using Expand:
                value:
                  amount: 42
                  expand:
                    - transactions.events
              Final Capture:
                value:
                  amount: 42
                  final: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentAPIResponse'
              example:
                id: kHdEw9EG
                date: '2021-02-21T15:36:16.367687'
                dateUpdated: '2021-02-21T15:36:17.133701'
                status: SETTLED
                orderId: order-abc
                customerId: customer-123
                currencyCode: EUR
                amount: 42
                cardTokenType: CARD_PAN
                paymentMethod:
                  paymentType: SUBSCRIPTION
                  paymentMethodToken: heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4
                  isVaulted: true
                  authorizationType: FINAL
                  descriptor: 'Purchase: Socks'
                  analyticsId: VtkMDAxZW5isH0HsbbNxZ3lo
                  paymentMethodType: PAYMENT_CARD
                  paymentMethodData:
                    first6Digits: '411111'
                    last4Digits: '1111'
                    expirationMonth: '12'
                    expirationYear: '2030'
                    cardholderName: John Biggins
                    network: Visa
                    isNetworkTokenized: false
                    binData:
                      network: VISA
                      regionalRestriction: UNKNOWN
                      accountNumberType: UNKNOWN
                      accountFundingType: UNKNOWN
                      prepaidReloadableIndicator: NOT_APPLICABLE
                      productUsageType: UNKNOWN
                      productCode: VISA
                      productName: VISA
                processor:
                  name: STRIPE
                  processorMerchantId: acct_stripe_1234
                  amountCaptured: 42
                  amountRefunded: 0
                transactions:
                  - type: SALE
                    processorStatus: SETTLED
                    processorName: STRIPE
                    processorMerchantId: acct_stripe_1234
                    processorTransactionId: 54c4eb5b3ef8a
                    cardTokenType: CARD_PAN
                customer:
                  email: customer123@gmail.com
                metadata:
                  productId: 123
                  merchantId: a13bsd62s
                riskData:
                  fraudChecks:
                    source: FRAUD_PROVIDER
                    preAuthorizationResult: THREE_DS
                    postAuthorizationResult: ACCEPT
                  cvvCheck:
                    source: PROCESSOR
                    result: MATCHED
                  avsCheck:
                    source: PROCESSOR
                    result:
                      streetAddress: NOT_MATCHED
                      postalCode: NOT_VERIFIED
        '400':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400ErrorResponse'
              example:
                error:
                  errorId: PaymentError
                  description: The payment could not be found
                  diagnosticsId: '1234567898'
        '409':
          description: Idempotency key already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/409ErrorResponse'
              example:
                error:
                  errorId: IdempotencyKeyAlreadyExists
                  description: >-
                    The idempotency key "1234567898" already exists for transaction
                  diagnosticsId: '1234567898'
                  paymentId: gg3r3tsa3
                  paymentStatus: SETTLED
        '422':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
              example:
                error:
                  errorId: RequestValidationError
                  description: >-
                    We were unable to validate your request, please check your payload
                    against /docs/api
                  diagnosticsId: '1234567898'
                  validationErrors: [{model: PaymentCaptureAPIRequest, errors: [{
                              path: $.amount, description: Value must be a valid
                                integer}]}]
  /payments/{id}/cancel:
    post:
      tags:
        - Payments API
      summary: Cancel a payment
      description: |
        <p/>

        Provided the payment has not reached `SETTLED` status, Primer will
        send a "void" request to the payment processor, thereby cancelling the payment
        and releasing the hold on customer funds. Upon success, the payment will transition
        to `CANCELLED`. The payload is optional.

      operationId: cancel_payment_payments__id__cancel_post
      parameters:
        - required: true
          schema:
            title: Payment ID
            type: string
          name: id
          description: ID of payment to cancel.
          in: path
        - $ref: '#/components/parameters/IdempotencyHeader'
        - $ref: '#/components/parameters/ApiVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCancelAPIRequest'
              title: Data
              default: {}
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentAPIResponse'
              example:
                id: kHdEw9EG
                date: '2021-02-21T15:36:16.367687'
                dateUpdated: '2021-02-21T15:36:17.133701'
                status: CANCELLED
                orderId: order-abc
                customerId: customer-123
                currencyCode: EUR
                amount: 42
                cardTokenType: CARD_PAN
                paymentMethod:
                  paymentType: SUBSCRIPTION
                  paymentMethodToken: heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4
                  isVaulted: true
                  authorizationType: FINAL
                  descriptor: 'Purchase: Socks'
                  analyticsId: VtkMDAxZW5isH0HsbbNxZ3lo
                  paymentMethodType: PAYMENT_CARD
                  paymentMethodData:
                    first6Digits: '411111'
                    last4Digits: '1111'
                    expirationMonth: '12'
                    expirationYear: '2030'
                    cardholderName: John Biggins
                    network: Visa
                    isNetworkTokenized: false
                    binData:
                      network: VISA
                      regionalRestriction: UNKNOWN
                      accountNumberType: UNKNOWN
                      accountFundingType: UNKNOWN
                      prepaidReloadableIndicator: NOT_APPLICABLE
                      productUsageType: UNKNOWN
                      productCode: VISA
                      productName: VISA
                processor:
                  name: STRIPE
                  processorMerchantId: acct_stripe_1234
                  amountCaptured: 0
                  amountRefunded: 0
                transactions:
                  - type: SALE
                    processorStatus: CANCELLED
                    processorName: STRIPE
                    processorMerchantId: acct_stripe_1234
                    processorTransactionId: 54c4eb5b3ef8a
                    cardTokenType: CARD_PAN
                    reason: 'Customer returned order #1234.'
                customer:
                  email: customer123@gmail.com
                metadata:
                  productId: 123
                  merchantId: a13bsd62s
                riskData:
                  fraudChecks:
                    source: FRAUD_PROVIDER
                    preAuthorizationResult: THREE_DS
                    postAuthorizationResult: ACCEPT
                  cvvCheck:
                    source: PROCESSOR
                    result: MATCHED
                  avsCheck:
                    source: PROCESSOR
                    result:
                      streetAddress: NOT_MATCHED
                      postalCode: NOT_VERIFIED
        '400':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400ErrorResponse'
              example:
                error:
                  errorId: PaymentError
                  description: The payment could not be found
                  diagnosticsId: '1234567898'
        '409':
          description: Idempotency key already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/409ErrorResponse'
              example:
                error:
                  errorId: IdempotencyKeyAlreadyExists
                  description: >-
                    The idempotency key "1234567898" already exists for transaction
                  diagnosticsId: '1234567898'
                  paymentId: gg3r3tsa3
                  paymentStatus: SETTLED
  /payments/{id}/refund:
    post:
      tags:
        - Payments API
      summary: Refund a payment
      description: |
        <p/>

        Issue a full or partial refund for a previously settled payment. By default, the full amount
        will be refunded unless a specific amount is provided for a partial refund.

        If the payment was partially captured multiple times, you can specify which capture to
        refund by using the transaction event ID. Refer to the `transactions.events` array in the
        payment object to find available transaction event IDs (when the appropriate `expand`
        parameter is passed).

        When specifying a transaction event ID, the refund amount should not exceed the amount
        captured in that event. If no refund amount is provided, it defaults to the amount captured
        in that specific event.

      operationId: refund_payment_payments__id__refund_post
      parameters:
        - required: true
          schema:
            title: Payment ID
            type: string
          name: id
          description: ID of payment to refund.
          in: path
        - $ref: '#/components/parameters/IdempotencyHeader'
        - $ref: '#/components/parameters/ApiVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRefundAPIRequest'
              title: Data
              default: {}
            examples:
              Full Refund:
                value: {}
              Partial Refund:
                value:
                  amount: 42
              Partial Refund with Transaction Event:
                value:
                  transactionEventId: 493cde19-04f2-4913-b00b-71af806f4374
              Using Expand:
                value:
                  expand:
                    - transactions.events
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentAPIResponse'
              example:
                id: kHdEw9EG
                date: '2021-02-21T15:36:16.367687'
                dateUpdated: '2021-02-21T15:36:17.133701'
                status: SETTLED
                orderId: order-abc
                customerId: customer-123
                currencyCode: EUR
                amount: 42
                cardTokenType: CARD_PAN
                paymentMethod:
                  paymentType: SUBSCRIPTION
                  paymentMethodToken: heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4
                  isVaulted: true
                  authorizationType: FINAL
                  descriptor: 'Purchase: Socks'
                  analyticsId: VtkMDAxZW5isH0HsbbNxZ3lo
                  paymentMethodType: PAYMENT_CARD
                  paymentMethodData:
                    first6Digits: '411111'
                    last4Digits: '1111'
                    expirationMonth: '12'
                    expirationYear: '2030'
                    cardholderName: John Biggins
                    network: Visa
                    isNetworkTokenized: false
                    binData:
                      network: VISA
                      regionalRestriction: UNKNOWN
                      accountNumberType: UNKNOWN
                      accountFundingType: UNKNOWN
                      prepaidReloadableIndicator: NOT_APPLICABLE
                      productUsageType: UNKNOWN
                      productCode: VISA
                      productName: VISA
                processor:
                  name: STRIPE
                  processorMerchantId: acct_stripe_1234
                  amountCaptured: 42
                  amountRefunded: 42
                transactions:
                  - type: SALE
                    processorStatus: SETTLED
                    processorName: STRIPE
                    processorMerchantId: acct_stripe_1234
                    processorTransactionId: 54c4eb5b3ef8a
                    cardTokenType: CARD_PAN
                  - type: REFUND
                    processorStatus: SETTLED
                    processorName: STRIPE
                    processorMerchantId: acct_stripe_1234
                    processorTransactionId: 54c4eb5b3ef8a
                    reason: 'Customer returned order #1234.'
                customer:
                  email: customer123@gmail.com
                metadata:
                  productId: 123
                  merchantId: a13bsd62s
                riskData:
                  fraudChecks:
                    source: FRAUD_PROVIDER
                    preAuthorizationResult: THREE_DS
                    postAuthorizationResult: ACCEPT
                  cvvCheck:
                    source: PROCESSOR
                    result: MATCHED
                  avsCheck:
                    source: PROCESSOR
                    result:
                      streetAddress: NOT_MATCHED
                      postalCode: NOT_VERIFIED
        '400':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400ErrorResponse'
              example:
                error:
                  errorId: PaymentError
                  description: The payment could not be found
                  diagnosticsId: '1234567898'
        '409':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/409ErrorResponse'
              examples:
                IdempotencyKeyAlreadyExists:
                  summary: Idempotency key already exists
                  value:
                    error:
                      errorId: IdempotencyKeyAlreadyExists
                      description: >-
                        The idempotency key "1234567898" already exists for transaction
                      diagnosticsId: '1234567898'
                      paymentId: gg3r3tsa3
                      paymentStatus: SETTLED
                PaymentAlreadyRefunded:
                  summary: Payment already refunded
                  value:
                    error:
                      errorId: PaymentAlreadyRefunded
                      description: >-
                        Cannot refund this payment because the payment has already
                        been fully refunded.
                      diagnosticsId: '1234567898'
        '422':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
              examples:
                RequestValidationError:
                  summary: Request validation error
                  value:
                    error:
                      errorId: RequestValidationError
                      description: >-
                        We were unable to validate your request, please check your
                        payload against /docs/api
                      diagnosticsId: '1234567898'
                      validationErrors: [{model: PaymentCaptureAPIRequest, 
                              errors: [{path: $.amount, description: Value must 
                                    be a valid integer}]}]
                UnprocessableRefundAmount:
                  summary: Unprocessable refund amount
                  value:
                    error:
                      errorId: UnprocessableRefundAmount
                      description: >-
                        Cannot refund this payment with the amount 4201. The refund
                        amount must be less than or equal to the payment authorized
                        amount (4200).
                      diagnosticsId: '1234567898'
  /payments/{id}/resume:
    post:
      tags:
        - Payments API
      summary: Resume a payment
      description: |
        <p/>

        Resume a payment's workflow execution from a paused state. This
        is usually required when a Workflow was paused in order to get further information
        from the customer, or when waiting for an asynchronous response from a third
        party connection.

      operationId: resume_payment_payments__id__resume_post
      parameters:
        - required: true
          schema:
            title: Payment ID
            type: string
          name: id
          description: ID of payment to resume.
          in: path
        - $ref: '#/components/parameters/ApiVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentResumeAPIRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentAPIResponse'
              example:
                id: kHdEw9EG
                date: '2021-02-21T15:36:16.367687'
                dateUpdated: '2021-02-21T15:36:17.133701'
                status: AUTHORIZED
                orderId: order-abc
                customerId: customer-123
                currencyCode: EUR
                amount: 42
                cardTokenType: CARD_PAN
                paymentMethod:
                  paymentType: SUBSCRIPTION
                  paymentMethodToken: heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4
                  isVaulted: true
                  authorizationType: FINAL
                  descriptor: 'Purchase: Socks'
                  analyticsId: VtkMDAxZW5isH0HsbbNxZ3lo
                  paymentMethodType: PAYMENT_CARD
                  paymentMethodData:
                    first6Digits: '411111'
                    last4Digits: '1111'
                    expirationMonth: '12'
                    expirationYear: '2030'
                    cardholderName: John Biggins
                    network: Visa
                    isNetworkTokenized: false
                    binData:
                      network: VISA
                      regionalRestriction: UNKNOWN
                      accountNumberType: UNKNOWN
                      accountFundingType: UNKNOWN
                      prepaidReloadableIndicator: NOT_APPLICABLE
                      productUsageType: UNKNOWN
                      productCode: VISA
                      productName: VISA
                processor:
                  name: STRIPE
                  processorMerchantId: acct_stripe_1234
                  amountCaptured: 0
                  amountRefunded: 0
                transactions:
                  - type: SALE
                    processorStatus: AUTHORIZED
                    processorName: STRIPE
                    processorMerchantId: acct_stripe_1234
                    processorTransactionId: 54c4eb5b3ef8a
                    cardTokenType: CARD_PAN
                customer:
                  email: customer123@gmail.com
                metadata:
                  productId: 123
                  merchantId: a13bsd62s
                riskData:
                  fraudChecks:
                    source: FRAUD_PROVIDER
                    preAuthorizationResult: THREE_DS
                    postAuthorizationResult: ACCEPT
                  cvvCheck:
                    source: PROCESSOR
                    result: MATCHED
                  avsCheck:
                    source: PROCESSOR
                    result:
                      streetAddress: NOT_MATCHED
                      postalCode: NOT_VERIFIED
                      responses:
        '202':
          description: Accepted for Processing Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/202AcceptedResponse'
              example:
                error:
                  description: >-
                    The payment was not processed in time. Processing will continue
                    asynchronously.
                  diagnosticsId: '1234567898'
                  errorId: NoActionsToHandle
                  recoverySuggestion: Use GET /payments/:paymentId to get the 
                    state of the payment
        '400':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400ErrorResponse'
              example:
                error:
                  errorId: PaymentError
                  description: The payment could not be found
                  diagnosticsId: '1234567898'
  /payments/{id}/adjust-authorization:
    post:
      tags:
        - Payments API
      summary: Adjust authorized amount
      description: |
        <p/>

        Adjust authorized amount. This is only possible if `authorizationType` was set to 
        `ESTIMATED` when the payment was created, and the mechanism is supported by the payment method.

      operationId: adjust_authorization_payments__id__adjust_authorization_post
      parameters:
        - required: true
          schema:
            title: Payment ID
            type: string
          name: id
          description: ID of payment for adjusting authorization.
          in: path
        - $ref: '#/components/parameters/IdempotencyHeader'
        - $ref: '#/components/parameters/ApiVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentAdjustAuthorizationAPIRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentAPIResponse'
              example:
                id: kHdEw9EG
                date: '2021-02-21T15:36:16.367687'
                dateUpdated: '2021-02-21T15:36:17.133701'
                status: AUTHORIZED
                orderId: order-abc
                customerId: customer-123
                currencyCode: EUR
                amount: 42
                cardTokenType: CARD_PAN
                paymentMethod:
                  paymentMethodToken: heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4
                  authorizationType: ESTIMATED
                  isVaulted: true
                  descriptor: 'Purchase: Socks'
                  analyticsId: VtkMDAxZW5isH0HsbbNxZ3lo
                  paymentMethodType: PAYMENT_CARD
                  paymentMethodData:
                    first6Digits: '411111'
                    last4Digits: '1111'
                    expirationMonth: '12'
                    expirationYear: '2030'
                    cardholderName: John Biggins
                    network: Visa
                    isNetworkTokenized: false
                    binData:
                      network: VISA
                      regionalRestriction: UNKNOWN
                      accountNumberType: UNKNOWN
                      accountFundingType: UNKNOWN
                      prepaidReloadableIndicator: NOT_APPLICABLE
                      productUsageType: UNKNOWN
                      productCode: VISA
                      productName: VISA
                processor:
                  name: STRIPE
                  processorMerchantId: acct_stripe_1234
                  amountCaptured: 0
                  amountRefunded: 0
                transactions:
                  - type: SALE
                    processorStatus: AUTHORIZED
                    processorName: STRIPE
                    processorMerchantId: acct_stripe_1234
                    processorTransactionId: 54c4eb5b3ef8a
                    cardTokenType: CARD_PAN
                customer:
                  email: customer123@gmail.com
                metadata:
                  productId: 123
                  merchantId: a13bsd62s
                riskData:
                  fraudChecks:
                    source: FRAUD_PROVIDER
                    preAuthorizationResult: THREE_DS
                    postAuthorizationResult: ACCEPT
                  cvvCheck:
                    source: PROCESSOR
                    result: MATCHED
                  avsCheck:
                    source: PROCESSOR
                    result:
                      streetAddress: NOT_MATCHED
                      postalCode: NOT_VERIFIED
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400ErrorResponse'
              examples:
                IncorrectPaymentAuthorizationType:
                  summary: Incorrect authorization type
                  value:
                    error:
                      errorId: IncorrectPaymentAuthorizationType
                      description: >-
                        Adjust authorization is only allowed on payments where authorizationType
                        is set to estimated and not final.
                      diagnosticsId: '1234567898'
                PaymentIsNotAuthorized:
                  summary: Payment is not authorized
                  value:
                    error:
                      errorId: PaymentIsNotAuthorizedYet
                      description: Adjust Authorization is only allowed on 
                        authorized payments.
                      diagnosticsId: '1234567898'
                AdjustAuthorizationNonCardPayment:
                  summary: Adjust Authorization with non-card payment
                  value:
                    error:
                      errorId: AdjustAuthorizationNonCardPayment
                      description: Adjust Authorization is only available on 
                        card payments.
                      diagnosticsId: '1234567898'
                AdjustAuthorizationNotSupported:
                  summary: Processor doesn't support authorization adjust
                  value:
                    error:
                      errorId: AdjustAuthorizationNotSupported
                      description: Adjust Authorization for processor X is not 
                        supported.
                      diagnosticsId: '1234567898'
        '404':
          description: Payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404ErrorResponse'
              example:
                error:
                  errorId: EntityNotFound
                  description: No matching Payment could be found.
                  diagnosticsId: '1234567898'
                  validationErrors: []
        '409':
          description: Idempotency key already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/409ErrorResponse'
              example:
                error:
                  errorId: IdempotencyKeyAlreadyExists
                  description: >-
                    The idempotency key "1234567898" already exists for transaction
                  diagnosticsId: '1234567898'
                  paymentId: gg3r3tsa3
                  paymentStatus: SETTLED
        '422':
          description: Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
  /payments/{id}:
    get:
      tags:
        - Payments API
      summary: Get a payment
      description: |
        <p/>

        Retrieve a payment by its ID.

      operationId: get_payment_by_id_payments__id__get
      parameters:
        - required: true
          schema:
            title: Payment ID
            type: string
          name: id
          description: ID of payment to retrieve.
          in: path
        - name: expand
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Expand'
        - $ref: '#/components/parameters/ApiVersionHeader'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentAPIResponse'
              example:
                id: kHdEw9EG
                date: '2021-02-21T15:36:16.367687'
                dateUpdated: '2021-02-21T15:36:17.133701'
                status: AUTHORIZED
                orderId: order-abc
                customerId: customer-123
                currencyCode: EUR
                amount: 42
                cardTokenType: CARD_PAN
                paymentMethod:
                  paymentType: SUBSCRIPTION
                  paymentMethodToken: heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4
                  isVaulted: true
                  authorizationType: FINAL
                  descriptor: 'Purchase: Socks'
                  analyticsId: VtkMDAxZW5isH0HsbbNxZ3lo
                  paymentMethodType: PAYMENT_CARD
                  paymentMethodData:
                    first6Digits: '411111'
                    last4Digits: '1111'
                    expirationMonth: '12'
                    expirationYear: '2030'
                    cardholderName: John Biggins
                    network: Visa
                    isNetworkTokenized: false
                    binData:
                      network: VISA
                      regionalRestriction: UNKNOWN
                      accountNumberType: UNKNOWN
                      accountFundingType: UNKNOWN
                      prepaidReloadableIndicator: NOT_APPLICABLE
                      productUsageType: UNKNOWN
                      productCode: VISA
                      productName: VISA
                processor:
                  name: STRIPE
                  processorMerchantId: acct_stripe_1234
                  amountCaptured: 0
                  amountRefunded: 0
                transactions:
                  - type: SALE
                    processorStatus: AUTHORIZED
                    processorName: STRIPE
                    processorMerchantId: acct_stripe_1234
                    processorTransactionId: 54c4eb5b3ef8a
                    cardTokenType: CARD_PAN
                customer:
                  email: customer123@gmail.com
                metadata:
                  productId: 123
                  merchantId: a13bsd62s
        '400':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400ErrorResponse'
              example:
                error:
                  errorId: PaymentError
                  description: The payment could not be found
                  diagnosticsId: '1234567898'

  /payment-instruments/{paymentMethodToken}/vault:
    post:
      tags:
        - Payment Methods API
      summary: Save a payment method token
      description: |
        <p/>

        Save a `SINGLE_USE` payment method token so it can be used
        again later.

        If you try to vault an already vaulted token, you will get the existing vaulted token back.

      operationId: vault_payment_method_payment_methods__token__vault_post
      parameters:
        - description: Payment method token to store.
          required: true
          schema:
            title: Payment Method Token
            type: string
            description: Payment method token
          name: paymentMethodToken
          in: path
        - $ref: '#/components/parameters/ApiVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VaultPaymentMethodAPIRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantPaymentMethodTokenAPIResponse'
        '400':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400ErrorResponse'
              example:
                error:
                  errorId: FailedVerification
                  description: Payment method could not be verified
                  diagnosticsId: '1234567898'
        '422':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
              example:
                error:
                  errorId: RequestValidationError
                  description: >-
                    We were unable to validate your request, please check your payload
                    against /docs/api
                  diagnosticsId: '1234567898'
                  validationErrors: [{model: VaultPaymentInstrumentAPIRequest, 
                          errors: [{path: $.customerId, description: Ensure this
                                value has at least 1 characters}]}]
  /payment-instruments:
    get:
      tags:
        - Payment Methods API
      summary: List saved payment methods
      description: Retrieve a list of stored payment methods for a customer.
      operationId: get_payment_methods_payment_methods_get
      parameters:
        - description: Return payment methods for this customer ID.
          required: true
          schema:
            title: Customer ID
            type: string
            description: Return payment methods for this customer ID.
          name: customer_id
          in: query
        - $ref: '#/components/parameters/ApiVersionHeader'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/MerchantPaymentMethodTokenListAPIResponse
  /payment-instruments/{paymentMethodToken}:
    delete:
      tags:
        - Payment Methods API
      summary: Delete a saved payment method
      description: Delete a saved payment method.
      operationId: delete_payment_method_payment_methods__token__delete
      parameters:
        - description: Saved payment method token to delete.
          required: true
          schema:
            title: Payment Method Token
            type: string
            description: Payment method token
          name: paymentMethodToken
          in: path
        - $ref: '#/components/parameters/ApiVersionHeader'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantPaymentMethodTokenAPIResponse'
        '400':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400ErrorResponse'
              example:
                error:
                  errorId: InvalidPaymentInstrumentToken
                  description: Invalid payment instrument.
                  diagnosticsId: '1234567898'
  /payment-instruments/{paymentMethodToken}/default:
    post:
      tags:
        - Payment Methods API
      summary: Update the default saved payment method
      description: >-
        Update a saved payment method to be the default stored payment method for
        a customer.
      operationId: >-
        set_payment_method_default_payment_methods__token__default_post
      parameters:
        - description: Saved payment method token to set to default.
          required: true
          schema:
            title: Token
            type: string
            description: Payment method token
          name: paymentMethodToken
          in: path
        - $ref: '#/components/parameters/ApiVersionHeader'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantPaymentMethodTokenAPIResponse'
        '400':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400ErrorResponse'
              example:
                error:
                  errorId: InvalidPaymentInstrumentToken
                  description: Invalid payment instrument.
                  diagnosticsId: '1234567898'


components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

  parameters:
    IdempotencyHeader:
      required: false
      schema:
        title: X-Idempotency-Key
        type: string
      name: X-Idempotency-Key
      description: >-
        Optional key to make the request idempotent. Enables a safe retry of a request
        without risking the user being charged or refunded multiple times. The idempotency
        key must be generated by the client and needs to be unique for every new request.
      in: header
    ApiVersionHeader:
      required: true
      schema:
        title: X-API-VERSION
        type: string
        example: '2.4'
      name: X-API-VERSION
      description: >-
        Specifies the version of the API to use. This must be set to `2.4`.
      in: header

  schemas:
    AccountFundingTypeEnum:
      title: AccountFundingTypeEnum
      enum:
        - CREDIT
        - DEBIT
        - PREPAID
        - CHARGE
        - DEFERRED_DEBIT
        - UNKNOWN
      type: string
      description: An enumeration.

    ApayaCustomerTokenAPISchema:
      title: ApayaCustomerTokenAPISchema
      required:
        - mx
      type: object
      properties:
        mx:
          title: Mx
          type: string
        mnc:
          title: Mnc
          type: integer
          format: int64
        mcc:
          title: Mcc
          type: integer
          format: int64

    BinDataAPISchema:
      title: BinDataAPISchema
      required:
        - network
        - regionalRestriction
        - accountNumberType
        - accountFundingType
        - prepaidReloadableIndicator
        - productUsageType
        - productCode
        - productName
      type: object
      properties:
        network:
          $ref: '#/components/schemas/CardNetworkEnum'
        issuerCountryCode:
          $ref: '#/components/schemas/CountryCodeEnum'
        issuerName:
          title: Issuername
          type: string
        issuerCurrencyCode:
          $ref: '#/components/schemas/Currency'
        regionalRestriction:
          $ref: '#/components/schemas/CardRegionRestrictionEnum'
        accountNumberType:
          $ref: '#/components/schemas/CardAccountNumberTypeEnum'
        accountFundingType:
          $ref: '#/components/schemas/AccountFundingTypeEnum'
        prepaidReloadableIndicator:
          $ref: '#/components/schemas/PrepaidReloadableEnum'
        productUsageType:
          $ref: '#/components/schemas/CardProductTypeEnum'
        productCode:
          title: Productcode
          type: string
        productName:
          title: Productname
          type: string

    BlockingPaymentActionTypeEnum:
      title: BlockingPaymentActionTypeEnum
      enum:
        - 3DS_AUTHENTICATION
        - USE_PRIMER_SDK
        - PAYMENT_METHOD_VOUCHER
        - PROCESSOR_3DS
      type: string
      description: An enumeration.

    CardAccountNumberTypeEnum:
      title: CardAccountNumberTypeEnum
      enum:
        - PRIMARY_ACCOUNT_NUMBER
        - NETWORK_TOKEN
        - DIGITAL_PAN
        - UNKNOWN
      type: string
      description: An enumeration.

    CardNetworkEnum:
      title: CardNetworkEnum
      enum:
        - AMEX
        - DANKORT
        - DINERS_CLUB
        - DISCOVER
        - EFTPOS
        - ENROUTE
        - ELO
        - HIPER
        - INTERAC
        - JCB
        - MAESTRO
        - MASTERCARD
        - MIR
        - PRIVATE_LABEL
        - UNIONPAY
        - VISA
        - CARTES_BANCAIRES
        - OTHER
      type: string
      description: |
        The list of available card networks.

    CardProductTypeEnum:
      title: CardProductTypeEnum
      enum:
        - CONSUMER
        - BUSINESS
        - GOVERNMENT
        - UNKNOWN
      type: string
      description: An enumeration.

    CardRegionRestrictionEnum:
      title: CardRegionRestrictionEnum
      enum:
        - DOMESTIC_USE_ONLY
        - NONE
        - UNKNOWN
      type: string
      description: An enumeration.

    ClientSessionUpdateAPIRequest:
      title: ClientSessionUpdateAPIRequest
      type: object
      properties:
        clientToken:
          title: Client token
          type: string
          description: >-
            Client token for use in the Primer-JS SDK obtained via `POST` /client-session
            API call.
        customerId:
          title: The ID of the customer using the checkout.
          type: string
          description: A unique identifier for your customer.
        orderId:
          title: Order ID
          type: string
          description: Your reference for the order.
        currencyCode:
          title: Currency
          type: string
          description: >
            The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).
            e.g. use `USD` for US dollars.
        amount:
          title: Payment amount
          minimum: 0.0
          type: integer
          format: int64
          description: >-
            The amount you would like to charge the customer, in minor units. e.g.
            for $7, use `700`.


            Some currencies, such as Japanese Yen, do not have minor units. In this
            case you should use the value as it is, without any formatting. For example
            for ¥100, use `100`.


            If the amount is provided on this level, it would override any amount
            calculated from the provided line items, shipping and other amounts.
        metadata:
          title: Payment Metadata
          type: object
          description: |
            Additional data to be used throughout the payment lifecycle.

            Provide the entire object to update it. Anything provided previously will be overwritten.
        customer:
          $ref: '#/components/schemas/CheckoutCustomerDetailsAPISchema'
          title: Customer Details
          description: |
            More information associated with the customer.

            Each of the fields in this object must be updated in its entirety, i.e. provide the entire object to update it. Anything provided previously will be overwritten.
        order:
          $ref: '#/components/schemas/OrderDetailsAPISchema'
          title: Order Details
          description: |
            More information associated with the order.

            Each of the fields in this object must be updated in its entirety, i.e. provide the entire object to update it. Anything provided previously will be overwritten.

        paymentMethod:
          $ref: '#/components/schemas/CheckoutPaymentMethodOptionsAPISchema'
          title: Payment Method Options
          description: >-
            Enable certain options associated with the payment method. Provide the
            entire object to update it. Anything provided previously will be overwritten.
      additionalProperties: false
      example:
        clientToken: client-session-token
        customerId: customer-123
        orderId: order-abc
        customer: {emailAddress: john@primer.io}
        amount: 500
        paymentMethod:
          authorizationType: FINAL
        order: {lineItems: [{itemId: shoe-123, description: Blue Shoe, amount: 
                  100, quantity: 10}], countryCode: FR}

    ClientSessionAPIRequest:
      title: ClientSessionAPIRequest
      type: object
      properties:
        orderId:
          title: Order identifier
          type: string
          description: Your reference for the payment.
          minLength: 1
          maxLength: 255
        currencyCode:
          $ref: '#/components/schemas/Currency'
          title: Currency
          description: >
            The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).
            e.g. use `USD` for US dollars.
        amount:
          title: Payment amount
          minimum: 0.0
          type: integer
          format: int64
          description: >-
            The amount you would like to charge the customer, in minor units. e.g.
            for $7, use `700`.


            Some currencies, such as Japanese Yen, do not have minor units. In this
            case you should use the value as it is, without any formatting. For example
            for ¥100, use `100`.


            If the amount is provided on this level, it would override any amount
            calculated from the provided line items, shipping and other amounts.
        order:
          $ref: '#/components/schemas/OrderDetailsAPISchema'
          title: Order Details
          description: More information associated with the order.
        customerId:
          title: The ID of the customer using the checkout
          type: string
          description: >-
            A unique identifier for your customer.

            Create a client session token with a `customerId` to enable the client-side
            SDK to retrieve and manage your customer's saved payment methods. A client
            session token also enables saving payment methods against this customer
            id.
          minLength: 1
          maxLength: 255
        customer:
          $ref: '#/components/schemas/CheckoutCustomerDetailsAPISchema'
          title: Customer Details
          description: More information associated with the customer.
        metadata:
          title: Payment Metadata
          type: object
          description: |
            Additional data to be used throughout the payment lifecycle.

            A dictionary of key-value pairs where the values can only be strings or
            integers.

            e.g. `{"productId": 1001, "merchantId": "a13bsd62s"}`
        paymentMethod:
          $ref: '#/components/schemas/CheckoutPaymentMethodOptionsAPISchema'
          title: Payment Method Options
          description: Enable certain options associated with the payment 
            method.
      additionalProperties: false
      example:
        orderId: order-abc
        currencyCode: GBP
        amount: 1000
        order:
          countryCode: FR,
          lineItems:
            - itemId: shoe-123
              description: Blue Shoe
              amount: 100
              quantity: 10
        customerId: customer-123
        customer:
          emailAddress: john@primer.io
        metadata:
          productType: Shoes
        paymentMethod:
          descriptor: 'Purchase: Shoes'
          paymentMethodType: PAYMENT_CARD
          vaultOnSuccess: true
          vaultOn3DS: false
          options:
            PAYMENT_CARD:
              networks:
                VISA:
                  surcharge:
                    amount: 10
            GOOGLE_PAY:
              surcharge:
                amount: 20
          authorizationType: ESTIMATED

    OrderDetailsAPISchema:
      title: OrderDetailsAPISchema
      type: object
      properties:
        lineItems:
          title: Line Items
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItemsAPISchema'
          description: The details of the line items of the order.
        countryCode:
          $ref: '#/components/schemas/CountryCodeEnum'
          title: Country Code
          description: The country in which the order is created
        retailerCountryCode:
          $ref: '#/components/schemas/CountryCodeEnum'
          title: Retailer Country Code
          description: The country code of the retailer
        fees:
          title: Fee Details
          type: array
          items:
            $ref: '#/components/schemas/OrderFeesAPISchema'
          description: The details of fees charged.
        shipping:
          $ref: '#/components/schemas/OrderShippingAPISchema'
          title: Shipping Details
          description: The details of shipping charged.

    OrderFeesAPISchema:
      title: OrderFeesAPISchema
      type: object
      required:
        - amount
      properties:
        amount:
          minimum: 0.0
          type: integer
          format: int64
          description: >-
            The fee amount charged to the customer, in minor  units. e.g. for $7,
            use `700`.
        type:
          type: string
          description: The type of fee.
          minLength: 1
          maxLength: 255
        description:
          type: string
          description: A description of the fee, e.g. "Currency Conversion Fee".
          minLength: 1
          maxLength: 255

    OrderLineItemsAPISchema:
      title: OrderLineItemsAPISchema
      description: |
        The details of the line items of the order.

        The total amount of a line item is calculated like so: 
        ````
          totalAmount = (amount * quantity) - discountAmount + taxAmount
        ```
      type: object
      required:
        - amount
      properties:
        itemId:
          title: Item ID
          type: string
          description: A unique identifier for the line item.
          minLength: 1
          maxLength: 255
        name:
          title: Name
          type: string
          description: A name of the item.
          maxLength: 255
        description:
          title: Item ID
          type: string
          description: A description of the item.
          maxLength: 255
        amount:
          minimum: 0.0
          type: integer
          format: int64
          description: >-
            The amount charged to the customer, in minor units. The minimum amount
            is 0. The maximum amount is the limit of `int64`.
        quantity:
          type: integer
          description: >-
            The number of the particular line item that is being ordered.
          default: 1
          format: int64
        discountAmount:
          title: Discount Amount
          minimum: 0.0
          type: integer
          format: int64
          description: >-
            Any discount applicable to this item, in minor units. This discount is
            applied for the entire line item, and not per `quantity`.
        taxAmount:
          title: Tax Amount
          minimum: 0.0
          type: integer
          format: int64
          description: >-
            The tax charged on this item, in minor units. This tax amount is applied
            for the entire line item, and not per `quantity`.
        taxCode:
          title: Tax Code
          type: string
          description: >-
            The tax code associated with this item, in minor units. This is required
            for Primer-initiated tax calculations.
          minLength: 1
          maxLength: 255
        productType:
          $ref: '#/components/schemas/ProductTypeEnum'
          title: Product Type
          description: An identifier for the product type.
        productData:
          $ref: '#/components/schemas/OrderLineItemsProductDataAPISchema'
          title: Product Data
          description: Details related to the product

    OrderLineItemsProductDataAPISchema:
      title: OrderLineItemsProductDataAPISchema
      description: Details related to the product
      type: object
      properties:
        sku:
          title: SKU
          type: string
          description: The product SKU
          minLength: 1
          maxLength: 255
        brand:
          title: Brand
          type: string
          description: The product brand
          minLength: 1
          maxLength: 255
        color:
          title: Color
          type: string
          description: The product color
          minLength: 1
          maxLength: 255
        globalTradeItemNumber:
          title: Global Trade Item Number
          type: string
          description: The product Global Trade Item Number (e.g. ISBN)
          minLength: 1
          maxLength: 255
        manufacturerPartNumber:
          title: Manufacturer Part Number
          type: string
          description: The product Manufacturer Part Number
          minLength: 1
          maxLength: 255
        weight:
          title: Weight
          type: number
          description: The product weight
          minimum: 0.0
        weightUnit:
          title: Weight Unit
          type: string
          description: The product weight unit (e.g. kg, g)
          minLength: 1
          maxLength: 255
        pageUrl:
          title: Page URL
          type: string
          description: The product page URL
          minLength: 1
          maxLength: 1024

    OrderShippingAPISchema:
      title: OrderShippingAPISchema
      type: object
      properties:
        amount:
          minimum: 0.0
          type: integer
          format: int64
          description: >-
            The shipping amount charged to the customer, in minor units. e.g. for
            $7, use `700`.
        methodId:
          type: string
          description: >-
            Your unique identifier of the shipping method selected by the customer.
        methodName:
          type: string
          description: >-
            The display label for the selected shipping method (e.g. "Standard Shipping").
        methodDescription:
          type: string
          description: >-
            The descriptive text that is displayed alongside the shipping method name.

    CheckoutPaymentMethodOptionsAPISchema:
      title: PaymentMethodOptionsAPISchema
      type: object
      properties:
        vaultOnSuccess:
          type: boolean
          description: >-
            Whether the payment method should be vaulted on a successful payment or
            not.
          default: false
        vaultOn3DS:
          type: boolean
          description: >-
            Whether the payment method should be vaulted after a successful 3DS authentication
            or not.
          default: false
        vaultOnAgreement:
          type: boolean
          description: >-
            Whether the payment method should be vaulted right when payment is created
            or not.
          default: false
        descriptor:
          title: Payment descriptor
          type: string
          description: >-
            A description of the payment, as it would typically appear on a bank statement.
          maxLength: 255
        paymentType:
          $ref: '#/components/schemas/RecurringPaymentTypeSchema'
        orderedAllowedCardNetworks:
          title: Allowed card networks
          type: array
          items:
            $ref: '#/components/schemas/CardNetworkEnum'
          description: |
            If provided, the checkout will run the validation on the entered card number and raise an error in case the card network is not supported.

            The order sets the default card network that should be used in the case of co-badged cards. 
            e.g. in the case of `["VISA", "CARTES_BANCAIRES", "MASTERCARD"]` - if the user enters a "Visa" / "Cartes Bancaires" card: the default is Visa.

            Values should be unique. 

            If `null` or nothing passed in the request, the following list with all card networks will be returned in the response:

            `["VISA", "MASTERCARD", "AMEX", "MAESTRO", "UNIONPAY", "CARTES_BANCAIRES", "DANKORT", "DINERS_CLUB", "DISCOVER", "EFTPOS", "ENROUTE", "ELO", "HIPER", "INTERAC", "JCB", "MIR", "OTHER"]`

        options:
          title: Payment Method Options
          type: object
          description: |
            Additional options for the payment methods represented as dictionary 
            with key of [available payment methods](/docs/connections/payment-methods/available-payment-methods) and value of corresponding options.
          properties:
            <PAYMENT_METHOD_TYPE>:
              type: object
              $ref: '#/components/schemas/CheckoutPaymentMethodOptionAPISchema'
            APPLE_PAY:
              type: object
              $ref: >-
                #/components/schemas/CheckoutPaymentMethodApplePayOptionAPISchema
            PAYMENT_CARD:
              type: object
              $ref: >-
                #/components/schemas/CheckoutPaymentMethodCardOptionAPISchema
        authorizationType:
          title: Authorization Type
          $ref: '#/components/schemas/AuthorizationTypeEnum'
          description: |
            Allows to adjust the authorized amount after the authorization, if supported by payment method.
            `FINAL` - the authorized amount is final and can not be adjusted. Adjusting the amount can be only done via canceling the payment and re-authorization with new amount.
            `ESTIMATED` - the amount can be adjusted after the authorization, if supported by payment method.
        firstPaymentReason:
          title: First Payment Reason
          $ref: '#/components/schemas/FirstPaymentReasonEnum'
          description: |
            The reason for the first payment. This is used for informing payment processors about the specific reason a payment method is being stored.
            Defaults to None if not provided.

    CheckoutPaymentMethodOptionAPISchema:
      title: PaymentMethodOptionAPISchema
      type: object
      description: |
        Options for the payment method of type `PAYMENT_METHOD_TYPE`.
      required:
        - surcharge
      properties:
        surcharge:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionSurchargeAPISchema
          title: Surcharge
          description: Surcharge information
        extraMerchantData:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionExtraMerchantDataAPISchema
          title: Extra Merchant Data
          description: |
            For payments using the Klarna payment method, depending on the merchant segment and/or 
            the services available to consumers, Klarna may require additional information regarding 
            the customer, the merchant and/or the purchase. This information, referred to as extra merchant 
            data (EMD), consist of data that is typically not available at the checkout, but which enables 
            Klarna to complete an assertive risk assessment, enable new promotional products and improve 
            conversion rates for a boost in performance.
        merchantName:
          title: Merchant name
          type: string
          description: |
            For payments using the Apple Pay payment method, use this field to override the default merchant 
            name for the Primer account from showing on the Apple Pay flow. For example, if your merchant 
            name on your account is "Company X" but you want to display a specific store name on the Apple Pay 
            flow, you can set the `merchantName` to "Store name A".

    CheckoutPaymentMethodCardOptionAPISchema:
      title: Payment Method Card Option
      type: object
      properties:
        networks:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkAPISchema
          title: Card networks
          description: >-
            Dictionary of available card networks as a key with value of Payment Method
            Card Network Option.
        captureVaultedCardCvv:
          type: boolean
          description: Whether to capture CVV for vaulted card.

    CheckoutPaymentMethodOptionCardNetworkAPISchema:
      title: Payment Method Card Network Option
      type: object
      # No better way to define enum keys with OpenAPI 3.0 https://stackoverflow.com/a/46553255/1889928
      properties:
        AMEX:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
        CARTES_BANCAIRES:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
        DANKORT:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
        DINERS_CLUB:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
        DISCOVER:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
        ENROUTE:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
        ELO:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
        HIPER:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
        INTERAC:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
        JCB:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
        MAESTRO:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
        MASTERCARD:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
        MIR:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
        PRIVATE_LABEL:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
        UNIONPAY:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
        VISA:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
        OTHER:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema
      additionalProperties: false

    CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema:
      type: object
      properties:
        surcharge:
          $ref: >-
            #/components/schemas/CheckoutPaymentMethodOptionSurchargeAPISchema
          title: Surcharge
          description: Surcharge information

    CheckoutPaymentMethodOptionSurchargeAPISchema:
      title: CheckoutPaymentMethodOptionSurchargeAPISchema
      type: object
      properties:
        amount:
          type: integer
          minimum: 0.0
          format: int64
          description: >-
            The surcharge amount, in minor units. Surcharge amount must be used in
            conjunction with line item amounts, if a top level amount is passed then
            surcharge will not be calculated.

    CheckoutPaymentMethodOptionExtraMerchantDataAPISchema:
      title: CheckoutPaymentMethodOptionExtraMerchantDataAPISchema
      type: object
      additionalProperties: true

    PaymentRequestPaymentMethodOptionsAPISchema:
      title: PaymentRequestPaymentMethodOptionsAPISchema
      type: object
      properties:
        vaultOnSuccess:
          type: boolean
          description: >-
            Whether the payment method should be vaulted on a successful payment or
            not.
          default: false
        vaultOn3DS:
          type: boolean
          description: >-
            Whether the payment method should be vaulted after a successful 3DS authentication
            or not.
          default: false
        vaultOnAgreement:
          type: boolean
          description: >-
            Whether the payment method should be vaulted right when payment is created
            or not.
          default: false
        descriptor:
          title: Payment descriptor
          type: string
          description: >-
            A description of the payment, as it would typically appear on a bank statement.
          maxLength: 255
        paymentType:
          $ref: '#/components/schemas/RecurringPaymentTypeSchema'
        authorizationType:
          $ref: '#/components/schemas/AuthorizationTypeEnum'
          title: Authorization Type
          description: |
            Allows to adjust the authorized amount after the authorization, if supported by payment method.
            `FINAL` - the authorized amount is final and can not be adjusted. Adjusting the amount can be only done via canceling the payment and re-authorization with new amount.
            `ESTIMATED` - the amount can be adjusted after the authorization, if supported by payment method.
            Defaults to `FINAL`.
          default: FINAL
        firstPaymentReason:
          title: First Payment Reason
          $ref: '#/components/schemas/FirstPaymentReasonEnum'
          description: |
            The reason for the first payment. This is used to be passed to the payment processor when creating a first payment.
            Not all payment processors support this field so ignore it if you are not requested to provide it. If not provided defaults to null.
    Amount:
      type: integer
      format: int64
      minimum: 0
      description: >
        Charge amount in minor units (e.g., 500 = $5.00).
        Some currencies, such as Japanese Yen, do not have minor units.
        In this case, use the value as-is (e.g., ¥100 = 100).

    ApplePayLabel:
      type: string
      minLength: 1
      maxLength: 1024
      description: >
        Display label shown in the Apple Pay sheet to describe this billing option.

    ApplePayManagementUrl:
      type: string
      format: uri
      minLength: 1
      maxLength: 1024
      description: >
        URL where users can manage or cancel their Apple Pay billing agreements or
        subscriptions.

    ApplePayPaymentDescription:
      type: string
      minLength: 1
      maxLength: 1024
      description: >
        Text shown to the user during Apple Pay authorization.

    ApplePayBillingAgreement:
      type: string
      minLength: 1
      maxLength: 1024
      description: >
        Terms and conditions the user agrees to when authorizing Apple Pay billing.

    ApplePayIntervalUnit:
      type: string
      enum: [minute, hour, day, month, year]
      description: >
        Calendar unit representing part of a recurring billing interval.

    ApplePayIntervalCount:
      type: integer
      format: int64
      minimum: 1
      description: >
        Number of calendar units that make up the full recurring interval (e.g., 1
        = monthly).

    CheckoutPaymentMethodApplePayOptionAPISchema:
      title: ApplePayOptions
      type: object
      description: >-
        Apple Pay configuration used in a client session's payment method options.
      properties:
        merchantName:
          type: string
          description: Display name for the merchant shown in the Apple Pay 
            sheet.
          minLength: 1
          maxLength: 1024
        recurringPaymentRequest:
          $ref: '#/components/schemas/ApplePayRecurringRequest'
        deferredPaymentRequest:
          $ref: '#/components/schemas/ApplePayDeferredRequest'
        automaticReloadRequest:
          $ref: '#/components/schemas/ApplePayAutomaticReloadRequest'
      example:
        merchantName: My Store
        recurringPaymentRequest:
          paymentDescription: Monthly Subscription
          billingAgreement: You agree to pay monthly until you cancel.
          managementUrl: https://example.com/manage
          regularBilling:
            label: Monthly Plan
            amount: 999
            recurringStartDate: '2025-06-09T00:00:00Z'
            recurringIntervalUnit: month

    ApplePayRecurringRequest:
      title: ApplePayRecurringRequest
      type: object
      required: [managementUrl, regularBilling]
      properties:
        paymentDescription:
          $ref: '#/components/schemas/ApplePayPaymentDescription'
        billingAgreement:
          $ref: '#/components/schemas/ApplePayBillingAgreement'
        managementUrl:
          $ref: '#/components/schemas/ApplePayManagementUrl'
        regularBilling:
          $ref: '#/components/schemas/ApplePayRegularBilling'
        trialBilling:
          $ref: '#/components/schemas/ApplePayTrialBilling'
      example:
        paymentDescription: Subscription Service
        billingAgreement: >-
          You authorize us to charge your payment method monthly. You can cancel anytime.
        managementUrl: https://example.com/subscription
        regularBilling:
          label: Premium Plan
          amount: 1999
          recurringStartDate: '2024-06-03T00:00:00Z'
          recurringIntervalUnit: month
          recurringIntervalCount: 1
        trialBilling:
          label: Free Trial
          amount: 0
          recurringEndDate: '2024-06-09T00:00:00Z'

    ApplePayRegularBilling:
      title: ApplePayRegularBilling
      type: object
      required: [label]
      properties:
        label:
          $ref: '#/components/schemas/ApplePayLabel'
        amount:
          $ref: '#/components/schemas/Amount'
        recurringStartDate:
          type: string
          format: date-time
          description: >
            Start of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).
            If not provided, Apple Pay defaults it to now().
        recurringEndDate:
          type: string
          format: date-time
          description: >
            End of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).
        recurringIntervalUnit:
          $ref: '#/components/schemas/ApplePayIntervalUnit'
        recurringIntervalCount:
          $ref: '#/components/schemas/ApplePayIntervalCount'
      example:
        label: Monthly Subscription
        amount: 999
        recurringStartDate: '2024-06-03T00:00:00Z'
        recurringIntervalUnit: month

    ApplePayTrialBilling:
      title: ApplePayTrialBilling
      type: object
      required: [label]
      properties:
        label:
          $ref: '#/components/schemas/ApplePayLabel'
        amount:
          allOf:
            - $ref: '#/components/schemas/Amount'
          default: 0
        recurringStartDate:
          type: string
          format: date-time
          description: >
            Start of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).
            If not provided, Apple Pay defaults it to now().
        recurringEndDate:
          type: string
          format: date-time
          description: >
            End of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).
        recurringIntervalUnit:
          $ref: '#/components/schemas/ApplePayIntervalUnit'
        recurringIntervalCount:
          $ref: '#/components/schemas/ApplePayIntervalCount'
      example:
        label: Free Trial
        amount: 0
        recurringEndDate: '2024-06-09T00:00:00Z'

    ApplePayDeferredRequest:
      title: ApplePayDeferredRequest
      type: object
      required: [managementUrl, deferredBilling]
      properties:
        paymentDescription:
          $ref: '#/components/schemas/ApplePayPaymentDescription'
        billingAgreement:
          $ref: '#/components/schemas/ApplePayBillingAgreement'
        managementUrl:
          $ref: '#/components/schemas/ApplePayManagementUrl'
        deferredBilling:
          $ref: '#/components/schemas/ApplePayDeferredBilling'
        freeCancellationDate:
          type: string
          format: date-time
          description: >
            End of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).
        freeCancellationTimeZone:
          type: string
          minLength: 3
          maxLength: 50
          description: Time zone for interpreting freeCancellationDate.
      example:
        paymentDescription: Deferred Payment
        billingAgreement: >-
          You will be charged when the item ships. Free cancellation until shipping.
        managementUrl: https://example.com/orders
        deferredBilling:
          label: Order Payment
          amount: 4999
          deferredPaymentDate: '2024-07-03T00:00:00Z'
        freeCancellationDate: '2024-07-02T00:00:00Z'
        freeCancellationTimeZone: UTC

    ApplePayDeferredBilling:
      title: ApplePayDeferredBilling
      type: object
      required: [label, deferredPaymentDate]
      properties:
        label:
          $ref: '#/components/schemas/ApplePayLabel'
        amount:
          $ref: '#/components/schemas/Amount'
        deferredPaymentDate:
          type: string
          format: date-time
          description: >
            Start of billing cycle date and time (UTC) in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601).
      example:
        label: Product Payment
        amount: 4999
        deferredPaymentDate: '2024-07-03T00:00:00Z'

    ApplePayAutomaticReloadRequest:
      title: ApplePayAutomaticReloadRequest
      type: object
      required: [managementUrl, automaticReloadBilling]
      properties:
        paymentDescription:
          $ref: '#/components/schemas/ApplePayPaymentDescription'
        billingAgreement:
          $ref: '#/components/schemas/ApplePayBillingAgreement'
        managementUrl:
          $ref: '#/components/schemas/ApplePayManagementUrl'
        automaticReloadBilling:
          $ref: '#/components/schemas/ApplePayAutomaticReloadBilling'
      example:
        paymentDescription: Account Auto Reload
        billingAgreement: >-
          When your balance drops below the threshold, we'll automatically reload
          your account.
        managementUrl: https://example.com/account
        automaticReloadBilling:
          label: Auto Reload
          amount: 2500
          automaticReloadThresholdAmount: 500

    ApplePayAutomaticReloadBilling:
      title: ApplePayAutomaticReloadBilling
      type: object
      required: [label, automaticReloadThresholdAmount]
      properties:
        label:
          $ref: '#/components/schemas/ApplePayLabel'
        amount:
          $ref: '#/components/schemas/Amount'
        automaticReloadThresholdAmount:
          type: integer
          format: int64
          minimum: 0
          description: >-
            Balance threshold in minor units (e.g., 500 = $5.00) that triggers the
            reload.
      example:
        label: Auto Reload
        amount: 2500
        automaticReloadThresholdAmount: 500

    PaymentResponsePaymentMethodOptionsAPISchema:
      title: PaymentResponsePaymentMethodOptionsAPISchema
      type: object
      properties:
        descriptor:
          title: Payment descriptor
          type: string
          description: |
            The description of the payment, as it would typically appear
            on a bank statement.
          maxLength: 255
        paymentType:
          $ref: '#/components/schemas/RecurringPaymentTypeSchema'
        paymentMethodToken:
          title: Payment method token
          type: string
          description: The payment method token used to authorize the 
            transaction.
        isVaulted:
          title: Is Vaulted flag
          type: boolean
          description: >-
            Whether the payment method token represents a vaulted payment method and
            can be used for future payments.
          default: false
        analyticsId:
          title: Unique analytics ID
          type: string
          description: >-
            Unique analytics identifier corresponding to a payment method
          maxLength: 255
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodTypeEnum'
          title: Payment method type
          description: Payment method type used for payment authorization.
        paymentMethodData:
          title: Payment method data
          anyOf:
            - $ref: '#/components/schemas/PaymentCardTokenAPISchema'
            - $ref: '#/components/schemas/PayPalOrderTokenAPISchema'
            - $ref: '#/components/schemas/PayPalBillingAgreementAPISchema'
            - $ref: '#/components/schemas/GoCardlessMandateAPISchema'
            - $ref: '#/components/schemas/KlarnaPaymentSessionAPISchema'
            - $ref: '#/components/schemas/KlarnaCustomerTokenAPISchema'
            - $ref: '#/components/schemas/IdealPayNLTokenAPISchema'
            - $ref: '#/components/schemas/ApayaCustomerTokenAPISchema'
          description: Payment method data
        threeDSecureAuthentication:
          $ref: '#/components/schemas/ThreeDSecureAuthenticationAPISchema'
          title: Threedsecureauthentication
          default:
            response_code: NOT_PERFORMED
        authorizationType:
          $ref: '#/components/schemas/AuthorizationTypeEnum'
          title: Authorization Type
          description: >-
            Allows to adjust the authorized amount after the authorization, if supported
            by payment method. `FINAL` - the authorized amount is final and can not
            be adjusted. Adjusting the amount can be only done via canceling the payment
            and re-authorization with new amount. `ESTIMATED` - the amount can be
            adjusted after the authorization, if supported by payment method.

    CheckoutCustomerDetailsAPISchema:
      title: CustomerDetailsAPISchema
      type: object
      properties:
        emailAddress:
          title: Email Address
          type: string
          description: |
            Customer email address. <br />Must be a valid email address. Supports internationalized email addresses.
          format: email
        mobileNumber:
          title: Mobile Number
          type: string
          description: The customer's mobile number
          minLength: 1
          maxLength: 255
        firstName:
          title: First Name
          type: string
          description: The customer's first name
          minLength: 1
          maxLength: 255
        lastName:
          title: Last Name
          type: string
          description: The customer's last name
          minLength: 1
          maxLength: 255
        billingAddress:
          $ref: '#/components/schemas/OptionalAddressAPISchema'
          title: Billing Address
          description: |
            Customer billing address.
        shippingAddress:
          $ref: '#/components/schemas/OptionalAddressAPISchema'
          title: Shipping Address
          description: Customer shipping address
        taxId:
          title: Tax ID
          type: string
          description: The customer's tax id number for tax exemptions
          maxLength: 255
        nationalDocumentId:
          title: National Document ID
          type: string
          description: The customer's national identification number
          maxLength: 255

    CustomerDetailsAPISchema:
      title: CustomerDetailsAPISchema
      type: object
      properties:
        emailAddress:
          title: Email Address
          type: string
          description: |
            Customer email address.

            Note: It is recommended to include this field if a 3DS check will be performed
          format: email
        mobileNumber:
          title: Mobile Number
          type: string
          description: The customer's mobile number
          maxLength: 255
        firstName:
          title: First Name
          type: string
          description: The customer's first name
          maxLength: 255
        lastName:
          title: Last Name
          type: string
          description: The customer's last name
          maxLength: 255
        billingAddress:
          $ref: '#/components/schemas/OptionalAddressAPISchema'
          title: Billing Address
          description: |
            Customer billing address.

            Note: It is recommended to include this field if a 3DS check will be performed
        shippingAddress:
          $ref: '#/components/schemas/OptionalAddressAPISchema'
          title: Shipping Address
          description: Customer shipping address
        taxId:
          title: Tax ID
          type: string
          description: The customer's tax id number for tax exemptions
          maxLength: 255
        nationalDocumentId:
          title: National Document ID
          type: string
          description: The customer's national identification number
          maxLength: 255

    ClientSessionWithTokenAPIResponse:
      title: ClientSessionWithTokenAPIResponse
      type: object
      required:
        - clientToken
        - clientTokenExpirationDate
      properties:
        clientToken:
          title: Client token
          type: string
          description: Client token used to initialize the SDK on all platforms.
        clientTokenExpirationDate:
          title: Expiration Date
          type: string
          description: >-
            Expiration date & time of the client token (UTC with no timezoneinfo).
          format: date-time
        orderId:
          title: Order ID
          type: string
          description: Your reference for the payment.
        currencyCode:
          title: Currency
          type: string
          description: >
            The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).
            e.g. use `USD` for US dollars.
        amount:
          title: Payment amount
          minimum: 0.0
          type: integer
          format: int64
          description: >-
            The amount you would like to charge the customer, in minor units. e.g.
            for $7, use `700`.


            Some currencies, such as Japanese Yen, do not have minor units. In this
            case you should use the value as it is, without any formatting. For example
            for ¥100, use `100`.


            If the amount is provided on this level, it would override any amount
            calculated from the provided line items, shipping and other amounts.
        order:
          $ref: '#/components/schemas/OrderDetailsAPISchema'
          title: Order Details
          description: More information associated with the order.
        customerId:
          title: The ID of the customer using the checkout
          type: string
          description: A unique identifier for your customer.
        customer:
          $ref: '#/components/schemas/CustomerDetailsAPISchema'
          title: Customer Details
          description: More information associated with the customer.
        metadata:
          title: Payment Metadata
          type: object
          description: |
            Additional data to be used throughout the payment lifecycle.
        paymentMethod:
          $ref: '#/components/schemas/CheckoutPaymentMethodOptionsAPISchema'
          title: Payment Method Options
          description: Enable certain options associated with the payment 
            methods.
        warnings:
          $ref: '#/components/schemas/ClientSessionWarningsAPIResponse'
          description: >-
            Warning messages to indicate missing information that are required for
            payment methods, checkout modules and other features; or when third-party
            services are unavailable.
      example:
        clientToken: client-session-token
        clientExpirationDate: '2019-08-24T14:15:22Z'
        customerId: customer-123
        orderId: order-abc
        currencyCode: GBP
        metadata:
          productType: Shoe
        customer:
          emailAddress: john@primer.io
        amount: 20
        order:
          countryCode: FR
          fees:
            - type: SURCHARGE
              amount: 20
        paymentMethod:
          vaultOnSuccess: true
          vaultOn3DS: false
          options:
            PAYMENT_CARD:
              networks:
                VISA:
                  surcharge:
                    amount: 10
              captureVaultedCardCvv: true
            GOOGLE_PAY:
              surcharge:
                amount: 20
          authorizationType: ESTIMATED
        warnings:
          - type: TAXJAR
            code: MISSING_DATA
            message: Shipping details are required for calculating tax.

    ClientSessionAPIResponse:
      title: ClientSessionAPIResponse
      type: object
      properties:
        customerId:
          title: The ID of the customer using the checkout
          type: string
          description: A unique identifier for your customer.
          maxLength: 255
        orderId:
          title: Order ID
          type: string
          description: Your reference for the payment.
          maxLength: 255
        currencyCode:
          $ref: '#/components/schemas/Currency'
          title: Currency
          description: >
            The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).
            e.g. use `USD` for US dollars.
        amount:
          title: Payment amount
          minimum: 0.0
          type: integer
          format: int64
          description: >-
            The amount you are going to charge the customer, in minor units. This
            amount is calculated from the line items, shipping and other amounts provided
            in the `order`. 

            If a top-level amount is provided, it would override any calculated amount.
        metadata:
          title: Payment Metadata
          type: object
          description: |
            Additional data to be used throughout the payment lifecycle.
        customer:
          $ref: '#/components/schemas/CustomerDetailsAPISchema'
          title: Customer Details
          description: More information associated with the customer.
        order:
          $ref: '#/components/schemas/OrderDetailsAPISchema'
          title: Order Details
          description: More information associated with the order.
        paymentMethod:
          $ref: '#/components/schemas/CheckoutPaymentMethodOptionsAPISchema'
          title: Payment Method Options
          description: Enable certain options associated with the payment 
            methods.
      example:
        customerId: customer-123
        orderId: order-abc
        currencyCode: GBP
        amount: 650
        metadata:
          productType: Clothing
        customer:
          emailAddress: john@primer.io
        order:
          lineItems:
            - itemId: t-shirt-1
              description: White T-Shirt
              amount: 500
              quantity: 1
          fees:
            - type: SURCHARGE
              amount: 100
          shipping:
            amount: 50
          paymentMethod:
            vaultOnSuccess: false
            vaultOn3DS: false
            options:
              GOOGLE_PAY:
                surcharge:
                  amount: 100
              PAYMENT_CARD:
                networks:
                  VISA:
                    surcharge:
                      amount: 10
                  MASTERCARD:
                    surcharge:
                      amount: 20
              PAY_NL_IDEAL:
                surcharge:
                  amount: 50
          authorizationType: ESTIMATED

    ClientSessionWarningsAPIResponse:
      title: ClientSessionWarningsAPIResponse
      type: object
      properties:
        type:
          type: string
          description: The type of the connection involved
          example: TAXJAR
        code:
          type: string
          description: A unique code describing the particular issue
          example: MISSING_DATA
        message:
          type: string
          description: More information as to the reason for the warning

    CountryCodeEnum:
      title: CountryCodeEnum
      enum:
        - AW
        - AF
        - AO
        - AI
        - AX
        - AL
        - AD
        - AE
        - AR
        - AM
        - AS
        - AQ
        - TF
        - AG
        - AU
        - AT
        - AZ
        - BI
        - BE
        - BJ
        - BQ
        - BF
        - BD
        - BG
        - BH
        - BS
        - BA
        - BL
        - BY
        - BZ
        - BM
        - BO
        - BR
        - BB
        - BN
        - BT
        - BV
        - BW
        - CF
        - CA
        - CC
        - CH
        - CL
        - CN
        - CI
        - CM
        - CD
        - CG
        - CK
        - CO
        - KM
        - CV
        - CR
        - CU
        - CW
        - CX
        - KY
        - CY
        - CZ
        - DE
        - DJ
        - DM
        - DK
        - DO
        - DZ
        - EC
        - EG
        - ER
        - EH
        - ES
        - EE
        - ET
        - FI
        - FJ
        - FK
        - FR
        - FO
        - FM
        - GA
        - GB
        - GE
        - GG
        - GH
        - GI
        - GN
        - GP
        - GM
        - GW
        - GQ
        - GR
        - GD
        - GL
        - GT
        - GF
        - GU
        - GY
        - HK
        - HM
        - HN
        - HR
        - HT
        - HU
        - ID
        - IM
        - IN
        - IO
        - IE
        - IR
        - IQ
        - IS
        - IL
        - IT
        - JM
        - JE
        - JO
        - JP
        - KZ
        - KE
        - KG
        - KH
        - KI
        - KN
        - KR
        - KW
        - LA
        - LB
        - LR
        - LY
        - LC
        - LI
        - LK
        - LS
        - LT
        - LU
        - LV
        - MO
        - MF
        - MA
        - MC
        - MD
        - MG
        - MV
        - MX
        - MH
        - MK
        - ML
        - MT
        - MM
        - ME
        - MN
        - MP
        - MZ
        - MR
        - MS
        - MQ
        - MU
        - MW
        - MY
        - YT
        - NA
        - NC
        - NE
        - NF
        - NG
        - NI
        - NU
        - NL
        - 'NO'
        - NP
        - NR
        - NZ
        - OM
        - PK
        - PA
        - PN
        - PE
        - PH
        - PW
        - PG
        - PL
        - PR
        - KP
        - PT
        - PY
        - PS
        - PF
        - QA
        - RE
        - RO
        - RU
        - RW
        - SA
        - SD
        - SN
        - SG
        - GS
        - SH
        - SJ
        - SB
        - SL
        - SV
        - SM
        - SO
        - PM
        - RS
        - SS
        - ST
        - SR
        - SK
        - SI
        - SE
        - SZ
        - SX
        - SC
        - SY
        - TC
        - TD
        - TG
        - TH
        - TJ
        - TK
        - TM
        - TL
        - TO
        - TT
        - TN
        - TR
        - TV
        - TW
        - TZ
        - UG
        - UA
        - UM
        - UY
        - US
        - UZ
        - VA
        - VC
        - VE
        - VG
        - VI
        - VN
        - VU
        - WF
        - WS
        - YE
        - ZA
        - ZM
        - ZW
      description: |
        2-letter country code in <a href='https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements'>ISO 3166-1 alpha</a> format, 
        e.g. <code>FR</code> for France and <code>GB</code> for the United Kingdom.

    Currency:
      title: Currency
      enum:
        - AED
        - AFN
        - ALL
        - AMD
        - ANG
        - AOA
        - ARS
        - AUD
        - AWG
        - AZN
        - BAM
        - BBD
        - BDT
        - BGN
        - BHD
        - BIF
        - BMD
        - BND
        - BOB
        - BOV
        - BRL
        - BSD
        - BTN
        - BWP
        - BYR
        - BYN
        - BZD
        - CAD
        - CDF
        - CHE
        - CHF
        - CHW
        - CLP
        - CNY
        - COP
        - COU
        - CRC
        - CUC
        - CUP
        - CVE
        - CZK
        - DJF
        - DKK
        - DOP
        - DZD
        - EGP
        - ERN
        - ETB
        - EUR
        - FJD
        - FKP
        - GBP
        - GEL
        - GHS
        - GIP
        - GMD
        - GNF
        - GTQ
        - GYD
        - HKD
        - HNL
        - HRK
        - HTG
        - HUF
        - IDR
        - ILS
        - INR
        - IQD
        - IRR
        - ISK
        - JMD
        - JOD
        - JPY
        - KES
        - KGS
        - KHR
        - KMF
        - KPW
        - KRW
        - KWD
        - KYD
        - KZT
        - LAK
        - LBP
        - LKR
        - LRD
        - LSL
        - LYD
        - MAD
        - MDL
        - MKD
        - MMK
        - MNT
        - MOP
        - MRO
        - MUR
        - MVR
        - MWK
        - MXN
        - MXV
        - MYR
        - MZN
        - NAD
        - NGN
        - NIO
        - NOK
        - NPR
        - NZD
        - OMR
        - PAB
        - PEN
        - PGK
        - PHP
        - PKR
        - PLN
        - PYG
        - QAR
        - RON
        - RSD
        - RUB
        - RWF
        - SAR
        - SBD
        - SCR
        - SDG
        - SEK
        - SGD
        - SHP
        - SOS
        - SRD
        - SSP
        - SVC
        - SYP
        - SZL
        - THB
        - TJS
        - TMT
        - TND
        - TOP
        - TRY
        - TTD
        - TWD
        - TZS
        - UAH
        - UGX
        - USD
        - UYU
        - UZS
        - VND
        - VUV
        - WST
        - XAF
        - XAG
        - XAU
        - XBA
        - XBB
        - XBC
        - XBD
        - XCD
        - XDR
        - XFU
        - XOF
        - XPD
        - XPF
        - XPT
        - XSU
        - XTS
        - XUA
        - YER
        - ZAR
        - ZMW
        - ZWL
      description: |
        3-letter currency code in <a href='https://en.wikipedia.org/wiki/ISO_4217#Active_codes'>ISO 4217</a> format, 
        e.g. <code>USD</code> for US dollars.

    PaymentResponseProcessorAPISchema:
      title: PaymentResponseProcessorAPISchema
      type: object
      properties:
        name:
          title: Processor Name
          type: string
          description: The payment processor used for this payment.
          maxLength: 255
        processorMerchantId:
          title: Processor Merchant ID
          type: string
          description: >-
            The merchant ID registered at the payment processor used for this payment.
          maxLength: 255
        amountCaptured:
          title: Amount captured
          type: integer
          minimum: 0.0
          format: int64
          description: |
            If no capture was performed, this value will be set to `0`.

            If one or more partial captures were performed, this value will be a sum
            of all partial capture amounts.
        amountRefunded:
          title: Amount refunded
          type: integer
          minimum: 0.0
          format: int64
          description: |
            If no refund was performed, this value will be set to `0`.

            If one or more partial refunds were performed, this value will be a sum
            of all partial refund amounts.

    GoCardlessMandateAPISchema:
      title: GoCardlessMandateAPISchema
      required:
        - gocardlessMandateId
      type: object
      properties:
        gocardlessMandateId:
          title: Mandate agreement ID
          type: string
          description: Unique identifier of a GoCardless mandate agreement
    IdealPayNLTokenAPISchema:
      title: IdealPayNLTokenAPISchema
      required:
        - paymentMethodConfigId
      type: object
      properties:
        paymentMethodConfigId:
          title: Paymentmethodconfigid
          type: string
          format: uuid
    KlarnaAddressAPISchema:
      title: KlarnaAddressAPISchema
      type: object
      properties:
        title:
          title: Title
          type: string
        firstName:
          title: Firstname
          type: string
        lastName:
          title: Lastname
          type: string
        email:
          title: Email
          type: string
        phoneNumber:
          title: Phonenumber
          type: string
        addressLine1:
          title: Addressline1
          type: string
        addressLine2:
          title: Addressline2
          type: string
        addressLine3:
          title: Addressline3
          type: string
        city:
          title: City
          type: string
        state:
          title: State
          type: string
        countryCode:
          $ref: '#/components/schemas/CountryCodeEnum'
        postalCode:
          title: Postalcode
          type: string
    KlarnaCustomerTokenAPISchema:
      title: KlarnaCustomerTokenAPISchema
      required:
        - klarnaCustomerToken
        - sessionData
      type: object
      properties:
        klarnaCustomerToken:
          title: Klarnacustomertoken
          type: string
        sessionData:
          $ref: '#/components/schemas/KlarnaSessionDetailsAPISchema'
    KlarnaPaymentSessionAPISchema:
      title: KlarnaPaymentSessionAPISchema
      required:
        - klarnaAuthorizationToken
        - sessionData
      type: object
      properties:
        klarnaAuthorizationToken:
          title: Klarnaauthorizationtoken
          type: string
        sessionData:
          $ref: '#/components/schemas/KlarnaSessionDetailsAPISchema'
    KlarnaSessionDetailsAPISchema:
      title: KlarnaSessionDetailsAPISchema
      required:
        - billingAddress
        - purchaseCountry
        - purchaseCurrency
        - locale
        - orderLines
      type: object
      properties:
        recurringDescription:
          title: Recurringdescription
          type: string
        billingAddress:
          $ref: '#/components/schemas/KlarnaAddressAPISchema'
        shippingAddress:
          $ref: '#/components/schemas/KlarnaAddressAPISchema'
        purchaseCountry:
          title: Purchasecountry
          type: string
        purchaseCurrency:
          title: Purchasecurrency
          type: string
        locale:
          title: Locale
          type: string
        orderLines:
          title: Orderlines
          type: array
          items: {}
        tokenDetails:
          $ref: '#/components/schemas/KlarnaTokenDetails'
    KlarnaTokenDetails:
      title: KlarnaTokenDetails
      required:
        - type
      type: object
      properties:
        type:
          title: Type
          type: string
        brand:
          title: Brand
          type: string
        masked_number:
          title: Masked Number
          type: string
        expiry_date:
          title: Expiry Date
          type: string
    PayPalBillingAgreementAPISchema:
      title: PayPalBillingAgreementAPISchema
      required:
        - paypalBillingAgreementId
      type: object
      properties:
        paypalBillingAgreementId:
          title: Paypalbillingagreementid
          type: string
        externalPayerInfo:
          $ref: '#/components/schemas/PayPalExternalPayerInfoAPISchema'
          title: Payer Info
          description: Information about the PayPal customer
        shippingAddress:
          $ref: '#/components/schemas/AddressAPISchema'
          title: Shipping address
          description: The PayPal customer's shipping address
        paypalStatus:
          title: PayPal order status
          type: string
    PayPalExternalPayerInfoAPISchema:
      title: PayPalExternalPayerInfoAPISchema
      type: object
      properties:
        externalPayerId:
          title: Externalpayerid
          type: string
        email:
          title: Email
          type: string
        firstName:
          title: Firstname
          type: string
        lastName:
          title: Lastname
          type: string
    PayPalOrderTokenAPISchema:
      title: PayPalOrderTokenAPISchema
      required:
        - paypalOrderId
      type: object
      properties:
        paypalOrderId:
          title: PayPal order identifier
          type: string
        externalPayerInfo:
          $ref: '#/components/schemas/PayPalExternalPayerInfoAPISchema'
          title: Payer Info
          description: Information about the PayPal customer
        paypalStatus:
          title: PayPal order status
          type: string

    PaymentAPIResponse:
      title: PaymentAPIResponse
      type: object
      properties:
        id:
          title: Payment identifier
          type: string
          description: |
            The unique payment ID.

            You can use this ID to retrieve the payment details, or perform downstream
            operations.
        date:
          title: Payment date
          type: string
          description: >-
            The date and time at which the payment was created in UTC format.
          format: date-time
        dateUpdated:
          title: Payment updated date
          type: string
          description: The date and time of the last payment update in UTC 
            format.
          format: date-time
        status:
          $ref: '#/components/schemas/PaymentStatus'
          title: Current status
          description: >-
            See the payment [status table](../docs#payment-status) for more information.
        cardTokenType:
          title: Card token type used
          allOf:
            - $ref: '#/components/schemas/CardTokenTypeEnum'
          description: |
            The type of card token used for the payment.

            Only applies for card payments.
          example: CARD_PAN
        orderId:
          title: Order ID
          type: string
          description: Your reference for the payment.
          maxLength: 255
        currencyCode:
          $ref: '#/components/schemas/Currency'
          title: Currency
          description: >
            The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).
            e.g. use `USD` for US dollars.
        amount:
          title: Payment amount
          minimum: 0.0
          type: integer
          format: int64
          description: The amount you charged the customer, in minor units.
        order:
          $ref: '#/components/schemas/OrderDetailsAPISchema'
          title: Order Details
          description: More information associated with the order.
        customerId:
          title: The ID of the customer using the checkout
          type: string
          description: The unique identifier for your customer.
          maxLength: 255
        customer:
          $ref: '#/components/schemas/CustomerDetailsAPISchema'
          title: Customer Details
          description: More information associated with the customer.
        metadata:
          title: Payment Metadata
          type: object
          description: |
            Additional data to be used throughout the payment lifecycle.
        paymentMethod:
          $ref: >-
            #/components/schemas/PaymentResponsePaymentMethodOptionsAPISchema
          title: Payment Method Options
          description: >-
            The payment method options provided in the request, as well as the token
            used to process the payment.
        processor:
          $ref: '#/components/schemas/PaymentResponseProcessorAPISchema'
          title: Processor Information
          description: >-
            More information associated with the payment processor, including the
            processor name.
        requiredAction:
          $ref: '#/components/schemas/PaymentRequiredActionAPISchema'
          title: Required action
          description: >-
            Required action to perform in order to resume the payment workflow. This
            can be requiring a 3DS check from the customer for instance.
        statusReason:
          $ref: '#/components/schemas/StatusReasonAPISchema'
          title: Status Reason
          description: |
            Check this field for more information regarding the payment's status. This is especially useful when the status is `DECLINED` or `FAILED`.
        transactions:
          title: Transactions
          type: array
          items:
            $ref: '#/components/schemas/TransactionOverviewAPISchema'
          description: >-
            A list summarizing the transactions that occurred while processing the
            payment.


            Note: a refund is a separate transaction and so will appear in this `transactions`
            list if a refund was performed.
        riskData:
          $ref: '#/components/schemas/RiskDataAPISchema'
          title: Risk Data

    PaymentCancelAPIRequest:
      title: PaymentCancelAPIRequest
      type: object
      properties:
        reason:
          title: Cancellation reason
          type: string
          description: >-
            You can optionally specify a reason for the cancellation. This is for
            your own records.
        expand:
          $ref: '#/components/schemas/Expand'
      additionalProperties: false
      example:
        reason: 'Customer cancelled order #1234.'

    PaymentAuthorizationAPIRequest:
      title: PaymentAuthorizationAPIRequest
      type: object
      required:
        - processor
      properties:
        processor:
          $ref: >-
            #/components/schemas/PaymentAuthorizationRequestProcessorAPISchema
          title: Processor
          description: The payment processor to use for this payment.
        expand:
          $ref: '#/components/schemas/Expand'

    PaymentCaptureAPIRequest:
      title: PaymentCaptureAPIRequest
      type: object
      properties:
        amount:
          title: Amount to capture
          minimum: 0.0
          type: integer
          format: int64
          description: >-
            The amount you would like to capture, in minor units. The currency used
            on authorization is assumed.


            If no amount is specified it defaults to the full amount.
        final:
          title: Final capture
          type: boolean
          description: >-
            Indicates whether the capture request is the final capture request.


            After a final capture, no subsequent captures are allowed.
          default: true
        order:
          title: Order
          description: More information associated with the order.
          type: object
          properties:
            retailerCountryCode:
              $ref: '#/components/schemas/CountryCodeEnum'
              title: Retailer Country Code
              description: >-
                The country code of the retailer.

                This field is passed to the processor and overwrites the retailer
                country code set in order details.
        metadata:
          title: Payment Metadata
          description: >-
            Additional payment metadata.

            A dictionary of key-value pairs where the values can only be strings or
            integers. Keys which already exist in the payment metadata will be overwritten.
          type: object
        expand:
          $ref: '#/components/schemas/Expand'

      additionalProperties: false
      example:
        amount: 42

    PaymentCardTokenAPISchema:
      title: PaymentCardTokenAPISchema
      required:
        - last4Digits
        - expirationMonth
        - expirationYear
      type: object
      properties:
        first6Digits:
          title: Payment card's first six digits
          maxLength: 6
          minLength: 6
          type: string
        last4Digits:
          title: Payment card's last four digits
          maxLength: 4
          minLength: 4
          type: string
        expirationMonth:
          title: Expiration month
          maxLength: 2
          minLength: 2
          type: string
        expirationYear:
          title: Expiration year
          maxLength: 4
          minLength: 4
          type: string
        cardholderName:
          title: Cardholder's name
          type: string
        network:
          title: Card network
          type: string
        isNetworkTokenized:
          title: Is represented by a digital PAN
          type: boolean
          default: false
        binData:
          $ref: '#/components/schemas/BinDataAPISchema'

    PaymentCreationAPIRequest:
      title: PaymentCreationAPIRequest
      required:
        - paymentMethodToken
      type: object
      properties:
        orderId:
          title: Order ID
          type: string
          description: Your reference for the payment.
          maxLength: 255
        currencyCode:
          $ref: '#/components/schemas/Currency'
          title: Currency
          description: >
            The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).
            e.g. use `USD` for US dollars.
        amount:
          title: Payment amount
          minimum: 0.0
          type: integer
          format: int64
          description: >-
            The amount you would like to charge the customer, in minor units. e.g.
            for $7, use `700`.


            Some currencies, such as Japanese Yen, do not have minor units. In this
            case you should use the value as it is, without any formatting. For example
            for ¥100, use `100`. The minimum amount is 0. The maximum amount is the
            limit of `int64`.
        order:
          $ref: '#/components/schemas/OrderDetailsAPISchema'
          title: Order Details
          description: More information associated with the order.
        paymentMethodToken:
          title: Payment method token
          type: string
          description: |
            The payment method token used to authorize the payment.
        customerId:
          title: The ID of the customer using the checkout
          type: string
          description: >-
            A unique identifier for your customer.

            This attribute is required if `paymentMethod.vaultOnSuccess` is set to
            `True`.
          maxLength: 255
        customer:
          $ref: '#/components/schemas/CustomerDetailsAPISchema'
          title: Customer Details
          description: |
            More information associated with the customer.
        metadata:
          title: Payment Metadata
          type: object
          description: |
            Additional data to be used throughout the payment lifecycle.

            A dictionary of key-value pairs where the values can only be strings or
            integers.

            e.g. `{"productId": 1001, "merchantId": "a13bsd62s"}`
        paymentMethod:
          $ref: >-
            #/components/schemas/PaymentRequestPaymentMethodOptionsAPISchema
          title: Payment Method Options
          description: Enable certain options associated with the payment 
            method.
        expand:
          $ref: '#/components/schemas/Expand'

      additionalProperties: false
      example:
        orderId: order-abc
        currencyCode: EUR
        amount: 42
        paymentMethodToken: heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4
        customerId: customer-123
        customer:
          emailAddress: customer123@gmail.com
        metadata:
          productId: 123
          merchantId: a13bsd62s
        paymentMethod:
          paymentType: SUBSCRIPTION
          vaultOnSuccess: true
          authorizationType: ESTIMATED

    StatusReasonAPISchema:
      title: StatusReasonAPISchema
      required:
        - type
      type: object
      properties:
        type:
          $ref: '#/components/schemas/PaymentStatusTypeEnum'
          title: Payment status type
        declineType:
          $ref: '#/components/schemas/DeclineTypeEnum'
          title: Decline Type
          description: |
            If the error is of type `ISSUER_DECLINED` this will be returned.

            Declines of type `SOFT_DECLINE` may be retried,
            whereas declines of type `HARD_DECLINE` should not be retried.
        code:
          $ref: '#/components/schemas/TransactionDeclineReasonV2Enum'
          title: Payment status code
          description: >-
            If the error is of type `ISSUER_DECLINED`, this will be returned.
        message:
          title: Processor message
          type: string
          description: >-
            In case of an error on the processor's part, we will return the message
            returned by the processor. This is usually a human readable error.
        paymentMethodResultCode:
          title: Payment Method Result Code
          type: string
          description: |
            The result code returned by the payment method or card network. This code is unified across all supported processors.

            _e.g. Code `46` refers to the message "Closed account" for Visa across all supported processors._
        paymentMethodResultMessage:
          title: Payment Method Result Message
          type: string
          description: |
            Human-readable version of the Payment Method Result Code. This message is unified across all supported processors.

            _e.g. Code `46` refers to the message "Closed account" for Visa across all supported processors._
        paymentMethodAdviceCode:
          title: Payment Method Advice Code
          type: string
          description: |
            The advice code returned by the payment method or card network. This code is unified across all supported processors.

            _For payments made with Mastercard, this represents the Merchant Advice Code (MAC)._

            _e.g. Code `24` refers to the message "Retry after 1 hour" for Mastercard across all supported processors._
        paymentMethodAdviceMessage:
          title: Payment Method Advice Message
          type: string
          description: |
            Human-readable version of the Payment Method Advice Code. This message is unified across all supported processors.

            _For payments made with Mastercard, this represents the message of the Merchant Advice Code (MAC)._

            _e.g. Code `24` refers to the message "Retry after 1 hour" for Mastercard across all supported processors._
        advisedAction:
          title: Advised Action
          $ref: '#/components/schemas/AdvisedActionEnum'

    RiskDataAPISchema:
      title: RiskDataAPISchema
      description: |
        Risk data associated with this payment.
      type: object
      properties:
        fraudChecks:
          title: Fraud Checks
          $ref: '#/components/schemas/FraudCheckAPISchema'
        cvvCheck:
          title: CVV Check
          $ref: '#/components/schemas/CVVCheckAPISchema'
        avsCheck:
          title: AVS Check
          $ref: '#/components/schemas/AVSCheckAPISchema'

    FraudCheckAPISchema:
      title: FraudCheckAPISchema
      description: |
        Results of the pre-authorization and post-authorization fraud checks.
      type: object
      properties:
        source:
          type: string
          example: FRAUD_PROVIDER
        preAuthorizationResult:
          $ref: '#/components/schemas/PreAuthFraudDecisionTypeEnum'
          example: THREE_DS
        preAuthorizationRecommendation:
          $ref: '#/components/schemas/PreAuthorizationRecommendationEnum'
          example: TRANSACTION_RISK_ANALYSIS
        postAuthorizationResult:
          $ref: '#/components/schemas/PostAuthFraudDecisionTypeEnum'
          example: ACCEPT

    FraudDecisionTypeEnum:
      title: FraudDecisionTypeEnum
      enum:
        - ACCEPT
        - REFUSE
        - FAILED
        - THREE_DS
        - THREE_DS_EXEMPTION
      type: string
      description: Possible fraud check outcomes.

    PreAuthFraudDecisionTypeEnum:
      title: PreAuthFraudDecisionTypeEnum
      enum:
        - ACCEPT
        - REFUSE
        - FAILED
        - THREE_DS
        - THREE_DS_EXEMPTION
      type: string
      description: Possible pre-authorization fraud check outcomes.

    PostAuthFraudDecisionTypeEnum:
      title: PostAuthFraudDecisionTypeEnum
      enum:
        - ACCEPT
        - REFUSE
        - FAILED
        - THREE_DS
      type: string
      description: Possible post-authorization fraud check outcomes.

    PreAuthorizationRecommendationEnum:
      title: PreAuthorizationRecommendationEnum
      enum:
        - TRANSACTION_RISK_ANALYSIS
      type: string
      description: |
        Pre-authorization recommendation indicating the SCA exemption or risk assessment path taken. Only present when `preAuthorizationResult` is `THREE_DS_EXEMPTION`.

        Values:
        - `TRANSACTION_RISK_ANALYSIS`: Indicates that the fraud check deemed the transaction low risk and recommends applying a Transaction Risk Analysis (TRA) exemption to bypass Strong Customer Authentication (SCA) under PSD2, reducing friction for users.

    CVVCheckAPISchema:
      title: CVVCheckAPISchema
      description: |
        Results of any external CVV check performed on this payment.
      type: object
      properties:
        source:
          type: string
          example: PROCESSOR
        result:
          $ref: '#/components/schemas/RiskAssessmentStatusEnum'
          example: MATCHED

    AVSCheckAPISchema:
      title: AVSCheckAPISchema
      description: |
        Results of any external AVS check performed on this payment.
      type: object
      properties:
        source:
          type: string
          example: PROCESSOR
        result:
          $ref: '#/components/schemas/AVSRiskAssessmentValues'

    AVSRiskAssessmentValues:
      title: AVSRiskAssessmentValues
      type: object
      properties:
        streetAddress:
          $ref: '#/components/schemas/RiskAssessmentStatusEnum'
          example: NOT_MATCHED
        postalCode:
          $ref: '#/components/schemas/RiskAssessmentStatusEnum'
          example: NOT_VERIFIED

    RiskAssessmentStatusEnum:
      title: RiskAssessmentStatusEnum
      enum:
        - MATCHED
        - NOT_MATCHED
        - NOT_VERIFIED
        - NOT_PROVIDED
        - NOT_APPLICABLE
        - SKIPPED
      type: string
      description: Possible risk assessment values for CVV and AVS checks.

    PaymentMethodTypeEnum:
      title: PaymentMethodTypeEnum
      enum:
        - PAYMENT_CARD
        - GOOGLE_PAY
        - APPLE_PAY
        - PAYPAL
        - BANK_ACCOUNT
        - KLARNA
        - APAYA
        - OPENNODE
        - HOOLAH
        - ATOME
        - COINBASE
        - NETS
        - TWOC2P
        - CLEARPAY
        - SHOPEEPAY
        - TRIPLE_A
        - AFTERPAY
        - NOL_PAY
        - PAY_NL_IDEAL
        - PAY_NL_BANCONTACT
        - PAY_NL_DIRECT_DEBIT
        - PAY_NL_SOFORT_BANKING
        - PAY_NL_PAYPAL
        - PAY_NL_PAYCONIQ
        - PAY_NL_GIROPAY
        - PAY_NL_P24
        - PAY_NL_EPS
        - PAY_NL_KAARTDIRECT
        - ADYEN_SOFORT
        - ADYEN_TWINT
        - ADYEN_GIROPAY
        - ADYEN_TRUSTLY
        - ADYEN_ALIPAY
        - ADYEN_MOBILEPAY
        - ADYEN_MULTIBANCO
        - ADYEN_VIPPS
        - ADYEN_DOTPAY
        - ADYEN_IDEAL
        - ADYEN_BLIK
        - ADYEN_PAYTRAIL
        - ADYEN_INTERAC
        - ADYEN_PAYSHOP
        - ADYEN_MBWAY
        - ADYEN_AFFIRM
        - ADYEN_KLARNA
        - ADYEN_BANCONTACT_PAYCONIQ
        - ADYEN_EPS
        - ADYEN_BANCONTACT_CARD
        - ADYEN_SWISH
        - MOLLIE_IDEAL
        - MOLLIE_BANCONTACT
        - MOLLIE_P24
        - MOLLIE_GIROPAY
        - MOLLIE_EPS
        - MOLLIE_GIFTCARD
        - MOLLIE_SOFORT
        - NETAXEPT_PAYTRAIL
        - BUCKAROO_IDEAL
        - BUCKAROO_BANCONTACT
        - BUCKAROO_SOFORT
        - BUCKAROO_GIROPAY
        - BUCKAROO_EPS
        - RAPYD_GCASH
        - RAPYD_PROMPTPAY
        - RAPYD_GRABPAY
        - RAPYD_POLI
        - RAPYD_FAST
        - XFERS_PAYNOW
        - STRIPE_GIROPAY
        - STRIPE_IDEAL
        - ALIPAY_CN
        - CHAI_KAKAOPAY
        - CHAI_NAVER
        - CHAI_TOSS
        - XENDIT_DANA
        - XENDIT_OVO
        - XENDIT_SHOPEEPAY
        - XENDIT_RETAIL_OUTLETS
        - OMISE_PROMPTPAY
        - OMISE_TRUEMONEY
        - EBANX_PAGOFACIL
        - PACYPAY_WECHAT
        - PACYPAY_ALIPAY
        - PACYPAY_ALIPAY_PLUS
        - WORLDPAY_IDEAL
        - IPAY88_CARD
        - INGENICO_PAYPAL
        - VOLT_PIX
        - VOLT_BANK_TRANSFER
        - BRAINTREE_VENMO
        - THUNES_SPIRIT_OF_CADEAU
        - THUNES_ILLICADO
        - THUNES_CARTE_CADEAU_CONFORAMA
        - THUNES_CHEQUE_FIDELITE_CONFORAMA
        - SIPS_CPAY
        - SIPS_CPAYCONFORAMA
        - MONEXT_CETELEM
        - MONEXT_CPAY
      type: string
      description: >-
        Payment method type, where `OFF_SESSION_PAYMENT` is used for APM (Alternative
        Payment Method) payments and `PAYMENT_CARD` for traditional debit or credit
        cards. Please note that this list is different from one indicated on [available
        payment methods](/docs/connections/payment-methods/available-payment-methods)
        page and values of this field will be changed in the future versions of the
        API.

    PaymentListAPIResponse:
      title: PaymentListAPIResponse
      type: object
      properties:
        data:
          title: Data
          type: array
          items:
            $ref: '#/components/schemas/PaymentSummaryAPISchema'
        nextCursor:
          title: Nextcursor
          type: string
        prevCursor:
          title: Prevcursor
          type: string

    PaymentRefundAPIRequest:
      title: PaymentRefundAPIRequest
      type: object
      properties:
        amount:
          title: Amount to refund
          minimum: 0.0
          type: integer
          format: int64
          description: >-
            The amount you would like to refund the customer, in minor units. e.g.
            for $7, use `700`.


            Defaults to remaining non-refunded amount.
        orderId:
          title: Order ID
          type: string
          description: >-
            Optionally you can pass a specific order ID for the refund.


            By default this will be set to the original `orderId` given on payment
            creation.

        reason:
          title: Refund reason
          type: string
          description: >-
            You can optionally specify a reason for the refund, for your own records.
            This will be returned in the refund transaction of payment responses.

        transactionEventId:
          title: Transaction Event ID
          type: string
          format: uuid
          description: >-
            Specific capture ID to target for the refund. Use this to specify which
            transaction event the refund should apply to.
          example: 57a2027d-36a6-494f-ad07-a6e1d0c77772
        expand:
          $ref: '#/components/schemas/Expand'

      additionalProperties: false
      example:
        amount: 42
        orderId: order-1234-refund
        reason: 'Customer returned order #1234.'

    PaymentRequiredActionAPISchema:
      title: PaymentRequiredActionAPISchema
      required:
        - name
        - description
      type: object
      properties:
        name:
          $ref: '#/components/schemas/BlockingPaymentActionTypeEnum'
          title: Name
          description: Action name
        description:
          title: Description
          type: string
          description: Human description of the required action to perform.
        clientToken:
          title: Client token
          type: string
          description: >-
            The client token to be returned to the SDK if a required action is returned.

    PaymentResumeAPIRequest:
      title: PaymentResumeAPIRequest
      required:
        - resumeToken
      type: object
      properties:
        resumeToken:
          title: Resume token
          type: string
          description: >-
            A token containing any information that is sent back from the checkout
            to complete a blocked payment flow.
          format: uuid
      additionalProperties: false

    PaymentSummaryAPISchema:
      title: PaymentSummaryAPISchema
      required:
        - id
        - date
        - dateUpdated
        - status
        - orderId
        - currencyCode
        - amount
      type: object
      properties:
        id:
          title: Payment identifier
          type: string
          description: |
            The unique payment ID.

            You can use this ID to retrieve the payment details, or perform downstream
            operations.
        date:
          title: Payment date
          type: string
          description: >-
            The date and time at which the payment was created in UTC format.
          format: date-time
        dateUpdated:
          title: Payment updated date
          type: string
          description: The date and time of the last payment update in UTC 
            format.
          format: date-time
        status:
          $ref: '#/components/schemas/PaymentStatus'
          title: Current status
          description: >-
            See the payment [status table](../docs#payment-status) for more information.
        orderId:
          title: Order ID
          type: string
          description: Your reference for the payment.
        processor:
          $ref: '#/components/schemas/PaymentSummaryProcessorAPISchema'
          title: Processor
          description: The payment processor used for this payment.
        currencyCode:
          title: Currency
          type: string
          description: >
            The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).
            e.g. use `USD` for US dollars.
        amount:
          title: Payment amount
          type: integer
          format: int64
          description: >-
            The payment amount, in minor units. e.g. $7 would show as `700`.
        metadata:
          title: Payment Metadata
          type: object
          description: |
            Additional data to be used throughout the payment lifecycle.

            A dictionary of key-value pairs where the values can only be strings or
            integers.

            e.g. `{"productId": 1001, "merchantId": "a13bsd62s"}`
      example:
        id: IHQlakKC
        date: '2021-03-24T14:56:56.869248'
        status: SETTLED
        orderId: my-order-123
        currencyCode: EUR
        amount: 700
        processor:
          name: STRIPE
          processorMerchantId: acct_stripe_1234
        metadata:
          productId: 123
          merchantId: a13bsd62s

    PaymentAdjustAuthorizationAPIRequest:
      title: PaymentAdjustAuthorizationAPIRequest
      required:
        - amount
      type: object
      properties:
        amount:
          title: Payment amount
          minimum: 0.0
          type: integer
          format: int64
          description: >-
            The **final** amount you would like to charge the customer, in minor units.
            e.g. for $7, use `700`.


            Some currencies, such as Japanese Yen, do not have minor units. In this
            case you should use the value as it is, without any formatting. For example
            for ¥100, use `100`.


            If the amount is provided on this level, it would override any amount
            calculated from the provided line items, shipping and other amounts.
        expand:
          $ref: '#/components/schemas/Expand'

    PaymentAuthorizationRequestProcessorAPISchema:
      title: PaymentAuthorizationRequestProcessorAPISchema
      type: object
      required:
        - processorMerchantId
      properties:
        processorMerchantId:
          type: string
          title: Processor Merchant ID
          description: The processor's merchant ID used to authorize the 
            payment.
        name:
          type: string
          title: Processor Name
          description: >-
            The processor name should be provided if the processorMerchantId is not
            unique across all of your integrations.

    PaymentSummaryProcessorAPISchema:
      title: PaymentSummaryProcessorAPISchema
      required:
        - name
      type: object
      properties:
        name:
          title: Processor Name
          type: string
          description: The payment processor used for this payment.
        processorMerchantId:
          title: Processor Merchant ID
          type: string
          description: >-
            The merchant ID registered at the payment processor used for this payment.

    PrepaidReloadableEnum:
      title: PrepaidReloadableEnum
      enum:
        - RELOADABLE
        - NON_RELOADABLE
        - NOT_APPLICABLE
        - UNKNOWN
      type: string
      description: An enumeration.

    RecurringTransactionTypeEnum:
      title: RecurringTransactionTypeEnum
      enum:
        - FIRST_PAYMENT
        - ECOMMERCE
        - SUBSCRIPTION
        - UNSCHEDULED
      type: string
      description: An enumeration.

    RecurringPaymentTypeSchema:
      $ref: '#/components/schemas/RecurringTransactionTypeEnum'
      title: Recurring Payment Type
      description: |
        Payment types, primarily to be used for recurring payments.
        See the table below for all possible values. 

        Note: if no field is set, we will return a blank value and make a best effort
        to calculate the downstream fields required for processing the payment.

        | paymentType | Use case |
        | --- | --- |
        | `FIRST_PAYMENT` | a customer-initiated payment which is the first in a series of recurring payments or subscription, or a card on file scenario. |
        | `ECOMMERCE` | a customer-initiated payment using stored payment details where the cardholder is present. |
        | `SUBSCRIPTION` | a merchant-initiated payment as part of a series of payments on a fixed schedule and a set amount. |
        | `UNSCHEDULED` | a merchant-initiated payment using stored payment details with no fixed schedule or amount. |

    ProductTypeEnum:
      title: ProductTypeEnum
      enum:
        - PHYSICAL
        - DIGITAL
      type: string
      description: An enumeration

    ThreeDSecureAuthResponseCodeEnum:
      title: ThreeDSecureAuthResponseCodeEnum
      enum:
        - NOT_PERFORMED
        - SKIPPED
        - AUTH_SUCCESS
        - AUTH_FAILED
        - CHALLENGE
        - METHOD
      type: string
      description: An enumeration.

    ThreeDSecureAuthenticationAPISchema:
      title: ThreeDSecureAuthenticationAPISchema
      required:
        - responseCode
      type: object
      properties:
        responseCode:
          $ref: '#/components/schemas/ThreeDSecureAuthResponseCodeEnum'
        reasonCode:
          title: Reasoncode
          anyOf:
            - $ref: '#/components/schemas/ThreeDSecureSkippedReasonCodeEnum'
            - $ref: '#/components/schemas/ThreeDSecureFailedReasonCodeEnum'
        reasonText:
          title: Reasontext
          type: string
        protocolVersion:
          title: Protocolversion
          type: string
        challengeIssued:
          title: Challengeissued
          type: boolean

    ThreeDSecureFailedReasonCodeEnum:
      title: ThreeDSecureFailedReasonCodeEnum
      enum:
        - UNKNOWN
        - REJECTED_BY_ISSUER
        - CARD_AUTHENTICATION_FAILED
        - UNKNOWN_DEVICE
        - UNSUPPORTED_DEVICE
        - EXCEEDS_AUTHENTICATION_FREQUENCY_LIMIT
        - EXPIRED_CARD
        - INVALID_CARD_NUMBER
        - INVALID_TRANSACTION
        - NO_CARD_RECORD
        - SECURITY_FAILURE
        - STOLEN_CARD
        - SUSPECTED_FRAUD
        - TRANSACTION_NOT_PERMITTED_TO_CARDHOLDER
        - CARDHOLDER_NOT_ENROLLED_IN_SERVICE
        - TRANSACTION_TIMED_OUT_AT_THE_ACS
        - LOW_CONFIDENCE
        - MEDIUM_CONFIDENCE
        - HIGH_CONFIDENCE
        - VERY_HIGH_CONFIDENCE
        - EXCEEDS_ACS_MAXIMUM_CHALLENGES
        - NON_PAYMENT_NOT_SUPPORTED
        - THREE_RI_NOT_SUPPORTED
        - ACS_TECHNICAL_ISSUE
        - DECOUPLED_REQUIRED_BY_ACS
        - DECOUPLED_MAX_EXPIRY_EXCEEDED
        - DECOUPLED_AUTHENTICATION_INSUFFICIENT_TIME
        - AUTHENTICATION_ATTEMPTED_BUT_NOT_PERFORMED_BY_CARDHOLDER
        - ACS_TIMED_OUT
        - INVALID_ACS_RESPONSE
        - ACS_SYSTEM_ERROR_RESPONSE
        - ERROR_GENERATING_CAVV
        - PROTOCOL_VERSION_NOT_SUPPORTED
        - TRANSACTION_EXCLUDED_FROM_ATTEMPTS_PROCESSING
        - REQUESTED_PROGRAM_NOT_SUPPORTED
      type: string
      description: >-
        This enum is derived from the `transStatusReason` on page 218 of the

        [EMV Co 3DS protocol specification](https://www.emvco.com/terms-of-use/?u=/wp-content/uploads/documents/EMVCo_3DS_Spec_v220_122018.pdf)


        | Code | Description                             |

        |------|-----------------------------------------|

        | 01   | Card authentication failed              |

        | 02   | Unknown Device                          |

        | 03   | Unsupported Device                      |

        | 04   | Exceeds authentication frequency limit  |

        | 05   | Expired card                            |

        | 06   | Invalid card number                     |

        | 07   | Invalid transaction                     |

        | 08   | No Card record                          |

        | 09   | Security failure                        |

        | 10   | Stolen card                             |

        | 11   | Suspected fraud                         |

        | 12   | Transaction not permitted to cardholder |

        | 13   | Cardholder not enrolled in service      |

        | 14   | Transaction timed out at the ACS        |

        | 15   | Low confidence                          |

        | 16   | Medium confidence                       |

    ThreeDSecureSkippedReasonCodeEnum:
      title: ThreeDSecureSkippedReasonCodeEnum
      enum:
        - GATEWAY_UNAVAILABLE
        - DISABLED_BY_MERCHANT
        - NOT_SUPPORTED_BY_ISSUER
        - FAILED_TO_NEGOTIATE
        - UNKNOWN_ACS_RESPONSE
        - 3DS_SERVER_ERROR
        - ACQUIRER_NOT_CONFIGURED
        - ACQUIRER_NOT_PARTICIPATING
        - EXEMPTION_ACCEPTED
      type: string
      description: An enumeration.

    TokenTypeEnum:
      title: TokenTypeEnum
      enum:
        - MULTI_USE
        - SINGLE_USE
      type: string
      description: An enumeration.

    DeclineTypeEnum:
      title: DeclineTypeEnum
      enum:
        - SOFT_DECLINE
        - HARD_DECLINE
      type: string
      description: An enumeration.

    TransactionDeclineReasonV2Enum:
      title: TransactionDeclineReasonV2Enum
      enum:
        - ERROR
        - INVALID_CARD_NUMBER
        - EXPIRED_CARD
        - LOST_OR_STOLEN_CARD
        - SUSPECTED_FRAUD
        - UNKNOWN
        - DECLINED
        - REFER_TO_CARD_ISSUER
        - DO_NOT_HONOR
        - INSUFFICIENT_FUNDS
        - WITHDRAWAL_LIMIT_EXCEEDED
        - ISSUER_TEMPORARILY_UNAVAILABLE
        - AUTHENTICATION_REQUIRED
      type: string
      description: An enumeration.

    AdvisedActionEnum:
      title: AdvisedActionEnum
      enum:
        - RETRY_LATER
        - UPDATE_DATA
        - DO_NOT_RETRY
        - STOP_ALL_PAYMENTS
      type: string
      description: |
        The Primer-recommended action to take based on the underlying decline reason and advice code. This advised action is unified across all supported processors and payment methods.

        - `RETRY_LATER`: The payment was likely declined due to a temporary issue (e.g. Insufficient funds). The payment can be retried immediately or at a later date. 
        - `UPDATE_DATA`: The payment was likely declined because critical data was missing or out-of-date. Please ensure you use the most up-to-date payment information and customer details before retrying the payment.
        - `DO_NOT_RETRY`: The payment was declined and should not be retried. You can still charge this payment method for future orders or installments.
        - `STOP_ALL_PAYMENTS`: The processor or payment method explicitly informs you to stop making any payment requests with this payment method. Please use another payment method to charge this customer.
        - `null`: Primer is unable to determine a recommended action. 

    TransactionEventApiResponse:
      type: object
      required:
        - id
        - date
        - type
      properties:
        id:
          type: string
          description: The id of the event.
          format: uuid
          example: 46d25279-9d36-4237-8f45-2dc4e4e262d6
        processorEventId:
          type: string
          description: >-
            The ID of the event from the payment processor (e.g. PayPal).
          example: 30B258847H402782C
        date:
          type: string
          format: date-time
          description: Timestamp of when the event occurred.
          example: '2025-01-22T13:39:18.992928'
        type:
          type: string
          description: The type of the event.
          enum:
            - AUTHORIZATION_SUCCEEDED
            - AUTHORIZATION_ADJUSTMENT_SUCCEEDED
            - CAPTURE_SUCCEEDED
            - CANCELLATION_SUCCEEDED
          example: CAPTURE_SUCCEEDED
        amount:
          type: integer
          format: int64
          description: The amount associated with the event in minor units.
          example: 1234
        final:
          type: boolean
          description: >-
            Indicates whether the event is final.

            For example, in the case of a capture event this would indicate whether
            it was a final capture or not, but in the case of a cancellation request
            this field will not be present.
          example: false

    TransactionOverviewAPISchema:
      title: TransactionOverviewAPISchema
      required:
        - id
        - processor
        - processorMerchantId
        - type
        - status
        - date
        - amount
        - currencyCode
      type: object
      properties:
        date:
          title: Creation date
          type: string
          description: Date & time of the transaction (UTC)
        amount:
          minimum: 0.0
          type: integer
          format: int64
          description: Transaction amount in minor units
        currencyCode:
          $ref: '#/components/schemas/Currency'
          title: Currency
          description: >
            The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).
            e.g. use `USD` for US dollars.
        orderId:
          title: Order ID
          type: string
          description: The reference submitted on payment creation or refund.
        transactionType:
          $ref: '#/components/schemas/TransactionTypeEnum'
          title: Transaction type
        processorTransactionId:
          title: Processor's transaction ID
          type: string
          description: Processor's unique identifier for the transaction
        processorName:
          title: Processor Name
          type: string
          description: An identifier of a processor.
        processorMerchantId:
          title: Processor master account identifier
          type: string
          description: |
            Processor's main account identifier.

            * Adyen: Account code
            * Braintree: Merchant ID
            * Stripe: Account ID"
        processorStatus:
          $ref: '#/components/schemas/PaymentStatus'
          title: Processor Transaction status
          description: >-
            Transaction status, please refer to the [Transaction Status Codes](#section/API-Usage-Guide/Payment-Status)
            table for more information
        processorStatusReason:
          $ref: '#/components/schemas/StatusReasonAPISchema'
          title: Payment error
          description: |
            If the transaction has a declined or failed status.

            Only if the status is `DECLINED` or `FAILED`, otherwise `null`.
        cardTokenType:
          title: Card token type used
          allOf:
            - $ref: '#/components/schemas/CardTokenTypeEnum'
          description: |
            The type of card token used for the payment.

            Only applies for card payments.
          example: CARD_PAN
        reason:
          title: Reason
          type: string
          description: |
            The reason for a cancel or refund request on this transaction, if any.
          example: Item returned.
        events:
          title: Events
          type: array
          description: >-
            A list of events related to the transaction, included when the `expand`
            parameter is passed.
          items:
            $ref: '#/components/schemas/TransactionEventApiResponse'

    PaymentStatus:
      title: PaymentStatus
      enum:
        - PENDING
        - FAILED
        - AUTHORIZED
        - SETTLING
        - PARTIALLY_SETTLED
        - SETTLED
        - DECLINED
        - CANCELLED
      type: string
      description: An enumeration.

    PaymentStatusTypeEnum:
      title: PaymentStatusTypeEnum
      enum:
        - APPLICATION_ERROR
        - GATEWAY_REJECTED
        - GATEWAY_TIMEOUT
        - ISSUER_DECLINED
      type: string
      description: |
        The status reason type for the payment, providing more information on the error. 
        `APPLICATION_ERROR` indicates something went wrong internally within primer's system. 
        `GATEWAY_REJECTED` indicates that request was rejected on the third-party. 
        `GATEWAY_TIMEOUT` indicates the timeout limit on the third party request was exceeded. 
        `ISSUER_DECLINED` indicates a legitimate decline that is not due to a timeout.

    TransactionTypeEnum:
      title: TransactionTypeEnum
      enum:
        - SALE
        - REFUND
      type: string
      description: An enumeration.

    OptionalAddressAPISchema:
      title: OptionalAddressAPISchema
      type: object
      properties:
        firstName:
          title: First Name
          type: string
          minLength: 1
          maxLength: 255
        lastName:
          title: Last Name
          type: string
          minLength: 1
          maxLength: 255
        addressLine1:
          title: Address Line 1
          type: string
          description: Street name, Company name or PO Box
          minLength: 1
          maxLength: 255
        addressLine2:
          title: Address Line 2
          type: string
          description: Apartment, Unit or Building number
          maxLength: 255
        city:
          title: City
          type: string
          description: Name of the city, district, town or village
          minLength: 1
          maxLength: 255
        state:
          title: State
          type: string
          description: State, County or Province
          minLength: 1
          maxLength: 255
        countryCode:
          $ref: '#/components/schemas/CountryCodeEnum'
          title: Country Code
          description: Two letter ISO country code
        postalCode:
          title: Postal Code
          type: string
          description: Postal or ZIP code
          minLength: 1
          maxLength: 255

    AddressAPISchema:
      title: AddressAPISchema
      required:
        - addressLine1
        - city
        - countryCode
      type: object
      properties:
        firstName:
          title: First Name
          type: string
        lastName:
          title: Last Name
          type: string
        addressLine1:
          title: Address Line 1
          type: string
          description: Street name, Company name or PO Box
        addressLine2:
          title: Address Line 2
          type: string
          description: Apartment, Unit or Building number
        city:
          title: City
          type: string
          description: Name of the city, district, town or village
        state:
          title: State
          type: string
          description: State, County or Province
        countryCode:
          $ref: '#/components/schemas/CountryCodeEnum'
          title: Country Code
          description: Two letter ISO country code
        postalCode:
          title: Postal Code
          type: string
          description: Postal or ZIP code

    MerchantPaymentMethodTokenAPIResponse:
      title: MerchantPaymentMethodTokenAPIResponse
      type: object
      properties:
        createdAt:
          title: Creation date
          type: string
          description: Creation date & time of the object (UTC)
          format: date-time
        deletedAt:
          title: Revocation date
          type: string
          description: Date & time when this object was revoked. (UTC)
          format: date-time
        deleted:
          title: Revoked
          type: boolean
          description: Whether or not this object has been revoked.
        token:
          title: Token
          type: string
          description: The vaulted payment method token.
        tokenType:
          title: Token type
          type: string
          description: >-
            * `MULTI_USE` a vaulted token that can be re-used with subsequent payments
        analyticsId:
          title: Unique analytics ID
          type: string
          description: >-
            Unique analytics identifier corresponding to a payment method
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodTypeEnum'
          title: Payment method type
          description: Payment method type associated with a token.
        paymentMethodData:
          title: Payment method data
          anyOf:
            - $ref: '#/components/schemas/PaymentCardTokenAPISchema'
            - $ref: '#/components/schemas/PayPalBillingAgreementAPISchema'
            - $ref: '#/components/schemas/GoCardlessMandateAPISchema'
            - $ref: '#/components/schemas/KlarnaCustomerTokenAPISchema'
            - $ref: '#/components/schemas/ApayaCustomerTokenAPISchema'
          description: Payment method data
        customerId:
          title: Customer ID
          type: string
          description: The ID representing the customer
        description:
          title: Description
          type: string
          description: A friendly description given by the user
        default:
          title: Default
          type: boolean
          description: Whether or not this payment method is the default
          default: false
      example:
        createdAt: '2021-03-01T12:00:00.123456'
        token: _xlXlmBcTnuFxc2N3HAI73wxNjE1NTU5ODY5
        tokenType: MULTI_USE
        analyticsId: vuXhpZouWxaZpRZ-x_brZmtT
        paymentMethodType: PAYMENT_CARD
        payment_method_data:
          last4Digits: '1111'
          expirationMonth: '12'
          expirationYear: '2030'
          cardholderName: John Biggins
          network: Visa
          networkTransactionId: 020210628190752
          accountFundingType: DEBIT
        customerId: customer-123
        description: My first card
        deleted: false
        default: true

    MerchantPaymentMethodTokenListAPIResponse:
      title: MerchantPaymentMethodTokenListAPIResponse
      type: object
      properties:
        data:
          title: Data
          type: array
          items:
            $ref: '#/components/schemas/MerchantPaymentMethodTokenAPIResponse'

    VaultPaymentMethodAPIRequest:
      title: VaultPaymentMethodAPIRequest
      required:
        - customerId
      type: object
      properties:
        customerId:
          title: Customer ID
          minLength: 1
          type: string
          description: The ID representing the customer
      additionalProperties: false

    PaymentsInsightsBinData:
      type: object
      properties:
        network:
          $ref: '#/components/schemas/CardNetworkEnum'
        issuerCountryCode:
          enum:
            - AW
            - AF
            - AO
            - AI
            - AX
            - AL
            - AD
            - AE
            - AR
            - AM
            - AS
            - AQ
            - TF
            - AG
            - AU
            - AT
            - AZ
            - BI
            - BE
            - BJ
            - BQ
            - BF
            - BD
            - BG
            - BH
            - BS
            - BA
            - BL
            - BY
            - BZ
            - BM
            - BO
            - BR
            - BB
            - BN
            - BT
            - BV
            - BW
            - CF
            - CA
            - CC
            - CH
            - CL
            - CN
            - CI
            - CM
            - CD
            - CG
            - CK
            - CO
            - KM
            - CV
            - CR
            - CU
            - CW
            - CX
            - KY
            - CY
            - CZ
            - DE
            - DJ
            - DM
            - DK
            - DO
            - DZ
            - EC
            - EG
            - ER
            - EH
            - ES
            - EE
            - ET
            - FI
            - FJ
            - FK
            - FR
            - FO
            - FM
            - GA
            - GB
            - GE
            - GG
            - GH
            - GI
            - GN
            - GP
            - GM
            - GW
            - GQ
            - GR
            - GD
            - GL
            - GT
            - GF
            - GU
            - GY
            - HK
            - HM
            - HN
            - HR
            - HT
            - HU
            - ID
            - IM
            - IN
            - IO
            - IE
            - IR
            - IQ
            - IS
            - IL
            - IT
            - JM
            - JE
            - JO
            - JP
            - KZ
            - KE
            - KG
            - KH
            - KI
            - KN
            - KR
            - KW
            - LA
            - LB
            - LR
            - LY
            - LC
            - LI
            - LK
            - LS
            - LT
            - LU
            - LV
            - MO
            - MF
            - MA
            - MC
            - MD
            - MG
            - MV
            - MX
            - MH
            - MK
            - ML
            - MT
            - MM
            - ME
            - MN
            - MP
            - MZ
            - MR
            - MS
            - MQ
            - MU
            - MW
            - MY
            - YT
            - NA
            - NC
            - NE
            - NF
            - NG
            - NI
            - NU
            - NL
            - 'NO'
            - NP
            - NR
            - NZ
            - OM
            - PK
            - PA
            - PN
            - PE
            - PH
            - PW
            - PG
            - PL
            - PR
            - KP
            - PT
            - PY
            - PS
            - PF
            - QA
            - RE
            - RO
            - RU
            - RW
            - SA
            - SD
            - SN
            - SG
            - GS
            - SH
            - SJ
            - SB
            - SL
            - SV
            - SM
            - SO
            - PM
            - RS
            - SS
            - ST
            - SR
            - SK
            - SI
            - SE
            - SZ
            - SX
            - SC
            - SY
            - TC
            - TD
            - TG
            - TH
            - TJ
            - TK
            - TM
            - TL
            - TO
            - TT
            - TN
            - TR
            - TV
            - TW
            - TZ
            - UG
            - UA
            - UM
            - UY
            - US
            - UZ
            - VA
            - VC
            - VE
            - VG
            - VI
            - VN
            - VU
            - WF
            - WS
            - YE
            - ZA
            - ZM
            - ZW
          type: string
          description: >-
            2-letter country code in [ISO 3166-1](

            https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)
            alpha format,

            e.g. FR for France and GB for the United Kingdom.

        issuerName:
          type: string
          description: The name of the issuing bank.
          maxLength: 250
        productUsageType:
          type: string
          description: >-
            The usage type of the payment card e.g. commercial, consumer.
          maxLength: 250
        accountFundingType:
          type: string
          description: >-
            The funding type of the payment card e.g. credit, debit, prepaid.
          maxLength: 250
    PaymentsInsightsOrder:
      type: object
      properties:
        id:
          type: string
          description: The order reference for the payment.
          maxLength: 250
        countryCode:
          enum:
            - AW
            - AF
            - AO
            - AI
            - AX
            - AL
            - AD
            - AE
            - AR
            - AM
            - AS
            - AQ
            - TF
            - AG
            - AU
            - AT
            - AZ
            - BI
            - BE
            - BJ
            - BQ
            - BF
            - BD
            - BG
            - BH
            - BS
            - BA
            - BL
            - BY
            - BZ
            - BM
            - BO
            - BR
            - BB
            - BN
            - BT
            - BV
            - BW
            - CF
            - CA
            - CC
            - CH
            - CL
            - CN
            - CI
            - CM
            - CD
            - CG
            - CK
            - CO
            - KM
            - CV
            - CR
            - CU
            - CW
            - CX
            - KY
            - CY
            - CZ
            - DE
            - DJ
            - DM
            - DK
            - DO
            - DZ
            - EC
            - EG
            - ER
            - EH
            - ES
            - EE
            - ET
            - FI
            - FJ
            - FK
            - FR
            - FO
            - FM
            - GA
            - GB
            - GE
            - GG
            - GH
            - GI
            - GN
            - GP
            - GM
            - GW
            - GQ
            - GR
            - GD
            - GL
            - GT
            - GF
            - GU
            - GY
            - HK
            - HM
            - HN
            - HR
            - HT
            - HU
            - ID
            - IM
            - IN
            - IO
            - IE
            - IR
            - IQ
            - IS
            - IL
            - IT
            - JM
            - JE
            - JO
            - JP
            - KZ
            - KE
            - KG
            - KH
            - KI
            - KN
            - KR
            - KW
            - LA
            - LB
            - LR
            - LY
            - LC
            - LI
            - LK
            - LS
            - LT
            - LU
            - LV
            - MO
            - MF
            - MA
            - MC
            - MD
            - MG
            - MV
            - MX
            - MH
            - MK
            - ML
            - MT
            - MM
            - ME
            - MN
            - MP
            - MZ
            - MR
            - MS
            - MQ
            - MU
            - MW
            - MY
            - YT
            - NA
            - NC
            - NE
            - NF
            - NG
            - NI
            - NU
            - NL
            - 'NO'
            - NP
            - NR
            - NZ
            - OM
            - PK
            - PA
            - PN
            - PE
            - PH
            - PW
            - PG
            - PL
            - PR
            - KP
            - PT
            - PY
            - PS
            - PF
            - QA
            - RE
            - RO
            - RU
            - RW
            - SA
            - SD
            - SN
            - SG
            - GS
            - SH
            - SJ
            - SB
            - SL
            - SV
            - SM
            - SO
            - PM
            - RS
            - SS
            - ST
            - SR
            - SK
            - SI
            - SE
            - SZ
            - SX
            - SC
            - SY
            - TC
            - TD
            - TG
            - TH
            - TJ
            - TK
            - TM
            - TL
            - TO
            - TT
            - TN
            - TR
            - TV
            - TW
            - TZ
            - UG
            - UA
            - UM
            - UY
            - US
            - UZ
            - VA
            - VC
            - VE
            - VG
            - VI
            - VN
            - VU
            - WF
            - WS
            - YE
            - ZA
            - ZM
            - ZW
          type: string
          description: |-
            2-letter country code in [ISO 3166-1](
            https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) alpha format,
            e.g. FR for France and GB for the United Kingdom.
      required:
        - id
    PaymentsInsightsPatchedPayment:
      type: object
      properties:
        paymentId:
          type: string
          description: |-
            The payment ID.

            The payment ID must be unique. You can use this unique payment ID to update payment details.
          maxLength: 250
        currencyCode:
          enum:
            - AED
            - AFN
            - ALL
            - AMD
            - ANG
            - AOA
            - ARS
            - AUD
            - AWG
            - AZN
            - BAM
            - BBD
            - BDT
            - BGN
            - BHD
            - BIF
            - BMD
            - BND
            - BOB
            - BOV
            - BRL
            - BSD
            - BTN
            - BWP
            - BYR
            - BYN
            - BZD
            - CAD
            - CDF
            - CHE
            - CHF
            - CHW
            - CLP
            - CNY
            - COP
            - COU
            - CRC
            - CUC
            - CUP
            - CVE
            - CZK
            - DJF
            - DKK
            - DOP
            - DZD
            - EGP
            - ERN
            - ETB
            - EUR
            - FJD
            - FKP
            - GBP
            - GEL
            - GHS
            - GIP
            - GMD
            - GNF
            - GTQ
            - GYD
            - HKD
            - HNL
            - HRK
            - HTG
            - HUF
            - IDR
            - ILS
            - INR
            - IQD
            - IRR
            - ISK
            - JMD
            - JOD
            - JPY
            - KES
            - KGS
            - KHR
            - KMF
            - KPW
            - KRW
            - KWD
            - KYD
            - KZT
            - LAK
            - LBP
            - LKR
            - LRD
            - LSL
            - LYD
            - MAD
            - MDL
            - MKD
            - MMK
            - MNT
            - MOP
            - MRO
            - MUR
            - MVR
            - MWK
            - MXN
            - MXV
            - MYR
            - MZN
            - NAD
            - NGN
            - NIO
            - NOK
            - NPR
            - NZD
            - OMR
            - PAB
            - PEN
            - PGK
            - PHP
            - PKR
            - PLN
            - PYG
            - QAR
            - RON
            - RSD
            - RUB
            - RWF
            - SAR
            - SBD
            - SCR
            - SDG
            - SEK
            - SGD
            - SHP
            - SOS
            - SRD
            - SSP
            - SVC
            - SYP
            - SZL
            - THB
            - TJS
            - TMT
            - TND
            - TOP
            - TRY
            - TTD
            - TWD
            - TZS
            - UAH
            - UGX
            - USD
            - UYU
            - UZS
            - VND
            - VUV
            - WST
            - XAF
            - XAG
            - XAU
            - XBA
            - XBB
            - XBC
            - XBD
            - XCD
            - XDR
            - XFU
            - XOF
            - XPD
            - XPF
            - XPT
            - XSU
            - XTS
            - XUA
            - YER
            - ZAR
            - ZMW
            - ZWL
          type: string
          description: |-
            The 3-letter currency code in
            [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).

            e.g. use `USD` for US dollars.
        processor:
          $ref: '#/components/schemas/PaymentsInsightsProcessor'
        amount:
          type: integer
          format: int64
          minimum: 0
          description: |-
            The amount you would like to charge the customer,
            in minor units. e.g. for $7, use `700`.

            Some currencies, such as Japanese Yen, do not have minor units.
            In this case you should use the value as it is, without any formatting.
            For example for ¥100, use `100`.
            The minimum amount is 0. The maximum amount is the limit of `int64`.
        createdAt:
          type: string
          format: date-time
          description: |-
            The payment creation date and time (UTC) in [ISO 8601 format](
            https://en.wikipedia.org/wiki/ISO_8601).

            Cannot be updated in partial updates PATCH.
        order:
          $ref: '#/components/schemas/PaymentsInsightsOrder'
        status:
          enum:
            - DECLINED
            - CANCELLED
            - FAILED
            - SETTLING
            - PARTIALLY_SETTLED
            - AUTHORIZED
            - SETTLED
            - PENDING
          type: string
          description: |-
            See the payment [lifecycle](
            /docs/payments/primer-concepts#payment-lifecycle) for more information.
        statusReason:
          $ref: '#/components/schemas/PaymentsInsightsStatusReason'
          description: |-
            Pass more information regarding the payment's status in this field.

            This is especially useful when the status is `DECLINED` or `FAILED`.
        paymentMethod:
          $ref: '#/components/schemas/PaymentsInsightsPaymentMethod'
        metadata:
          type: object
          description: |-
            Additional data to be used throughout the payment lifecycle.

            Ad dictionary of key-value pairs where the values can only be strings or integers.

            e.g. `{"productId": 1001, "merchantId": "88278a"}`
        paymentType:
          enum:
            - FIRST_PAYMENT
            - ECOMMERCE
            - SUBSCRIPTION
            - UNSCHEDULED
          type: string
          description: |-
            Payment types, primarily to be used for recurring payments.
            See the table below for all possible values. 

            Note: if no field is set, we will return a blank value and make a best effort
            to calculate the downstream fields required for processing the payment.

            | paymentType | Use case |
            | --- | --- |
            | `FIRST_PAYMENT` | a customer-initiated payment which is the first in a series of recurring payments or subscription, or a card on file scenario. |
            | `ECOMMERCE` | a customer-initiated payment using stored payment details where the cardholder is present. |
            | `SUBSCRIPTION` | a merchant-initiated payment as part of a series of payments on a fixed schedule and a set amount. |
            | `UNSCHEDULED` | a merchant-initiated payment using stored payment details with no fixed schedule or amount. |

        descriptor:
          type: string
          description: |-
            A description of the payment,
            as it would typically appear on a bank statement.
          maxLength: 250
    PaymentsInsightsPayment:
      type: object
      properties:
        paymentId:
          type: string
          description: |-
            The payment ID.

            The payment ID must be unique. You can use this unique payment ID to update payment details.
          maxLength: 250
        currencyCode:
          enum:
            - AED
            - AFN
            - ALL
            - AMD
            - ANG
            - AOA
            - ARS
            - AUD
            - AWG
            - AZN
            - BAM
            - BBD
            - BDT
            - BGN
            - BHD
            - BIF
            - BMD
            - BND
            - BOB
            - BOV
            - BRL
            - BSD
            - BTN
            - BWP
            - BYR
            - BYN
            - BZD
            - CAD
            - CDF
            - CHE
            - CHF
            - CHW
            - CLP
            - CNY
            - COP
            - COU
            - CRC
            - CUC
            - CUP
            - CVE
            - CZK
            - DJF
            - DKK
            - DOP
            - DZD
            - EGP
            - ERN
            - ETB
            - EUR
            - FJD
            - FKP
            - GBP
            - GEL
            - GHS
            - GIP
            - GMD
            - GNF
            - GTQ
            - GYD
            - HKD
            - HNL
            - HRK
            - HTG
            - HUF
            - IDR
            - ILS
            - INR
            - IQD
            - IRR
            - ISK
            - JMD
            - JOD
            - JPY
            - KES
            - KGS
            - KHR
            - KMF
            - KPW
            - KRW
            - KWD
            - KYD
            - KZT
            - LAK
            - LBP
            - LKR
            - LRD
            - LSL
            - LYD
            - MAD
            - MDL
            - MKD
            - MMK
            - MNT
            - MOP
            - MRO
            - MUR
            - MVR
            - MWK
            - MXN
            - MXV
            - MYR
            - MZN
            - NAD
            - NGN
            - NIO
            - NOK
            - NPR
            - NZD
            - OMR
            - PAB
            - PEN
            - PGK
            - PHP
            - PKR
            - PLN
            - PYG
            - QAR
            - RON
            - RSD
            - RUB
            - RWF
            - SAR
            - SBD
            - SCR
            - SDG
            - SEK
            - SGD
            - SHP
            - SOS
            - SRD
            - SSP
            - SVC
            - SYP
            - SZL
            - THB
            - TJS
            - TMT
            - TND
            - TOP
            - TRY
            - TTD
            - TWD
            - TZS
            - UAH
            - UGX
            - USD
            - UYU
            - UZS
            - VND
            - VUV
            - WST
            - XAF
            - XAG
            - XAU
            - XBA
            - XBB
            - XBC
            - XBD
            - XCD
            - XDR
            - XFU
            - XOF
            - XPD
            - XPF
            - XPT
            - XSU
            - XTS
            - XUA
            - YER
            - ZAR
            - ZMW
            - ZWL
          type: string
          description: |-
            The 3-letter currency code in
            [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).

            e.g. use `USD` for US dollars.
        processor:
          $ref: '#/components/schemas/PaymentsInsightsProcessor'
        amount:
          type: integer
          minimum: 0
          format: int64
          description: |-
            The amount you would like to charge the customer,
            in minor units. e.g. for $7, use `700`.

            Some currencies, such as Japanese Yen, do not have minor units.
            In this case you should use the value as it is, without any formatting.
            For example for ¥100, use `100`.
            The minimum amount is 0. The maximum amount is the limit of `int64`.
        createdAt:
          type: string
          format: date-time
          description: |-
            The payment creation date and time (UTC) in [ISO 8601 format](
            https://en.wikipedia.org/wiki/ISO_8601).

            Cannot be updated in partial updates PATCH.
        order:
          $ref: '#/components/schemas/PaymentsInsightsOrder'
        status:
          enum:
            - DECLINED
            - CANCELLED
            - FAILED
            - SETTLING
            - PARTIALLY_SETTLED
            - AUTHORIZED
            - SETTLED
            - PENDING
          type: string
          description: |-
            See the payment [lifecycle](
            /docs/payments/primer-concepts#payment-lifecycle) for more information.
        statusReason:
          $ref: '#/components/schemas/PaymentsInsightsStatusReason'
          description: |-
            Pass more information regarding the payment's status in this field.

            This is especially useful when the status is `DECLINED` or `FAILED`.
        paymentMethod:
          $ref: '#/components/schemas/PaymentsInsightsPaymentMethod'
        metadata:
          type: object
          description: |-
            Additional data to be used throughout the payment lifecycle.

            Ad dictionary of key-value pairs where the values can only be strings or integers.

            e.g. `{"productId": 1001, "merchantId": "88278a"}`
        paymentType:
          enum:
            - FIRST_PAYMENT
            - ECOMMERCE
            - SUBSCRIPTION
            - UNSCHEDULED
          type: string
          description: |
            Payment types, primarily to be used for recurring payments.
            See the table below for all possible values. 

            Note: if no field is set, we will return a blank value and make a best effort
            to calculate the downstream fields required for processing the payment.


            | paymentType | Use case |
            | --- | --- |
            | `FIRST_PAYMENT` | a customer-initiated payment which is the first in a series of recurring payments or subscription, or a card on file scenario. |
            | `ECOMMERCE` | a customer-initiated payment using stored payment details where the cardholder is present. |
            | `SUBSCRIPTION` | a merchant-initiated payment as part of a series of payments on a fixed schedule and a set amount. |
            | `UNSCHEDULED` | a merchant-initiated payment using stored payment details with no fixed schedule or amount. |
        descriptor:
          type: string
          description: |-
            A description of the payment,
            as it would typically appear on a bank statement.
          maxLength: 250
      required:
        - amount
        - createdAt
        - currencyCode
        - order
        - paymentId
        - paymentMethod
        - processor
    PaymentsInsightsPaymentMethod:
      type: object
      properties:
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodTypeEnum'
          description: Payment method type used for payment authorization.
        data:
          $ref: '#/components/schemas/PaymentsInsightsPaymentMethodData'
        threeDSecureAuthentication:
          $ref: >-
            #/components/schemas/PaymentsInsightsThreeDSecureAuthentication
      required:
        - paymentMethodType
    PaymentsInsightsPaymentMethodData:
      type: object
      properties:
        binData:
          $ref: '#/components/schemas/PaymentsInsightsBinData'
        first6Digits:
          type: string
          description: |-
            The first six digits of the card used for payment,
            also known as the Bank Identification Number (BIN).
          maxLength: 250
    PaymentsInsightsProcessor:
      type: object
      properties:
        name:
          enum:
            - APAYA
            - ADYEN
            - AFTERPAY
            - AIRWALLEX
            - ALIANT
            - ALIPAY
            - ATOME
            - BANKED
            - BARCLAYCARD
            - BRAINTREE
            - BUCKAROO
            - BRIDGE
            - CHAI
            - CHECKOUT
            - CLEARPAY
            - COINBASE
            - CYBERSOURCE
            - DLOCAL
            - EBANX
            - ECOSPEND
            - FINTECTURE
            - GLOBAL_PAYMENTS
            - HOOLAH
            - INGENICO
            - INGENICO-CONNECT
            - KLARNA
            - LAYBUY
            - MPGS
            - MOLLIE
            - NEONOMICS
            - NEXI
            - NUVEI
            - OMISE
            - OPENNODE
            - PAY_NL
            - PAY-NL
            - PAYGENT
            - PAYPAL
            - PRIMER_TEST
            - STRIPE
            - TRILO
            - TRUELAYER
            - VOLT
            - VYNE
            - WORLDPAY
            - EMERCHANTPAY
            - XFERS
            - RAPYD
            - AUTHNET
            - NETS
            - NETAXEPT
            - PRIMER_PROCESSOR
            - REACH
            - TRUST_PAYMENTS
            - TWOC2P
            - MERCADO_PAGO
            - PAYU
            - XENDIT
            - FISERV
            - PACYPAY
            - SHOPEEPAY
            - TRIPLE_A
            - IPAY88
            - APPLE_PAY
            - GOOGLE_PAY
            - RISKIFIED
            - TAXJAR
            - STITCH
            - SIGNIFYD
          type: string
          description: |-
            The payment processor used for this payment.
            Primer supports the above processors through the Payments API,
            however any value can be passed here.
          maxLength: 250
        merchantId:
          type: string
          description: >-
            The merchant ID registered at the payment processor used for this payment.
          maxLength: 250
      required:
        - name
    PaymentsInsightsStatusReason:
      type: object
      properties:
        type:
          enum:
            - APPLICATION_ERROR
            - GATEWAY_REJECTED
            - GATEWAY_TIMEOUT
            - ISSUER_DECLINED
          type: string
          description: |
            The status of the transaction, providing more information on the error. 
            `APPLICATION_ERROR` indicates something went wrong internally within primer's system. 
            `GATEWAY_REJECTED` indicates that request was rejected on the third-party. 
            `GATEWAY_TIMEOUT` indicates the timeout limit on the third party request was exceeded. 
            `ISSUER_DECLINED` indicates a legitimate decline that is not due to a timeout.
        declineType:
          enum:
            - SOFT_DECLINE
            - HARD_DECLINE
          type: string
          description: |
            Declines of type `SOFT_DECLINE` may have been retried.
            Whereas declines of type `HARD_DECLINE` should have not been retried.
        code:
          enum:
            - ERROR
            - INVALID_CARD_NUMBER
            - EXPIRED_CARD
            - LOST_OR_STOLEN_CARD
            - SUSPECTED_FRAUD
            - UNKNOWN
            - DECLINED
            - REFER_TO_CARD_ISSUER
            - DO_NOT_HONOR
            - INSUFFICIENT_FUNDS
            - WITHDRAWAL_LIMIT_EXCEEDED
            - ISSUER_TEMPORARILY_UNAVAILABLE
            - AUTHENTICATION_REQUIRED
          type: string
          description: |-
            Payment status code with the error code when
            the issuer declined the payment.
        message:
          type: string
          description: |-
            Message detail returned by the processor when
            the error on appeared on their part.
          maxLength: 250
    PaymentsInsightsThreeDSecureAuthentication:
      type: object
      properties:
        transStatus:
          type: string
          maxLength: 250
        transStatusReason:
          type: string
          maxLength: 250
        responseCode:
          enum:
            - NOT_PERFORMED
            - SKIPPED
            - AUTH_SUCCESS
            - AUTH_FAILED
            - CHALLENGE
            - METHOD
          type: string
          description: >-
            The response returned during the 3D Secure authentication call.
        challengeIssued:
          type: boolean
          description: |-
            The challenge status of the 3D Secure authentication.
            Set to false for frictionless 3D Secure authentication.
        protocolVersion:
          type: string
          description: The protocol version used during 3D Secure 
            authentication.
          maxLength: 250
        reasonCode:
          type: string
          description: >-
            The reason code for unsuccessful 3D Secure authentication attempts.
          maxLength: 250
        reasonText:
          type: string
          description: |-
            The human readable reason text for unsuccessful
            3D Secure authentication attempts.
          maxLength: 250
        eci:
          type: string
          description: E-commerce Indicator (ECI)
          maxLength: 250

    ErrorObject:
      title: Error
      type: object
      description: >-
        An object containing information about the error that occurred.
      required:
        - errorId
        - description
      properties:
        errorId:
          title: Error ID
          type: string
          description: An error ID
        description:
          title: Error description
          type: string
          description: A human readable description of the error
        recoverySuggestion:
          title: Recovery Suggestion
          type: string
          description: A suggestion on how to recover from the error.
        diagnosticsId:
          title: Error diagnostics ID
          type: string
          description: >-
            An ID that you can quote when contacting the Primer support team via our
            [Support Portal](https://primerapi.atlassian.net/servicedesk/customer/portal/11).
        validationErrors:
          title: Validation Errors
          type: array
          items:
            type: object
          description: Returned in case of a badly formed request

    202AcceptedResponse:
      title: 202AcceptedResponse
      type: object
      properties:
        error:
          type: object
          properties:
            description:
              type: string
              description: A human readable description of the error
            diagnosticsId:
              type: string
              description: >-
                An ID that you can quote when contacting the Primer support team via
                our [Support Portal](https://primerapi.atlassian.net/servicedesk/customer/portal/11).
            errorId:
              type: string
              description: An error ID
            recoverySuggestion:
              type: string
              description: A suggestion on how to recover from the error.
    400ErrorResponse:
      title: 400ErrorResponse
      type: object
      required:
        - error
      properties:
        error:
          allOf:
            - $ref: '#/components/schemas/ErrorObject'
            - type: object
              properties:
                paymentId:
                  title: Payment ID
                  type: string
                  description: Payment ID of the related pay
                paymentStatus:
                  title: Status
                  type: string
                  description: Status of the related payment

    404ErrorResponse:
      title: 404ErrorResponse
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'

    409ErrorResponse:
      title: 409ErrorResponse
      type: object
      required:
        - error
      properties:
        error:
          allOf:
            - $ref: '#/components/schemas/ErrorObject'
            - type: object
              properties:
                paymentId:
                  title: Payment ID
                  type: string
                  description: Payment ID of the related payment
                paymentStatus:
                  title: Status
                  type: string
                  description: Status of the related payment

    422ErrorResponse:
      title: 422ErrorResponse
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'

    AuthorizationTypeEnum:
      title: AuthorizationTypeEnum
      enum:
        - ESTIMATED
        - FINAL
      type: string
      description: Type of authorization for the payment.

    CardTokenTypeEnum:
      title: CardTokenTypeEnum
      enum:
        - CARD_PAN
        - NETWORK_TOKEN
        - PROCESSOR_TOKEN
      type: string
      description: An enumeration.

    FirstPaymentReasonEnum:
      title: FirstPaymentReasonEnum
      enum:
        - CardOnFile
        - Recurring
        - Unscheduled
      type: string
      description: |
        The reason for the first payment. This is used for informing payment processors about the specific reason a payment method is being stored.
        Defaults to None if not provided.

    Expand:
      type: array
      nullable: true
      items:
        type: string
        enum:
          - transactions.events
        example:
          - transactions.events
      description: A list of fields to expand, such as transactions.events.