> ## 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.

# Retrieve a payment

> Reads a payment back, including the `status` of the charge and the card it was taken from.

> [!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/{id}
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/{id}:
    get:
      tags:
        - Payments
      summary: Retrieve a payment
      description: >-
        Reads a payment back, including the `status` of the charge and the card
        it was taken from.
      operationId: getPayment
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '403':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/InsufficientPermissionsError'
                  - $ref: '#/components/schemas/NoBannerAssociationError'
        '404':
          description: ''
      security:
        - bearer: []
components:
  schemas:
    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
    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
    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.
    InsufficientPermissionsErrorDetails:
      type: object
      properties:
        action:
          allOf:
            - $ref: '#/components/schemas/Action'
        resource:
          allOf:
            - $ref: '#/components/schemas/Resource'
      required:
        - action
        - resource
    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.
    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
    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)
- [Retrieve a refund](https://help.vori.com/api/refunds/retrieve.md)
- [Retrieve a transaction](https://help.vori.com/api-reference/transactions/retrieve-a-transaction.md)
