Adding payments to an existing check

Important

To use the /orders endpoint to add payments, you need access to the orders.payments:write scope. For more information about API client scopes, and how to get access to them, see Scopes.

You can use the orders API to add authorized credit card payments and alternative payments to a check on an existing order.

How to add the payments to the check

To add payments to an existing check, you send a POST request to the /orders/{orderGuid}/checks/{checkGuid}/payments endpoint of the Toast orders API. To include the information about the payments, you include an array of JSON Payment objects. The type value for the payments must be CREDIT or OTHER. Credit card payments must be authorized before you add them.

For more information, see Post payments in the Toast API reference.

Add payment to an existing check

  1. Find the Toast platform GUIDs of the order and the check that you are adding payment to. For more information on locating these GUIDs, see Finding an order or check GUID.

  2. Authorize the credit card payments that you are adding. For more information, see Credit card payments.

    When you add payments to the check, you include the UUIDs of the authorized credit card payments.

  3. Create an array of JSON Payment objects that contain information about the payments you are adding. For each payment, you use the UUID as the value of guid.

    For information about the Payment object, see the orders API reference documentation.

  4. Send a POST request to the /orders/{orderGuid}/checks/{checkGuid}/payments endpoint of the orders API.

    In the request path parameters, include the Toast platform GUID of the order and the check.

    In the request body, include the array of Payment objects that contains information about the payments to add.

    For more information about the orders API payments endpoint, see the reference documentation.

  5. Examine the response data that you receive from the orders API. Verify that your request is processed successfully. For an example, see Example response data when adding a payment to an existing check.

Add an alternative payment type to an existing check

  1. Find the Toast platform GUIDs of the order and the check that you are adding payment to. For more information on locating these GUIDs, see Finding an order or check GUID.

  2. Find the GUID of the alternative payment type you want to apply. To get the list of alternative payment types available for the location, send a GET request to the /alternatePaymentTypes endpoint of the configuration API. For more information about alternative payment types, see the reference documentation.

  3. For each alternative payment, set type to OTHER and include the alternate payment type GUID as the value of otherPayment.guid.

    For information about the Payment object, see the orders API reference documentation.

  4. Send a POST request to the /orders/{orderGuid}/checks/{checkGuid}/payments endpoint of the orders API.

    In the request path parameters, include the Toast platform GUID of the order and the check.

    In the request body, include the array of Payment objects that contains information about the payments to add.

    For more information about the orders API payments endpoint, see the reference documentation.

  5. Examine the response data that you receive from the orders API. Verify that your request is processed successfully. For an example, see Example response data when adding a payment to an existing check.

Example array of Payment objects to add payments to an existing check

The following example shows an array of Payment objects to add payments to a check contained in an existing order. 

[
  {
    "guid": "7c65cc16-15bd-496e-886b-a3c080b36100",1
    "type": "CREDIT",2
    "amount": 35.21,3
    "tipAmount": 154
  },
  {5
    "type": "OTHER",
    "amount": 48.74,
    "tipAmount": 20,
    "otherPayment": {
        "guid": "28645ad1-b795-44f6-ad9f-baeeb07fa03d"6
  }
]

1

The UUID of the credit card payment that you authorized in the Toast credit cards API. For more information, see Credit card payments.

2

The /orders/{orderGuid}/checks/{checkGuid}/payments endpoint supports adding credit card and alternative payment types. The type field must be CREDIT for credit card payments or OTHER for alternative payment types.

3

The currency amount to apply to the check price in the added payment.

4

The currency amount of a tip or gratuity in the added payment.

5

You can add one or more payments in the array. This example adds two payments to the check.

6

The GUID of the alternate payment type configured for this location.

Example response data when adding a payment to an existing check

The following example shows example response data for a POST request to the /orders/{orderGuid}/checks/{checkGuid}/payments endpoint of the orders API. 

{
  "guid": "99e42b9c-2f45-4b01-ab90-de4169f6dd29",1
  "entityType": "Order",

  [contents omitted]

  "checks": [
    {
      "guid": "b7dba08f-db0c-4db3-8ce8-ef25aa0cc492",2
      "entityType": "Check",

      [contents omitted]

      "payments": [3
        {
          "guid": "b7372d29-09fd-46bc-b95e-3c1ab4e77fae",4
          "entityType": "OrderPayment",
          "externalId": null,
          "originalProcessingFee": null,
          "amount": 50.12,
          "tipAmount": 20.34,
          "amountTendered": null,
          "cashDrawer": null,
          "cardType": "VISA",
          "lastModifiedDevice": {
            "id": null
          },
          "refundStatus": "NONE",
          "houseAccount": null,
          "type": "CREDIT",
          "voidInfo": null,
          "otherPayment": null,
          "mcaRepaymentAmount": null,
          "createdDevice": {
            "id": null
          },
          "paidDate": "2019-03-31T14:43:04.036+0000",
          "cardEntryMode": null,
          "paymentStatus": "AUTHORIZED",
          "paidBusinessDate": 20190331,
          "last4Digits": "1111",
          "refund": null
        }
      ],

      [contents omitted]

    }
  ],

  [contents omitted]

}

1

The Toast platform GUID of the order that you added payments to.

2

The Toast platform GUID of the check that you added payments to.

3

The payments value in a check includes an array of Payment objects for the payments that are applied to the check. These payments include the payments that you added.

4

The Toast platform GUID of a payment that you added.