> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowlix.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve a payment

> Retrieves a payment by ID.



## OpenAPI

````yaml /api-reference/payments-api.yaml get /v1/payments/{id}
openapi: 3.0.4
info:
  title: Flowlix Payments API
  version: 1.0.0
  description: >
    The Flowlix Payments API is a RESTful API for creating and retrieving

    Payments, creating Refunds, and submitting and retrieving Payouts.

    It follows industry-standard conventions: JSON request/response bodies,
    Bearer token authentication,

    standard HTTP verbs, idempotency support, and cursor-based pagination.


    ## Base URL


    API requests are made to `https://api.flowlix.eu`.

    Endpoints are versioned under `/v1`, e.g.

    `https://api.flowlix.eu/v1/payments`.


    ## Amounts and currencies


    All monetary amounts are expressed in **minor units** (the smallest currency
    unit).

    How many minor units make up one major unit is defined by the currency's

    ISO 4217 exponent, so the same integer means a different value in different

    currencies: `4999` is **EUR 49.99** and **GBP 49.99** (exponent 2), but

    **JPY 4999** (exponent 0, no minor unit). Do not assume two decimal places.


    Currencies are three-letter ISO 4217 codes. Requests are accepted

    case-insensitively; Flowlix normalizes them and always returns canonical

    uppercase codes such as `EUR`. The currencies accepted for a Payment or

    Payout are validated separately per request rather than listed in this

    contract, so enabling another currency is not a breaking change. A code

    that is not three letters is rejected with `400 parameter_invalid`

    (`param=currency`), and a well-formed code that Flowlix does not accept for

    the requested operation is rejected with `422 currency_not_supported`.

    Neither response creates a Payment or Payout.


    A refund is always made in the currency of the original payment, and the

    refund request does not accept a currency.
  contact:
    name: Flowlix Developer Support
    email: developers@flowlix.eu
    url: https://flowlix.dev/support
  license:
    name: Proprietary
    url: https://flowlix.dev/terms
servers:
  - url: https://api.flowlix.eu
    description: Flowlix Merchant API.
security:
  - BearerAuth: []
tags:
  - name: Health
    description: Check aggregate Flowlix API availability.
  - name: Payments
    description: Create, retrieve, and list payments.
  - name: Payouts
    description: Submit, list, and retrieve Host-to-Host card payouts.
  - name: Refunds
    description: >-
      Create refunds and track their status through the parent payment's
      `refunds` array.
