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

# List payments

> Lists the payments taken for the stores you can reach in the mode of your API key, newest first. Filter by store or status, and page through the results with the cursor parameters.

> [!WARNING]
>
> Payments and refunds are in beta. Contact Vori Support to enable them for your account. Until they are enabled, these endpoints answer `403 Forbidden`.


## OpenAPI

````yaml api/openapi.json GET /v1/payments
openapi: 3.0.0
info:
  title: Vori API
  description: ''
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.vori.com
    description: production
security: []
tags: []
paths:
  /v1/payments:
    get:
      tags:
        - Payments
      summary: List payments
      description: >-
        Lists the payments taken for the stores you can reach in the mode of
        your API key, newest first. Filter by store or status, and page through
        the results with the cursor parameters.
      operationId: listPayments
      parameters:
        - name: ending_before
          required: false
          in: query
          description: Return records that precede the record with this ID, in list order.
          schema:
            type: string
        - name: limit
          required: false
          in: query
          description: Maximum number of records to return.
          schema:
            minimum: 1
            maximum: 100
            default: 20
            type: integer
        - name: starting_after
          required: false
          in: query
          description: Return records that follow the record with this ID, in list order.
          schema:
            type: string
        - name: status
          required: false
          in: query
          style: form
          explode: true
          description: >-
            Where the payment stands: `captured` once the amount was taken from
            the card, `authorized` while the processor only holds it, and
            `failed` when the card was refused. A payment the processor has not
            answered for yet is not served at all: sending the same request
            again with the same `idempotency_key` and the same `token` settles
            it. Repeat to match any of up to 20 values.
          schema:
            type: array
            items:
              type: string
              enum:
                - authorized
                - captured
                - failed
        - name: store_id
          required: false
          in: query
          style: form
          explode: true
          description: >-
            ID of the store the payment was taken for. Repeat to match any of up
            to 20 values.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentList'
        '400':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ConflictingListParametersError'
                  - $ref: '#/components/schemas/InvalidListCursorError'
        '403':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/InsufficientPermissionsError'
                  - $ref: '#/components/schemas/NoBannerAssociationError'
      security:
        - bearer: []
