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

# Create a payment

> Charges a card your site or app tokenized in the browser, through the payment processor configured for the store. Retrying with the same `idempotency_key` returns the payment already taken instead of charging the card again, and answers a refused card with the same failure. If the processor does not answer, the payment is held back from reads and this call returns a gateway timeout. Vori settles the payment from what the processor has on record, on its own within minutes or sooner when you retry with the same `idempotency_key`, and the retry answers with the outcome once it is known. A payment the processor never received settles as declined and is never charged later, so charge the card again with a new `idempotency_key`. Sending the sales tax, your order reference and the line items with the charge qualifies commercial and purchasing cards for the lower Level 2 and Level 3 interchange rates; the line items and tax must add up to the amount or the payment is refused before anything is charged.

> [!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 POST /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:
    post:
      tags:
        - Payments
      summary: Create a payment
      description: >-
        Charges a card your site or app tokenized in the browser, through the
        payment processor configured for the store. Retrying with the same
        `idempotency_key` returns the payment already taken instead of charging
        the card again, and answers a refused card with the same failure. If the
        processor does not answer, the payment is held back from reads and this
        call returns a gateway timeout. Vori settles the payment from what the
        processor has on record, on its own within minutes or sooner when you
        retry with the same `idempotency_key`, and the retry answers with the
        outcome once it is known. A payment the processor never received settles
        as declined and is never charged later, so charge the card again with a
        new `idempotency_key`. Sending the sales tax, your order reference and
        the line items with the charge qualifies commercial and purchasing cards
        for the lower Level 2 and Level 3 interchange rates; the line items and
        tax must add up to the amount or the payment is refused before anything
        is charged.
      operationId: createPayment
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/DuplicateIdempotencyKeyError'
                  - $ref: '#/components/schemas/InvalidStoreError'
                  - $ref: '#/components/schemas/PaymentAmountDetailsMismatchError'
                  - $ref: '#/components/schemas/PaymentProcessorNotConfiguredError'
        '402':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/CardDeclinedError'
        '403':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/InsufficientPermissionsError'
                  - $ref: '#/components/schemas/NoBannerAssociationError'
        '409':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PaymentInProgressError'
        '504':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PaymentProcessorTimeoutError'
      security:
        - bearer: []
components:
  schemas:
    CreatePaymentRequest:
      type: object
      properties:
        amount:
          type: string
          description: >-
            Amount charged to the card, in dollars. Payments above 99999.99 are
            not accepted.
          format: positive-monetary
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '199.99'
        amount_details:
          description: >-
            Tax and line items the payment covers, each optional. Sending the
            tax with `payment_details.order_reference` qualifies commercial
            cards for the lower Level 2 interchange rate.
          allOf:
            - $ref: '#/components/schemas/PaymentAmountDetails'
        idempotency_key:
          type: string
          maxLength: 255
          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, stored as sent and returned unchanged.
            Vori never interprets them. Up to 50 keys; key names up to 40
            characters of letters, numbers, underscores, and hyphens; values up
            to 500 characters. Keys beginning with "vori" are reserved. Do not
            put personal or sensitive information here — these values flow into
            reporting and data exports.
        payment_details:
          description: Your reference for the purchase.
          allOf:
            - $ref: '#/components/schemas/PaymentDetails'
        store_id:
          type: string
          description: >-
            ID of the store to charge the card for. The charge settles to the
            processor account configured for that store.
          pattern: ^[0-9]+$
        token:
          type: string
          maxLength: 256
          description: >-
            One-time token returned by the hosted tokenizer for the card being
            charged. A token is good for a single charge, so a new payment needs
            a new one. Retrying a payment that timed out may send the token it
            already has, which is only used if the charge never reached the
            processor.
      description: >-
        Charges a card that your site or app tokenized in the browser, using the
        payment processor configured for the store.
      required:
        - amount
        - idempotency_key
        - store_id
        - token
    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
    DuplicateIdempotencyKeyError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - duplicate_idempotency_key
      required:
        - error_code
    InvalidStoreError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - invalid_store
      required:
        - error_code
    PaymentAmountDetailsMismatchError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - payment_amount_details_mismatch
        error_details:
          $ref: '#/components/schemas/PaymentAmountDetailsMismatchErrorDetails'
      required:
        - error_code
        - error_details
    PaymentProcessorNotConfiguredError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - payment_processor_not_configured
        error_details:
          $ref: '#/components/schemas/PaymentProcessorNotConfiguredErrorDetails'
      required:
        - error_code
        - error_details
    CardDeclinedError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - card_declined
        error_details:
          $ref: '#/components/schemas/CardDeclinedErrorDetails'
      required:
        - error_code
        - error_details
    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
    PaymentInProgressError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - payment_in_progress
        error_details:
          $ref: '#/components/schemas/PaymentInProgressErrorDetails'
      required:
        - error_code
        - error_details
    PaymentProcessorTimeoutError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - payment_processor_timeout
        error_details:
          $ref: '#/components/schemas/PaymentProcessorTimeoutErrorDetails'
      required:
        - error_code
        - error_details
    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.
    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
    PaymentMode:
      type: string
      enum:
        - live
        - test
      description: Live or test. A test payment moves no money.
    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.
    PaymentAmountDetailsMismatchErrorDetails:
      type: object
      properties:
        amount:
          type: string
          description: Amount the payment asked for.
          format: monetary
          example: '199.99'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
        amount_details_total:
          type: string
          description: >-
            What the purchase details add up to: every line item unit cost times
            its quantity, plus the tax.
          format: monetary
          example: '199.99'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
      required:
        - amount
        - amount_details_total
    PaymentProcessorNotConfiguredErrorDetails:
      type: object
      properties:
        mode:
          description: >-
            Mode the payment asked for. A store can be set up to take live
            payments but not test ones, or the other way around.
          allOf:
            - $ref: '#/components/schemas/PaymentMode'
        store_id:
          type: string
          description: ID of the store that has no payment processor.
          pattern: ^[0-9]+$
      required:
        - mode
        - store_id
    CardDeclinedErrorDetails:
      type: object
      properties:
        payment_id:
          type: string
          description: ID of the payment the error is about.
        processor_message:
          type: string
          nullable: true
          description: What the payment processor said about the decline, in its own words.
      required:
        - payment_id
        - processor_message
    InsufficientPermissionsErrorDetails:
      type: object
      properties:
        action:
          allOf:
            - $ref: '#/components/schemas/Action'
        resource:
          allOf:
            - $ref: '#/components/schemas/Resource'
      required:
        - action
        - resource
    PaymentInProgressErrorDetails:
      type: object
      properties:
        payment_id:
          type: string
          description: ID of the payment the error is about.
      required:
        - payment_id
    PaymentProcessorTimeoutErrorDetails:
      type: object
      properties:
        payment_id:
          type: string
          description: ID of the payment the error is about.
        refund_id:
          type: string
          description: >-
            ID of the refund the error is about, when the processor was
            answering about a refund of the payment.
      required:
        - payment_id
    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)
- [Create a refund](https://help.vori.com/api/refunds/create.md)
- [Create transactions](https://help.vori.com/api/create-transactions.md)