paths:
  /v1/payments/{id}:
    get:
      tags:
        - Payments
      summary: Retrieve a payment
      description: Retrieves a payment by ID.
      operationId: getPayment
      parameters:
        - $ref: '#/components/parameters/PaymentId'
      responses:
        '200':
          description: |
            The current Payment object. Use `status`, `next_action`,
            `failure_code`, `amount_refundable`, and `refunds` to decide the
            next merchant-side action.
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
              examples:
                pending:
                  $ref: '#/components/examples/HppPaymentPending'
                requires_action:
                  $ref: '#/components/examples/DirectPaymentRequiresAction'
                processing:
                  $ref: '#/components/examples/DirectPaymentProcessing'
                succeeded:
                  $ref: '#/components/examples/PaymentSucceeded'
                failed:
                  $ref: '#/components/examples/DirectPaymentFailed'
                expired:
                  $ref: '#/components/examples/PaymentExpired'
        '400':
          $ref: '#/components/responses/PaymentReadBadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/PaymentNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    PaymentId:
      name: id
      in: path
      required: true
      description: Payment ID.
      schema:
        $ref: '#/components/schemas/PaymentId'
  headers:
    RequestId:
      description: >-
        A unique identifier for this API request. Include it when contacting
        support.
      schema:
        type: string
        maxLength: 255
      example: req_abc123def456
    RetryAfter:
      description: Number of seconds to wait before retrying.
      schema:
        type: integer
      example: 5
  schemas:
    Payment:
      type: object
      description: |
        A Payment represents one attempt to collect funds from the customer.
        Merchants can use `merchant_reference` to associate multiple
        payment attempts with the same order or checkout in their own systems.
      required:
        - id
        - amount
        - currency
        - status
        - created_at
        - livemode
        - amount_refunded
        - amount_refundable
        - integration_type
      properties:
        id:
          $ref: '#/components/schemas/PaymentId'
        amount:
          type: integer
          format: int64
          minimum: 1
          description: >-
            Payment amount in the currency's minor units, per its ISO 4217
            exponent: `4999` is EUR 49.99 but JPY 4999.
          example: 4999
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        status:
          $ref: '#/components/schemas/PaymentStatus'
        integration_type:
          $ref: '#/components/schemas/IntegrationType'
        merchant_reference:
          type: integer
          allOf:
            - $ref: '#/components/schemas/MerchantReference'
          nullable: true
          description: Merchant-side reconciliation reference, if provided.
        description:
          type: string
          nullable: true
          description: Merchant-provided payment description.
          example: 'Order #1234'
        card:
          type: object
          allOf:
            - $ref: '#/components/schemas/Card'
          nullable: true
          description: Masked card details, or `null` before card details are available.
        billing_details:
          type: object
          allOf:
            - $ref: '#/components/schemas/BillingDetails'
          nullable: true
          description: Billing details captured for the payment, if available.
        failure_code:
          type: string
          allOf:
            - $ref: '#/components/schemas/OperationFailureCode'
          nullable: true
          description: >-
            Machine-readable reason code when the payment reaches a terminal
            failed status.
          example: insufficient_funds
        failure_message:
          type: string
          nullable: true
          description: >-
            Human-readable explanation when the payment reaches a terminal
            failed status.
          example: The card has insufficient funds.
        amount_refunded:
          type: integer
          format: int64
          minimum: 0
          description: >-
            Total amount successfully refunded so far, in the payment currency's
            minor units, per its ISO 4217 exponent.
          example: 0
        amount_refundable:
          type: integer
          format: int64
          minimum: 0
          description: >-
            Remaining amount that can be refunded, in the payment currency's
            minor units, per its ISO 4217 exponent.
          example: 4999
        refunds:
          type: array
          description: Refunds created for this payment, oldest first.
          items:
            $ref: '#/components/schemas/Refund'
          default: []
        status_transitions:
          $ref: '#/components/schemas/StatusTransitions'
        created_at:
          type: integer
          format: int64
          description: Unix timestamp when the payment was created.
          example: 1719792000
        livemode:
          type: boolean
          description: Always `false` for a Payment created in Sandbox.
          example: false
        next_action:
          type: object
          allOf:
            - $ref: '#/components/schemas/PaymentNextAction'
          nullable: true
          description: Customer action required to continue the payment.
    PaymentId:
      type: string
      pattern: ^pay_[A-Za-z0-9]{24}$
      description: >-
        Unique opaque identifier for a payment (`pay_` prefix + random
        alphanumeric suffix).
      example: pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E
    CurrencyCode:
      type: string
      minLength: 3
      maxLength: 3
      pattern: ^[A-Z]{3}$
      description: >
        Canonical uppercase three-letter ISO 4217 currency code. Responses
        always

        return the original currency the payment was created in; a provider

        response never replaces it.
      example: EUR
    PaymentStatus:
      type: string
      enum:
        - PENDING
        - REQUIRES_ACTION
        - PROCESSING
        - SUCCEEDED
        - FAILED
        - EXPIRED
      description: >
        Current status of a payment attempt.


        - `PENDING` -- The payment was accepted by Flowlix and is awaiting
        provider submission or the next lifecycle decision.

        - `REQUIRES_ACTION` -- Customer action is required, such as completing
        3D Secure authentication or a hosted payment page.

        - `PROCESSING` -- The payment is being processed by downstream payment
        systems.

        - `SUCCEEDED` -- The payment completed successfully.

        - `FAILED` -- The payment was declined or failed permanently.

        - `EXPIRED` -- The customer did not complete a required action before
        its expiry time.
      example: SUCCEEDED
    IntegrationType:
      type: string
      enum:
        - DIRECT
        - HOSTED_PAYMENT_PAGE
      description: |
        How the payment was collected. This is separate from the payment method
        instrument, such as `card`.
      example: DIRECT
    MerchantReference:
      type: integer
      format: int64
      minimum: 1000000000
      maximum: 9999999999
      description: |
        Optional merchant-side reconciliation reference. The value must contain
        exactly 10 decimal digits and does not provide idempotency by itself.
      example: 1234567890
    Card:
      type: object
      description: >-
        Masked card details. If card details are not available, the entire
        `card` field is `null`.
      required:
        - brand
        - last4
        - exp_month
        - exp_year
      properties:
        brand:
          $ref: '#/components/schemas/CardBrand'
        last4:
          type: string
          pattern: ^[0-9]{4}$
          description: Last four digits of the card number.
          example: '2207'
        exp_month:
          type: integer
          format: int32
          minimum: 1
          maximum: 12
          description: Card expiration month.
          example: 12
        exp_year:
          type: integer
          format: int32
          description: Card expiration year.
          example: 2027
        cardholder_name:
          type: string
          nullable: true
          description: >-
            Cardholder name, if available. For Direct API payments, this is the
            submitted `holder_name`.
          example: Jenny Rosen
        country:
          type: string
          nullable: true
          description: Two-letter ISO country code of the issuing bank, if available.
          allOf:
            - $ref: '#/components/schemas/CountryCode'
    BillingDetails:
      type: object
      description: Billing details associated with the payer.
      properties:
        email:
          type: string
          nullable: true
          format: email
          description: Billing email address.
          example: jenny@example.com
        first_name:
          type: string
          nullable: true
          description: Payer first name.
          example: Jenny
        last_name:
          type: string
          nullable: true
          description: Payer last name.
          example: Rosen
        phone:
          type: string
          nullable: true
          pattern: ^\+[1-9]\d{1,14}$
          description: Billing phone number in E.164 format, for example `+491701234567`.
          example: '+491701234567'
        address:
          type: object
          allOf:
            - $ref: '#/components/schemas/BillingAddress'
          nullable: true
    OperationFailureCode:
      type: string
      description: >-
        Stable public failure vocabulary used by Payment `failure_code`, Refund
        `failure.code`, and Payout `failure_code`. The meaning is shared, but
        handling differs: shopper or new-card actions for a Payment must not be
        applied to a Refund or Payout.
      enum:
        - not_found
        - processor_error
        - processor_unavailable
        - generic_decline
        - do_not_honor
        - issuer_declined
        - insufficient_funds
        - invalid_number
        - invalid_expiry
        - expired_card
        - invalid_amount
        - invalid_currency
        - not_permitted
        - cardholder_limit
        - card_velocity_exceeded
        - lost_card
        - stolen_card
        - suspect_fraud
        - fraud_filter
        - three_d_secure_failed
        - three_d_secure_timeout
        - three_d_secure_not_supported
        - three_d_secure_error
      example: insufficient_funds
    Refund:
      type: object
      description: A refund against a payment.
      required:
        - id
        - payment_id
        - amount
        - currency
        - reason
        - refund_type
        - status
        - created_at
        - updated_at
        - livemode
      properties:
        id:
          $ref: '#/components/schemas/RefundId'
        payment_id:
          $ref: '#/components/schemas/PaymentId'
        amount:
          type: integer
          format: int64
          minimum: 1
          description: >-
            Refund amount in the currency's minor units, per its ISO 4217
            exponent: `4999` is EUR 49.99 but JPY 4999.
          example: 1500
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        merchant_reference:
          type: integer
          allOf:
            - $ref: '#/components/schemas/MerchantReference'
          nullable: true
          description: Merchant-side reconciliation reference for this refund, if provided.
        reason:
          type: string
          maxLength: 50
          description: Merchant-provided refund reason stored with the refund.
          example: Full refund verification
        refund_type:
          $ref: '#/components/schemas/RefundType'
        status:
          $ref: '#/components/schemas/RefundStatus'
        failure:
          $ref: '#/components/schemas/RefundFailure'
        created_at:
          type: integer
          format: int64
          description: Unix timestamp when the refund was created.
          example: 1719795600
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp when the refund was last updated.
          example: 1719795660
        completed_at:
          type: integer
          nullable: true
          format: int64
          description: Unix timestamp when the refund reached a terminal status.
          example: 1719799200
        livemode:
          type: boolean
          description: Always `false` for a Refund created in Sandbox.
          example: false
    StatusTransitions:
      type: object
      description: Timestamps for important payment status transitions.
      properties:
        requires_action_at:
          type: integer
          nullable: true
          format: int64
          description: Unix timestamp when the payment first required customer action.
          example: null
        processing_at:
          type: integer
          nullable: true
          format: int64
          description: Unix timestamp when downstream processing started.
          example: 1719792002
        succeeded_at:
          type: integer
          nullable: true
          format: int64
          description: Unix timestamp when the payment succeeded.
          example: 1719792042
        failed_at:
          type: integer
          nullable: true
          format: int64
          description: Unix timestamp when the payment failed.
          example: null
        expired_at:
          type: integer
          nullable: true
          format: int64
          description: Unix timestamp when the payment expired.
          example: null
    PaymentNextAction:
      type: object
      required:
        - type
        - reason
        - redirect_url
      properties:
        type:
          type: string
          enum:
            - redirect
          description: The action type. Currently only `redirect` is supported.
          example: redirect
        reason:
          type: string
          enum:
            - hosted_payment_page
            - three_d_secure
          description: Why the customer redirect is required.
          example: three_d_secure
        redirect_url:
          type: string
          format: uri
          description: |
            Opaque provider URL for the current customer browser action. The
            URL can point to a hosted payment page, 3D Secure fingerprint
            collection, or a later authentication/challenge step. Redirect the
            customer to the latest URL returned for the payment, follow a new
            URL if it changes while the payment is still `REQUIRES_ACTION`, and
            avoid repeatedly redirecting the same browser to the same URL.
          example: https://authentication.example/redirect-token
    ApiError:
      type: object
      description: Error response wrapper.
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorBody'
    CardBrand:
      type: string
      description: |
        Canonical lower-case card-network brand, for example `visa`,
        `mastercard`, or `amex`. The schema remains extensible; each operation
        validates its supported brands separately.
      example: visa
    CountryCode:
      type: string
      pattern: ^[A-Z]{2}$
      description: Canonical ISO 3166-1 alpha-2 country code.
      example: DE
    BillingAddress:
      type: object
      description: Billing address associated with the payer.
      properties:
        line1:
          type: string
          nullable: true
          description: First line of the billing street address.
          example: Kurfuerstendamm 21
        line2:
          type: string
          nullable: true
          description: Second line of the billing street address, if present.
          example: Apartment 4B
        city:
          type: string
          nullable: true
          description: Billing city.
          example: Berlin
        state:
          type: string
          nullable: true
          description: Billing state, region, or province, if applicable.
          example: Berlin
        postal_code:
          type: string
          nullable: true
          description: Billing postal code.
          example: '10719'
        country:
          type: string
          nullable: true
          pattern: ^[A-Z]{2}$
          description: Billing country as an ISO 3166-1 alpha-2 code.
          example: DE
    RefundId:
      type: string
      pattern: ^ref_[A-Za-z0-9]{24}$
      description: >-
        Unique opaque identifier for a refund (`ref_` prefix + random
        alphanumeric suffix).
      example: ref_L9xQ4wE2rT8yU6iO3pA7sD1f
    RefundType:
      type: string
      enum:
        - FULL
        - PARTIAL
      description: |
        Whether the refund covers the full original payment amount or only part
        of it.
      example: FULL
    RefundStatus:
      type: string
      enum:
        - PENDING
        - PROCESSING
        - SUCCEEDED
        - FAILED
      description: |
        Current refund lifecycle status. Refunds normally move from `PENDING`
        to `PROCESSING`, then to `SUCCEEDED` or `FAILED`.
      example: PENDING
    RefundFailure:
      type: object
      nullable: true
      description: Refund failure details when the refund reaches `FAILED`.
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable Flowlix error code.
          example: fraud_filter
        message:
          type: string
          description: Human-readable Flowlix error explanation.
          example: The payment was declined by fraud controls.
    ApiErrorBody:
      type: object
      description: Detailed error information.
      required:
        - message
      properties:
        code:
          type: string
          nullable: true
          description: Short machine-readable error code.
        message:
          type: string
          description: >-
            Human-readable context that may include object-specific values and
            may change. Branch on `code`, not this text.
        param:
          type: string
          nullable: true
          description: Request parameter that caused the error, if applicable.
        doc_url:
          type: string
          nullable: true
          format: uri
          description: URL to documentation for this error.
        request_id:
          type: string
          nullable: true
          description: Request ID matching the `Request-Id` response header.
  examples:
    HppPaymentPending:
      summary: Hosted Payment Page outcome is pending review
      value:
        id: pay_v2Pr7Su3Aw9Cy1De4Fg8Hi0K
        amount: 2500
        currency: EUR
        status: PENDING
        integration_type: HOSTED_PAYMENT_PAGE
        merchant_reference: 2345678901
        description: 'Order #5678'
        amount_refunded: 0
        amount_refundable: 0
        refunds: []
        created_at: 1719792000
        livemode: false
    DirectPaymentRequiresAction:
      summary: Direct Payment requires a 3D Secure browser action
      value:
        id: pay_r8Ln3Oq9Ws5Yu7Za0Bc4De6F
        amount: 4999
        currency: EUR
        status: REQUIRES_ACTION
        integration_type: DIRECT
        merchant_reference: 1234567890
        description: 'Order #1234'
        card:
          brand: visa
          last4: '2207'
          exp_month: 12
          exp_year: 2027
          cardholder_name: Jenny Rosen
        amount_refunded: 0
        amount_refundable: 0
        refunds: []
        status_transitions:
          requires_action_at: 1719792002
        created_at: 1719792000
        livemode: false
        next_action:
          type: redirect
          reason: three_d_secure
          redirect_url: https://authentication.example/redirect-token
    DirectPaymentProcessing:
      summary: Direct Payment is processing without a browser action
      value:
        id: pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E
        amount: 4999
        currency: EUR
        status: PROCESSING
        integration_type: DIRECT
        merchant_reference: 1234567890
        description: 'Order #1234'
        card:
          brand: visa
          last4: '2207'
          exp_month: 12
          exp_year: 2027
          cardholder_name: Jenny Rosen
        amount_refunded: 0
        amount_refundable: 0
        refunds: []
        status_transitions:
          processing_at: 1719792002
        created_at: 1719792000
        livemode: false
    PaymentSucceeded:
      summary: Payment completed successfully
      value:
        id: pay_t0Np5Qs1Yu7Aw9Bc2De6Fg8H
        amount: 4999
        currency: EUR
        status: SUCCEEDED
        integration_type: DIRECT
        merchant_reference: 1234567890
        description: 'Order #1234'
        card:
          brand: visa
          last4: '2207'
          exp_month: 12
          exp_year: 2027
          cardholder_name: Jenny Rosen
        amount_refunded: 0
        amount_refundable: 4999
        refunds: []
        status_transitions:
          processing_at: 1719792002
          succeeded_at: 1719792042
        created_at: 1719792000
        livemode: false
    DirectPaymentFailed:
      summary: Direct Payment ended in a terminal decline
      value:
        id: pay_u1Oq6Rt2Zv8Bx0Cd3Ef7Gh9J
        amount: 4999
        currency: EUR
        status: FAILED
        integration_type: DIRECT
        merchant_reference: 1234567890
        description: 'Order #1234'
        card:
          brand: visa
          last4: '2207'
          exp_month: 12
          exp_year: 2027
          cardholder_name: Jenny Rosen
        failure_code: insufficient_funds
        failure_message: The card has insufficient funds.
        amount_refunded: 0
        amount_refundable: 0
        refunds: []
        status_transitions:
          failed_at: 1719792002
        created_at: 1719792000
        livemode: false
    PaymentExpired:
      summary: Payment browser action expired before completion
      value:
        id: pay_x4Rt9Uw5Cy1Ea3Fg6Hi0Jk2M
        amount: 2500
        currency: EUR
        status: EXPIRED
        integration_type: HOSTED_PAYMENT_PAGE
        merchant_reference: 2345678901
        description: 'Order #5678'
        amount_refunded: 0
        amount_refundable: 0
        refunds: []
        status_transitions:
          requires_action_at: 1719792002
          expired_at: 1719795602
        created_at: 1719792000
        livemode: false
    ErrorInvalidRequest:
      summary: Read request contains an invalid value
      value:
        error:
          code: invalid_request
          message: Request validation failed.
          doc_url: https://docs.flowlix.eu/api-reference/errors
          request_id: req_read400a
    ErrorPaymentIdInvalid:
      summary: Payment ID has an invalid format
      value:
        error:
          code: parameter_invalid
          message: Request parameter is invalid.
          param: id
          doc_url: https://docs.flowlix.eu/guides/errors
          request_id: req_payment400a
    ErrorInvalidApiKey:
      summary: Missing or invalid API key
      value:
        error:
          code: invalid_api_key
          message: The API key is invalid.
          doc_url: https://docs.flowlix.eu/guides/errors
          request_id: req_auth401a
    ErrorPaymentNotFound:
      summary: Payment is absent from the merchant and mode scope
      value:
        error:
          code: object_not_found
          message: Payment 'pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E' was not found.
          doc_url: https://docs.flowlix.eu/api-reference/errors
          request_id: req_payment404a
    ErrorInternal:
      summary: Unexpected Flowlix error
      value:
        error:
          code: internal_error
          message: An internal error occurred.
          doc_url: https://docs.flowlix.eu/guides/errors
          request_id: req_internal500a
    ErrorServiceUnavailable:
      summary: Flowlix is temporarily unavailable
      value:
        error:
          code: service_unavailable
          message: Upstream payment processor is temporarily unavailable. Please retry.
          doc_url: https://docs.flowlix.eu/guides/errors
          request_id: req_service503a
  responses:
    PaymentReadBadRequest:
      description: |
        The Payment ID or another read parameter is invalid. Correct the value
        named by `error.param` when it is present.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            invalid_request:
              $ref: '#/components/examples/ErrorInvalidRequest'
            invalid_parameter:
              $ref: '#/components/examples/ErrorPaymentIdInvalid'
    Unauthorized:
      description: >
        The API key is missing, invalid, expired, or revoked. Send the secret
        key

        for the intended merchant and mode in `Authorization: Bearer <key>`.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            invalid_api_key:
              $ref: '#/components/examples/ErrorInvalidApiKey'
    PaymentNotFound:
      description: |
        The Payment was not found in the authenticated merchant and mode
        scope. Verify the Payment ID and API key mode; do not blind retry.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            object_not_found:
              $ref: '#/components/examples/ErrorPaymentNotFound'
    InternalError:
      description: |
        Flowlix encountered an unexpected server error before the operation
        completed. Retry safely with the original idempotency key for a POST
        and include `Request-Id` when contacting support.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            internal_error:
              $ref: '#/components/examples/ErrorInternal'
    ServiceUnavailable:
      description: |
        Flowlix is temporarily unable to process the request. Wait for
        `Retry-After` when present, then retry with exponential backoff. Reuse
        the same idempotency key when retrying a POST request.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            service_unavailable:
              $ref: '#/components/examples/ErrorServiceUnavailable'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Use the secret API key for the intended merchant and mode as the Bearer
        token. Sandbox keys start with `api_test_sk_`. Send the key only from
        your server environment.

        ```
        Authorization: Bearer api_test_sk_abc123def456
        ```

````