components:
  schemas:
    PaymentList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
        has_more:
          type: boolean
          description: Whether more records follow this page.
      required:
        - data
        - has_more
    ConflictingListParametersError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - conflicting_list_parameters
      required:
        - error_code
    InvalidListCursorError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - invalid_list_cursor
      required:
        - error_code
    InsufficientPermissionsError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - insufficient_permissions
        error_details:
          $ref: '#/components/schemas/InsufficientPermissionsErrorDetails'
      required:
        - error_code
        - error_details
    NoBannerAssociationError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - no_banner_association
      required:
        - error_code
    Payment:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the record.
        amount:
          type: string
          description: Amount charged to the card, in dollars.
          format: positive-monetary
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '199.99'
        amount_details:
          nullable: true
          description: Tax and line items supplied when the payment was taken.
          type: object
          allOf:
            - $ref: '#/components/schemas/PaymentAmountDetails'
        amount_refunded:
          type: string
          description: >-
            Total of the refunds of the payment that went through, in dollars.
            Refunds that failed or are still with the processor are not counted.
            `0.00` when nothing was refunded.
          format: monetary
          example: '199.99'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
        created_at:
          type: string
          description: When the record was created.
          format: date-time
        idempotency_key:
          type: string
          description: >-
            Your own key for the charge, unique within the banner for each
            `mode`. Sending the same key again returns the payment already taken
            rather than charging the card twice. Up to 255 characters.
        metadata:
          type: object
          maxProperties: 50
          additionalProperties:
            type: string
            maxLength: 500
          example:
            order_source: shopify
            fulfillment_id: '88213'
          nullable: true
          description: >-
            Your own key/value pairs, exactly as supplied when the payment was
            taken.
        mode:
          description: >-
            Whether money moved for real or not, which follows the API key that
            took the payment: `test` runs in the payment processor's test
            environment and never moves money, and `live` takes an actual
            payment.
          allOf:
            - $ref: '#/components/schemas/PaymentMode'
        payment_details:
          nullable: true
          description: Purchase reference supplied when the payment was taken.
          type: object
          allOf:
            - $ref: '#/components/schemas/PaymentDetails'
        payment_method:
          description: The card the payment was taken from.
          allOf:
            - $ref: '#/components/schemas/PaymentMethod'
        processor:
          description: >-
            The payment processor that handled the charge, which is the one
            configured for the store.
          allOf:
            - $ref: '#/components/schemas/PaymentProcessor'
        status:
          description: >-
            Where the payment stands: `captured` once the amount was taken from
            the card, `authorized` while the processor only holds it, and
            `failed` when the card was refused. A payment the processor has not
            answered for yet is not served at all: sending the same request
            again with the same `idempotency_key` and the same `token` settles
            it.
          allOf:
            - $ref: '#/components/schemas/PaymentStatus'
        store_id:
          type: string
          description: ID of the store the payment was taken for.
          pattern: ^[0-9]+$
        updated_at:
          type: string
          description: When the record was last changed.
          format: date-time
      description: >-
        A card payment taken through the Vori API on behalf of a store. One
        payment is one charge attempt, and a payment is never edited once the
        processor has answered.
      required:
        - id
        - amount
        - amount_details
        - amount_refunded
        - created_at
        - idempotency_key
        - metadata
        - mode
        - payment_details
        - payment_method
        - processor
        - status
        - store_id
        - updated_at
    InsufficientPermissionsErrorDetails:
      type: object
      properties:
        action:
          allOf:
            - $ref: '#/components/schemas/Action'
        resource:
          allOf:
            - $ref: '#/components/schemas/Resource'
      required:
        - action
        - resource
    PaymentAmountDetails:
      type: object
      properties:
        line_items:
          maxItems: 10
          description: >-
            What the payment paid for, up to 10 lines. Each line's unit cost
            times its quantity, summed with any tax, must equal the payment
            amount. Commercial cards get the lowest Level 3 interchange rate
            when every line has all its fields and
            `payment_details.order_reference` is sent too.
          type: array
          items:
            $ref: '#/components/schemas/PaymentLineItem'
        tax:
          nullable: true
          description: Tax included in the amount.
          type: object
          allOf:
            - $ref: '#/components/schemas/PaymentTax'
      description: How the amount of a payment breaks down.
    PaymentMode:
      type: string
      enum:
        - live
        - test
      description: Live or test. A test payment moves no money.
    PaymentDetails:
      type: object
      properties:
        order_reference:
          type: string
          maxLength: 17
          pattern: ^[A-Za-z0-9]+$
          example: PO15938
          description: >-
            Your reference for the purchase, such as a purchase order number, up
            to 17 letters and digits. Shown to the cardholder's company on its
            statement and required for the lower Level 2 and Level 3 interchange
            rates on commercial cards.
      description: References that travel with a payment to the card network.
      required:
        - order_reference
    PaymentMethod:
      type: object
      properties:
        brand:
          nullable: true
          description: Card brand the processor reported.
          allOf:
            - $ref: '#/components/schemas/CardBrand'
        last4:
          type: string
          nullable: true
          minLength: 4
          maxLength: 4
          pattern: ^[0-9]{4}$
          example: '1111'
          description: >-
            Last four digits of the card or bank account number, safe to show on
            a receipt.
        type:
          description: >-
            How the payment was made: `card`, or `ach_debit` for a debit from a
            bank account.
          allOf:
            - $ref: '#/components/schemas/OnlinePaymentMethodType'
      description: >-
        The card or bank account a payment was taken from, as the processor saw
        it.
      required:
        - brand
        - last4
        - type
    PaymentProcessor:
      type: string
      enum:
        - datacap
      description: >-
        The payment processor that handled the charge, which is the one
        configured for the store.
    PaymentStatus:
      type: string
      enum:
        - authorized
        - captured
        - failed
      description: >-
        Where the payment stands: `captured` once the amount was taken from the
        card, `authorized` while the processor only holds it, and `failed` when
        the card was refused. A payment the processor has not answered for yet
        is not served at all: sending the same request again with the same
        `idempotency_key` and the same `token` settles it.
    Action:
      type: string
      enum:
        - '*'
        - cancel
        - check_in
        - create
        - delete
        - read
        - read_credentials
        - record_events
        - refund
        - restart
        - update
        - void
    Resource:
      type: string
      enum:
        - '*'
        - accounting_integration
        - agent_chats
        - agent_job_settings
        - agent_tasks
        - agents
        - api_clients
        - asynchronous_tasks
        - banners
        - billing
        - blackhawk_transactions
        - business_entities
        - capabilities
        - coupons
        - custom_quick_actions
        - datacap_transactions
        - departments
        - discounts
        - ditto_auth_tokens
        - doordash_enrollments
        - edge_agents
        - electronic_shelf_labels
        - employees
        - feature_orientations
        - files
        - food_modifiers
        - gift_cards
        - gl_code_mappings
        - house_account_payment_links
        - house_account_payments
        - house_accounts
        - inventory
        - inventory_sessions
        - inventory_settings
        - invoices
        - item_modifiers
        - label_dimension_sets
        - label_sheet_profiles
        - label_stock_products
        - lanes
        - loyalty_bonuses
        - loyalty_campaigns
        - loyalty_rewards
        - notification_templates
        - offers
        - order_guides
        - orders
        - payments
        - people
        - pos_banner_configurations
        - pos_orders
        - pos_tills
        - price_settings
        - price_tags
        - product_attributes
        - product_ranges
        - products
        - promotions
        - purchase_orders
        - receiving
        - reporting
        - revision_sessions
        - revisions
        - roles
        - shopper_tags
        - shoppers
        - store_product_inventory_counts
        - store_product_lots
        - store_product_rules
        - store_product_tag_templates
        - store_snap_incentive_program_coupons
        - store_vendor_merge_requests
        - store_vendor_product_merge_requests
        - store_vendor_products
        - store_vendors
        - stores
        - tag_printings
        - tag_template_presets
        - tag_templates
        - tax_rates
        - users
        - variable_weights
        - vendor_data_requests
        - vendor_merge_requests
        - vendor_product_merge_requests
        - vendor_products
        - vendor_store_department_accounts
        - vendors
        - wallet_payments
        - wic_products
    PaymentLineItem:
      type: object
      properties:
        commodity_code:
          type: string
          nullable: true
          maxLength: 12
          pattern: ^[A-Za-z0-9]+$
          example: '50131700'
          description: >-
            Commodity code for the product in a standard scheme such as UNSPSC,
            up to 12 letters and digits.
        product_code:
          type: string
          nullable: true
          maxLength: 12
          pattern: ^[A-Za-z0-9]+$
          example: SKU002
          description: Your code for the product, up to 12 letters and digits.
        product_name:
          type: string
          nullable: true
          maxLength: 26
          example: Organic bananas
          description: Name of the product, up to 26 characters.
        quantity:
          type: integer
          minimum: 1
          maximum: 999999
          example: 2
          description: How many units were bought.
        unit_cost:
          type: string
          description: Price of one unit before tax, in dollars.
          format: positive-monetary
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '199.99'
        unit_of_measure:
          nullable: true
          description: What one unit is.
          allOf:
            - $ref: '#/components/schemas/PaymentLineItemUnitOfMeasure'
      description: One line of the purchase a payment covered.
      required:
        - quantity
        - unit_cost
    PaymentTax:
      type: object
      properties:
        total_tax_amount:
          type: string
          description: >-
            Sales tax included in the amount, in dollars. Send `0.00` when no
            tax was charged.
          format: monetary
          example: '199.99'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
      description: Tax included in a payment.
      required:
        - total_tax_amount
    CardBrand:
      type: string
      enum:
        - american_express
        - atm
        - bill_me_later
        - china_union_pay
        - debit
        - diners_club
        - discover
        - ebt
        - jcb
        - mastercard
        - other
        - revolution_money
        - telecheck
        - undetermined
        - visa
        - voyager
        - wright_express
    OnlinePaymentMethodType:
      type: string
      enum:
        - ach_debit
        - card
      description: The payment methods the account can be paid with.
    PaymentLineItemUnitOfMeasure:
      type: string
      enum:
        - box
        - case
        - foot
        - gallon_us
        - gram
        - inch
        - kilogram
        - liquid_pint_us
        - liquid_quart_us
        - liter
        - meter
        - ounce
        - pound
        - yard
      description: What one unit is.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````

## Related topics

- [Accept card payments online](https://help.vori.com/api/accept-card-payments-online.md)
- [List refunds](https://help.vori.com/api/refunds/list.md)
- [List transactions](https://help.vori.com/api-reference/transactions/list-transactions.md)
