Post payments

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.

Request
path Parameters
orderGuid
required
string

The Toast platform identifier of the order that you are adding payments to.

checkGuid
required
string

The Toast platform identifier of the check that you are adding payments to.

Request Body schema: application/json

An array of JSON Payment objects containing information about the payments you are adding.

Array
guid
required
string

The GUID maintained by Toast. Response only.

entityType
required
string

The type of object this is. Response only.

externalId
string

External identifier string that is prefixed by the naming authority. You can use the orders API to set an externalId for an order and then GET the order with that externalId.

paidDate
string <date-time>

The date at which the payment was made.

paidBusinessDate
integer

The business date (yyyyMMdd) on which this payment was first applied. Response only.

type
required
string

The payment method. When POSTing, only OTHER and CREDIT are supported. All other types are response only. For cash payments, please create an external cash payment type in Other Payment Options.

Enum: "CASH" "CREDIT" "GIFTCARD" "HOUSE_ACCOUNT" "REWARDCARD" "LEVELUP" "OTHER" "UNDETERMINED"
cardEntryMode
string

Indicates how credit card data was obtained. Response only.

Enum: "SWIPED" "KEYED" "ONLINE" "EMV_CHIP_SIGN" "TOKENIZED" "PRE_AUTHED" "SAVED_CARD" "FUTURE_ORDER" "CONTACTLESS" "APPLE_PAY_CNP" "GOOGLE_PAY_CNP" "INCREMENTAL_PRE_AUTHED" "PARTNER_ECOM_COF"
amount
required
number <double>

The amount of this payment, excluding tips.

tipAmount
required
number <double>

The amount tipped on this payment.

amountTendered
number <double>

The amount tendered for this payment.

cardType
string

The type of card used. Response only.

Enum: "VISA" "MASTERCARD" "AMEX" "DISCOVER" "JCB" "DINERS" "CIT" "MAESTRO" "LASER" "SOLO" "UNKNOWN"
last4Digits
string

The last 4 digits of the card used. Response only.

originalProcessingFee
number <double>

The original processing fee for this payment. The original processing fee value is populated after the payment has been captured. Response only.

object (schemas)

A wrapper object with fields that allow reference to a Toast entity by Toast GUID or a partner's identifier.

referenceCode
string

For internal use only.

object (schemas)

A wrapper object with fields that allow reference to a Toast entity by Toast GUID or a partner's identifier.

refundStatus
string

Response only.

Enum: "NONE" "PARTIAL" "FULL"
object (Refund)

A currency amount removed from a guest payment.

paymentStatus
string

The status of this payment when the type is CREDIT. Response only.

Enum: "OPEN" "PROCESSING" "AUTHORIZED_AT_RISK" "AUTHORIZED" "ERROR" "ERROR_NETWORK" "DENIED" "PROCESSING_VOID" "VOIDED_AT_RISK" "CANCELLED" "CAPTURE_IN_PROGRESS" "CAPTURED" "VOIDED"
object (VoidInformation)

Information about a void applied to a check or item.

object (schemas)

A wrapper object with fields that allow reference to a Toast entity by Toast GUID or a partner's identifier.

object (schemas)

A wrapper object with fields that allow reference to a Toast entity by Toast GUID or a partner's identifier.

object (Device)

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, do the following. From the overflow menu (⋮) select Device Status and then select the Device tab.

object (Device)

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, do the following. From the overflow menu (⋮) select Device Status and then select the Device tab.

mcaRepaymentAmount
number <double>

The total currency amount withheld as repayment for a Toast Capital merchant cash advance (MCA). The MCA repayment amount is set at the time the payment is captured, which is typically hours after the actual restaurant guest payment. Until the mcaRepaymentAmount is set, this value is null. The mcaRepaymentAmount might be updated when the payment is settled, which is typically one or more days after the actual guest payment. Response only.

cardPaymentId
string

Note: this value is in limited release. Your orders API integration might not include the cardPaymentId value.

A unique identifier for the credit card used for a CREDIT type payment. The identifier string is generated by the Toast platform and does not include any information related to or associated with the actual credit card account. The identifier is unique within your restaurant management group. The value is null for the following payment types:

  • Payment types other than CREDIT
  • Credit card payments entered using EMV (chip cards)
  • Credit card payments entered by keying in card numbers

Response only.

object (schemas)

A wrapper object with fields that allow reference to a Toast entity by Toast GUID or a partner's identifier.

object (schemas)

Reserved for future use.

orderGuid
string

The Toast platform identifier for the order that contains the payment. Response only.

checkGuid
string

The Toast platform identifier for the check that contains the payment. Response only.

receiptToken
string

For internal use only.

cardHolderFirstName
string

For internal use only.

cardHolderLastName
string

For internal use only.

Responses
200

A JSON Order object that includes the payments that you added.

post/orders/{orderGuid}/checks/{checkGuid}/payments
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
{
  • "guid": "string",
  • "entityType": "string",
  • "externalId": "string",
  • "openedDate": "2019-08-24T14:15:22Z",
  • "modifiedDate": "2019-08-24T14:15:22Z",
  • "promisedDate": "2019-08-24T14:15:22Z",
  • "diningOption": {
    },
  • "checks": [
    ],
  • "table": {
    },
  • "serviceArea": {
    },
  • "restaurantService": {
    },
  • "revenueCenter": {
    },
  • "source": "string",
  • "duration": 0,
  • "deliveryInfo": {
    },
  • "requiredPrepTime": "string",
  • "estimatedFulfillmentDate": "2019-08-24T14:15:22Z",
  • "numberOfGuests": 0,
  • "voided": true,
  • "voidDate": "2019-08-24T14:15:22Z",
  • "voidBusinessDate": 0,
  • "paidDate": "2019-08-24T14:15:22Z",
  • "closedDate": "2019-08-24T14:15:22Z",
  • "deletedDate": "2019-08-24T14:15:22Z",
  • "deleted": true,
  • "businessDate": 0,
  • "server": {
    },
  • "pricingFeatures": [
    ],
  • "approvalStatus": "NEEDS_APPROVAL",
  • "guestOrderStatus": "string",
  • "createdDevice": {
    },
  • "createdDate": "2019-08-24T14:15:22Z",
  • "initialDate": 0,
  • "lastModifiedDevice": {
    },
  • "curbsidePickupInfo": {
    },
  • "deliveryServiceInfo": {
    },
  • "marketplaceFacilitatorTaxInfo": {
    }
}