Toast Payments API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Toast Authentication Payments API
  description: 'The authentication API returns an authentication token that you can present

    when your integration client software uses other Toast APIs. For more

    information about authentication, see [the Toast Developer

    Guide](https://doc.toasttab.com/doc/devguide/authentication.html).

    '
  termsOfService: https://pos.toasttab.com/api-terms-of-use
  contact:
    name: Toast developer support
servers:
- url: https://toast-api-server/authentication/v1
tags:
- name: Payments
  description: 'Related to guests'' payments for restaurant orders. Toast platform

    payments apply to a check in an order.

    '
paths:
  /payments:
    get:
      tags:
      - Payments
      summary: Toast Get Payment Identifiers
      description: 'Returns a list of the GUIDs for each payment made during

        one restaurant business day.


        The specific hours that make up a business

        day depend on the business day cutoff in the restaurant configuration,

        which is available from the restaurants API in the `closeoutHour`

        property.


        The business day for a restaurant is based on its local time (not UTC

        or local time for an API client).


        You must include one of the

        `paidBusinessDate`, `refundBusinessDate`, or `voidBusinessDate` query

        parameters.

        '
      operationId: paymentsGet
      parameters:
      - name: Toast-Restaurant-External-ID
        description: The GUID of the restaurant used as the context of the request.
        in: header
        required: true
        schema:
          type: string
      - name: paidBusinessDate
        description: 'Returns a list of the payments that were made during

          one business day.


          Specify the business day in the format yyyyMMdd.

          For example, `20170101`.

          '
        in: query
        required: false
        schema:
          type: string
      - name: refundBusinessDate
        description: 'Returns a list of the payments that were refunded

          during one business day.


          Specify the business day in the format

          yyyyMMdd. For example, `20170101`.

          '
        in: query
        required: false
        schema:
          type: string
      - name: voidBusinessDate
        description: 'Returns a list of the payments that were voided during

          one business day.


          Specify the business day in the format yyyyMMdd.

          For example, `20170101`.

          '
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A JSON array of the GUID identifiers for the payments.
          content:
            application/json:
              schema:
                title: Response
                type: array
                items:
                  type: string
        '400':
          description: The API cannot process the request.
      security:
      - oauth2:
        - orders:read
  /payments/{guid}:
    get:
      tags:
      - Payments
      summary: Toast Get a Payment
      description: Returns a JSON `Payment` object containing detailed information about a  single payment, specified by its GUID.
      operationId: paymentsGuidGet
      parameters:
      - name: Toast-Restaurant-External-ID
        description: The GUID of the restaurant used as the context of the request.
        in: header
        required: true
        schema:
          type: string
      - name: guid
        description: The GUID for the payment you want to return.
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns a JSON `Payment` object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: The GUID was malformed.
        '404':
          description: The specified payment was not found.
      security:
      - oauth2:
        - orders:read
  /orders/{orderGuid}/checks/{checkGuid}/payments:
    post:
      tags:
      - Payments
      summary: Toast Post Payments
      description: 'Adds one or more payments to a check in an existing order. Include

        information about the payments in an array of `Payment` objects in the

        message body. Specify the Toast platform GUID of the order

        and check in REST path parameters.


        For more information, see [the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiAddingPaymentsToACheck.html).

        '
      operationId: ordersChecksPaymentsPost
      parameters:
      - name: orderGuid
        description: 'The Toast platform identifier of the order that you are

          adding payments to.

          '
        in: path
        required: true
        schema:
          type: string
      - name: checkGuid
        description: 'The Toast platform identifier of the check that you are

          adding payments to.

          '
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'A JSON `Order` object that includes the payments that you added.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: The API cannot process the request.
      security:
      - oauth2:
        - orders.payments:write
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Payment'
        description: 'An array of JSON `Payment` objects containing information about the payments you are adding.

          '
        required: true
  /orders/{orderGuid}/checks/{checkGuid}/payments/{paymentGuid}:
    patch:
      tags:
      - Payments
      summary: Toast Update a Tip Amount
      description: 'Updates the tip amount in an existing payment for a check in an

        order. Include the new `tipAmount` value in a `Payment` object

        in the message body.


        This endpoint does not allow any other

        `Payment` object value for a `PATCH` request.


        Specify the Toast

        platform GUID of the order, check, and payment in REST path

        parameters.


        For more information, see [the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiUpdatingTipsInAPayment.html).

        '
      operationId: ordersOrderGuidChecksCheckGuidPaymentsPaymentGuidPatch
      parameters:
      - name: orderGuid
        description: 'The Toast platform identifier of the order that you are

          updating a tip in.

          '
        in: path
        required: true
        schema:
          type: string
      - name: checkGuid
        description: 'The Toast platform identifier of the check that you are

          updating a tip in.

          '
        in: path
        required: true
        schema:
          type: string
      - name: paymentGuid
        description: 'The Toast platform identifier of the payment that you are

          updating a tip in.

          '
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'A JSON `Order` object

            that includes the tip amount that you updated.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: The API cannot process the request.
      security:
      - oauth2:
        - orders.payments:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePaymentRequest'
        description: 'A JSON `Payment` object

          containing the `tipAmount` value that will replace any

          existing tip amount for the payment.


          Do not include any

          value other than `tipAmount`.

          '
        required: true
components:
  schemas:
    RefundTransaction:
      allOf:
      - $ref: '#/components/schemas/ToastReference'
      - type: object
        description: 'An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.

          '
    Device:
      type: object
      description: 'The *Device ID* value that the Toast platform assigns to a specific Toast POS device.


        The `id` value is a unique identifier for a device.


        To find the ID for a Toast POS device, from the overflow  menu (⋮) select *Device Status* and then select the *Device* tab.

        '
      properties:
        id:
          type: string
          description: The physical id of the device
    AppliedDiscountTrigger:
      type: object
      description: The Selection that triggered the application of this discount
      properties:
        selection:
          $ref: '#/components/schemas/ExternalReference'
        quantity:
          type: number
          format: double
          description: The amount of the selection used to trigger the applied discount.
    RefundDetails:
      type: object
      description: 'Information about refunded currency amounts for an item

        selection, modifier option, or service charge. The refund

        information includes separate values for the pre-tax value

        being refunded and the tax amount being refunded.

        '
      properties:
        refundAmount:
          description: 'The value of the menu item or service charge (excluding taxes) being

            refunded. Includes the value of any nested modifier options that

            increased the price of the item or modifier option (an upcharge for

            the modifier option).

            '
          type: number
          format: double
        taxRefundAmount:
          description: 'The tax amount being refunded.

            '
          type: number
          format: double
        refundTransaction:
          description: 'An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.

            '
          type: object
          $ref: '#/components/schemas/RefundTransaction'
    Order:
      type: object
      description: "A Toast platform order is composed of one or more checks. Each check has \none or more menu item selections.\n\nThe `externalId` value for an order must be unique. If you submit an order\nwith an `externalId` that already exists for another order, the request\nwill fail. You can use this behavior to implement idempotent order\nsubmission by always providing a consistent `externalId` for each unique\norder attempt.\n"
      allOf:
      - $ref: '#/components/schemas/ExternalReference'
      - type: object
        required:
        - diningOption
        - checks
        properties:
          openedDate:
            description: "The business date of the order.\n\nFor dine-in and as soon as possible (ASAP) orders, `openedDate` should match `createdDate`.\n\nFor scheduled orders, `openedDate` should match `promisedDate`.\n\nIf you do not provide a value for \n`openedDate` value when you `POST` a new order, the\nbusiness date of the order is set to the restaurant\nbusiness day that corresponds to the current date and\ntime.\n\nThe business date of an order is affected by the\nbusiness date cutoff time for a restaurant, which is\navailable from the restaurants API in the `closeoutHour` property.\n"
            type: string
            format: date-time
            example: 2025-02-07T08:00:00.000-0800
          modifiedDate:
            type: string
            format: date-time
            description: The most recent date that the order, or a check or menu item selection in the order, was modified.
            example: 2025-02-07T08:00:00.000-0800
          promisedDate:
            description: 'For scheduled orders, the date and time that the order is scheduled to be fulfilled.


              For dine-in and as soon as possible (ASAP) orders, `promisedDate` is `null`.

              '
            type: string
            format: date-time
            example: 2025-05-01T08:00:00.000-0800
          channelGuid:
            description: 'Reserved for future use.

              '
            type: string
            format: uuid
          diningOption:
            description: The restaurant-configured dining option that applies to this order.
            $ref: '#/components/schemas/ExternalReference'
          checks:
            type: array
            description: 'The checks for this order. Most orders have one check.


              If the check is split, then there are multiple checks.

              '
            minItems: 1
            items:
              $ref: '#/components/schemas/Check'
          table:
            type: object
            description: 'The restaurant table at which this order was placed.

              '
            $ref: '#/components/schemas/ExternalReference'
          serviceArea:
            x-toast-read-only: true
            type: object
            description: The service area. Response only.
            $ref: '#/components/schemas/ExternalReference'
          restaurantService:
            x-toast-read-only: true
            type: object
            description: The applicable meal service. For example, lunch or dinner. Response only.
            $ref: '#/components/schemas/ExternalReference'
          revenueCenter:
            type: object
            description: 'The division or section of a restaurant that the order is

              fulfilled in.


              You use revenue centers to analyze financial reporting information.

              '
            $ref: '#/components/schemas/ExternalReference'
          source:
            x-toast-read-only: true
            type: string
            description: 'Indicates the way that the order was placed.


              Valid values:


              * `In Store`

              * `Online`

              * `Order-and-Pay-at-Table`

              * `API`

              * `Kiosk`

              * `Caller Id`

              * `Google`

              * `Invoice`

              * `Toast Pickup App`

              * `Toast Local`

              * `Toast Pay`

              * `Branded Online Ordering`

              * `Catering`

              * `Catering Online Ordering`

              * `Toast Tables`

              * `eCommerce Online ordering`

              * `Branded Mobile App`

              * `Grubhub` (deprecated)


              Response only.

              '
          duration:
            x-toast-read-only: true
            type: integer
            description: The number of seconds between creation and payment. Response only.
          deliveryInfo:
            description: Delivery information related to orders with a `DELIVERY` dining option.
            $ref: '#/components/schemas/DeliveryInfo'
          requiredPrepTime:
            type: string
            format: ISO-8601
            description: "The amount of time that it will take to prepare the order. This value overrides the \ndefault `deliveryPrepTime` or `takeoutPrepTime` that normally controls auto-firing for scheduled orders.\n\nYou can use `requiredPrepTime` to handle atypical orders that will take more time than usual for a restaurant to prepare.\n\nExpress the required preparation time in ISO-8601 duration format. Must be greater than zero and be an \nincrement of five minutes. For example, the value \"PT15M\" sets the required preparation time for the order to 15 minutes.\n"
          estimatedFulfillmentDate:
            x-toast-read-only: true
            type: string
            format: date-time
            description: 'The date and time that the order is expected to be ready for pickup or to be delivered.


              This value is only set when the order dining option uses the `DELIVERY` or `TAKE_OUT` dining behavior. For other dining options, the value is `null`.


              Response only.

              '
            example: 2025-05-01T08:00:00.000-0800
          numberOfGuests:
            type: integer
            description: 'The number of restaurant guests that are associated with the

              order. For example, for a dine-in order, this might be the

              number of guests at a table.

              '
          voided:
            x-toast-read-only: true
            type: boolean
            description: Set to `true` if this order was voided. Response only.
          voidDate:
            x-toast-read-only: true
            type: string
            format: date-time
            description: The date on which this order was voided. Response only.
            example: 2025-02-07T08:00:00.000-0800
          voidBusinessDate:
            x-toast-read-only: true
            type: integer
            description: The business date (yyyyMMdd) on which this order was voided. Response only.
          paidDate:
            type: string
            format: date-time
            description: The most recent date on which this order received payment. If not specified when `POST`ing, it is set to the current system time.
            example: 2025-02-07T08:00:00.000-0800
          closedDate:
            type: string
            format: date-time
            description: 'The most recent date on which the order payment status changed to `CLOSED`.


              This status is not returned for the order. The order is simply `CLOSED` when all of the checks on the order are `CLOSED`.

              '
            example: 2025-02-07T08:00:00.000-0800
          deletedDate:
            type: string
            format: date-time
            description: 'The date and time when the order was deleted.


              The `deletedDate` value only

              applies when the `deleted` value is `true`.


              If `deleted` is `false`, the value

              of `deletedDate` is the UNIX epoch, `1970-01-01T00:00:00.000+0000`.

              '
            example: 2025-02-07T08:00:00.000-0800
          deleted:
            x-toast-read-only: true
            type: boolean
            description: 'Set to `true` if this order is deleted. Response only.


              For example, if you combine a

              check into another order, the original order for the check is deleted.

              '
          businessDate:
            x-toast-read-only: true
            type: integer
            description: The business date (yyyyMMdd) on which the order was fulfilled. Response only.
          server:
            description: The restaurant employee, or server, who is assigned to the order.
            $ref: '#/components/schemas/ExternalReference'
          pricingFeatures:
            type: array
            description: Pricing features that this order is using.
            items:
              type: string
              description: A specific pricing feature used to price out the order.
              enum:
              - TAXESV2
              - TAXESV3
          approvalStatus:
            x-toast-read-only: true
            type: string
            description: 'The current state of the order in the restaurant order

              fulfillment process. For example, the `approvalStatus`

              can indicate that an order is waiting for a restaurant

              employee to approve it or that the order is in a

              restaurant kitchen being fulfilled. Response only.


              Valid values:


              * `NEEDS_APPROVAL` - The order is created but will

              not be fulfilled by the restaurant until an employee

              approves it.


              * `APPROVED` - The order is being fulfilled by the

              restaurant or it was fulfilled in the past. Orders

              remain in this state indefinitely after they are

              fulfilled.


              * `FUTURE` - The order is expected to be fulfilled by the

              restaurant at a future date and time. Restaurant

              employees will receive information about the order at the

              date and time that it is ready to be fulfilled.


              * `NOT_APPROVED` - Restaurant employees received

              information about the order but did not approve it for

              fulfillment. An order enters this state after a period of

              time passes without a restaurant employee approving it.

              '
            enum:
            - NEEDS_APPROVAL
            - APPROVED
            - FUTURE
            - NOT_APPROVED
          createdDevice:
            description: The Toast POS device that created the order. This value is `null` if the order was not created using a Toast POS device.
            $ref: '#/components/schemas/Device'
          createdDate:
            description: The date and time that the Toast platform received the order.
            type: string
            format: date-time
            example: 2025-02-07T08:00:00.000-0800
          lastModifiedDevice:
            description: 'The Toast POS device that modified the order most recently. This value is `null` if the order was never modified using a Toast POS device.


              If the order is modified but the modification was not made using a Toast POS device, this value does not change.

              '
            type: object
            $ref: '#/components/schemas/Device'
          curbsidePickupInfo:
            description: 'Information that the restaurant can use to identify a guest when they arrive outside the restaurant to pick up their order.

              '
            type: object
            $ref: '#/components/schemas/CurbsidePickupInfo'
          marketplaceFacilitatorTaxInfo:
            description: 'Information about the taxes that a marketplace

              facilitator organization remits on behalf of a Toast

              platform restaurant.


              `POST` only. The orders API does not

              include the `marketplaceFacilitatorTaxInfo` value in

              response data.


              **Note**: you can only include this information if your

              Toast API client is associated with a designated

              marketplace facilitator organization. Most Toast API

              clients do not create marketplace facilitator orders.

              '
            type: object
            $ref: '#/components/schemas/MarketplaceFacilitatorTaxInfo'
          createdInTestMode:
            type: boolean
            description: 'Indicates whether the order was created while the restaurant was

              in test mode.


              For more information, see [this _Toast Central_

              article](https://central.toasttab.com/s/article/Test-Mode-Enable-and-Disable-1492802389999)

              '
          appliedPackagingInfo:
            description: 'Information describing the guest''s packaging preferences for this order, for example utensils, napkins, condiments.


              For more information, see [Packaging preferences](https://doc.toasttab.com/doc/devguide/apiOrdersPackagingPreferences.html)

              '
            type: object
            $ref: '#/components/schemas/AppliedPackagingInfo'
          excessFood:
            x-toast-read-only: true
            type: boolean
            description: "Indicates whether the order was created to track excess food (for example, food waste) rather than a \nstandard guest order. Response only.\n\nFor more information on the differences between guest orders and excess food orders, see \n[Daily order for tracking excess food](https://doc.toasttab.com/doc/devguide/apiDailyOrderForTrackingExcessFood.html).\n"
          displayNumber:
            x-toast-read-only: true
            type: string
            description: Response only. Generally starts at one each day and counts up. Not guaranteed to be unique, can be empty if unset.
    ToastReference:
      type: object
      description: A wrapper object with fields that allow reference to a Toast entity by Toast GUID.
      required:
      - guid
      - entityType
      properties:
        guid:
          description: The GUID maintained by the Toast platform.
          type: string
        entityType:
          x-toast-read-only: true
          description: The type of object this is. Response only.
          type: string
    AppliedLoyaltyInfo:
      type: object
      description: Information about the customer loyalty program account associated with a check.
      required:
      - loyaltyIdentifier
      - vendor
      allOf:
      - $ref: '#/components/schemas/ToastReference'
      - type: object
        properties:
          loyaltyIdentifier:
            type: string
            description: An identifier for the loyalty program account. For `POST` orders, this identifier is transmitted to the loyalty program service provider to associate the check with the loyalty account.
          maskedLoyaltyIdentifier:
            type: string
            description: 'A representation of the identifier of the loyalty program

              account that can be displayed securely. For example:

              `************1234`. The Toast POS displays this string to

              restaurant employees and guests.


              You can optionally include this

              value when you `POST` an order. It is

              available in response data when you `GET` the order.


              If you do not provide a `maskedLoyaltyIdentifier` when you

              `POST` an order, this value is `null` in response data.


              The Toast POS app displays a masked representation of the

              `loyaltyIdentifier`. All characters except the last four

              are hidden.

              '
          vendor:
            type: string
            description: The specific loyalty program service provider that supports the loyalty account.
            enum:
            - TOAST
            - PUNCHH
            - PUNCHH2
            - PAYTRONIX
            - APPFRONT
            - INTEGRATION
          accrualFamilyGuid:
            x-toast-read-only: true
            type: string
            description: 'Response only. An internal Toast platform identifier for loyalty

              program transactions.


              This is not returned from the initial

              `POST` order request and is available at a later time.

              '
          accrualText:
            x-toast-read-only: true
            type: string
            description: 'Response only. A description of the loyalty program transaction

              to print on the customer''s receipt. For example,

              "Earned 27 points."


              The maximum length of the description string

              is 255 characters.


              This is not returned from the initial

              `POST` order request and is available at a later time.

              '
    Refund:
      type: object
      description: A currency amount removed from a guest payment.
      properties:
        refundAmount:
          type: number
          format: double
          description: The amount of the refund, excluding the tip.
        tipRefundAmount:
          type: number
          format: double
          description: The amount of the tip refund.
        refundDate:
          description: The date and time when the refund was made.
          type: string
          format: date-time
        refundBusinessDate:
          x-toast-read-only: true
          description: The business date (yyyyMMdd) on which this refund was created. Response only.
          type: integer
        refundTransaction:
          description: 'An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.

            '
          type: object
          $ref: '#/components/schemas/RefundTransaction'
    AppliedTaxRate:
      type: object
      description: A tax rate that is applied to an item or service charge.
      required:
      - taxRate
      allOf:
      - $ref: '#/components/schemas/ToastReference'
      - type: object
        properties:
          entityType:
            description: The type of object this is.
            type: string
          taxRate:
            type: object
            $ref: '#/components/schemas/ToastReference'
          name:
            type: string
            description: The name of the tax rate.
          rate:
            type: number
            format: double
            description: The tax rate, which can be a fixed amount, a percentage, or null.
          taxAmount:
            type: number
            format: double
            description: The tax amount that was actually applied.
          type:
            type: string
            description: 'The type of the tax rate. Default is `PERCENT`.


              The value `EXTERNAL` indicates that the tax is for a marketplace

              facilitator order, and that the marketplace facilitator

              organization calculated the tax amount.

              '
            enum:
            - PERCENT
            - FIXED
            - NONE
            - TABLE
            - EXTERNAL
          facilitatorCollectAndRemitTax:
            type: boolean
            description: 'Indicates whether the marketplace facilitator that

              received a guest order remitted the tax amount on behalf

              of the Toast platform restaurant.


              You can use this information to identify tax amounts that

              have already been paid by an ordering service provider

              and do not need to be paid again.


              * `true` - The marketplace facilitator paid the tax

              amount on behalf of the Toast platform restaurant

              location.


              * `false` - The marketplace facilitator has not paid the

              tax amount. The Toast platform restaurant location may be

              required to pay the tax amount.


              **Note**: Toast API response data is not guidance or

              advice for tax compliance.

              '
          displayName:
            type: string
            description: The name of the tax rate as it appears on guest receipts.
          jurisdiction:
            type: string
            description: The state or province of the tax rate for reporting purposes.
          jurisdictionType:
            type: string
            description: The jurisdiction type (ex. STATE, COUNTY, etc.) of the tax rate for reporting purposes.
    ConfigReference:
      type: object
      description: 'A wrapper object containing identifier values for Toast platform entities.

        '
      allOf:
      - $ref: '#/components/schemas/ToastReference'
      - type: object
        properties:
          multiLocationId:
            description: 'A consistent identifier for Toast platform entities, such

              as menu items, that applies to all versions of a shared

              entity at all locations in a restaurant group.


              For example, you can use the `multiLocationId` value to

              identify menu entities that are versions of a shared menu

              entity. For more information about the menus API `multilocationId` value, see

              [the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiUnderstandingGuidsEntityIdentifiersAndMultilocationIds_V2.html#apiMultilocationIdValues_V2).

              '
            type: string
          externalId:
            description: 'An external identifier that is prefixed by a naming

              authority. Deprecated for use in `ConfigReference`.

              '
            type: string
    AppliedServiceCharge:
      type: object
      description: 'A service charge that is added to a check. A service charge can represent an upcharge such as a gratuity or a delivery fee.


        Whether the upcharge is taxable is defined in the restaurant-configured `serviceCharge`.


        The fields on the `AppliedServiceCharge` are calculated based on the referenced `ServiceCharge` configuration.

        '
      allOf:
      - $ref: '#/components/schemas/ExternalReference'
      - type: object
        required:
        - serviceCharge
        properties:
          chargeAm

# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/toast/refs/heads/main/openapi/toast-payments-api-openapi.yml