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.

Securityoauth2
Request
path Parameters
checkGuid
required
string

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

orderGuid
required
string

The Toast platform identifier of the order 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
amount
required
number <double>

The amount of this payment, excluding tips.

amountTendered
number <double>

The amount tendered for this payment. The amount tendered does not include the tip.

cardEntryMode
string

Indicates how credit card data was obtained. Response only.

Valid values:

  • SWIPED - The credit card was swiped through a card reader.
  • KEYED - The restaurant employee typed the card number into a device.
  • ONLINE - The credit card information was entered online.
  • EMV_CHIP_SIGN - The credit card was inserted into a chip reader.
  • TOKENIZED - The credit card number is tokenized, meaning that it is replaced by a series of randomly generated numbers. The authorizer is able to use the token to authorize the actual credit card.
  • PRE_AUTHED - The credit card was pre-authorized for an initial amount. An example of pre-authorization is swiping a credit card to start a bar tab. The final payment is authorized when the order is complete.
  • SAVED_CARD - The credit card information was retrieved from the guest's account.
  • FUTURE_ORDER - The credit card payment was included on a scheduled order.
  • CONTACTLESS - The guest used a contactless payment option to provide the credit card number.
  • APPLE_PAY_CNP - The guest used the Apple Pay app to make the payment.
  • GOOGLE_PAY_CNP - The guest used the Google Pay app to make the payment.
  • INCREMENTAL_PRE_AUTHED - An additional payment was added to a pre-authorized card. For example, a guest uses a credit card to open a bar tab. As they continue to order more drinks, the pre-authorized amount is updated. The final payment is authorized when the order is complete.
  • PARTNER_ECOM_COF - The restaurant has the credit card on file.
  • CLICK_TO_PAY_CNP - The guest used Click to Pay to make the payment.
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" "CLICK_TO_PAY_CNP"
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.

cardType
string

The type of credit card that was used. Response only.

Enum: "VISA" "MASTERCARD" "AMEX" "DISCOVER" "JCB" "DINERS" "CIT" "MAESTRO" "LASER" "SOLO" "INTERAC" "UNKNOWN"
object (ExternalReference)

A wrapper object with fields that allow reference to a Toast entity by Toast GUID.

checkGuid
string

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

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

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.

guid
required
string

The GUID maintained by the Toast platform.

object (ExternalReference)

A wrapper object with fields that allow reference to a Toast entity by Toast GUID.

last4Digits
string

The last 4 digits of the credit card that was used. Response only.

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

mcaRepaymentAmount
number <double>

The total currency amount withheld as payments or repayments that apply to your business. For example, the mcaRepaymentAmount might include:

  • Toast Capital payments
  • Marketplace facilitator tax
  • Toast Delivery Services costs
  • Instant deposits

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.

You can use the following resources to find more specific information about the payment and repayment amounts that are included in mcaRepaymentAmount.

Important: Some of the resources listed here require access to Toast products as a restaurant employee or operator. If your organization provides an integration service you might not have access to the Toast products used by the restaurants you integrate with. Toast support cannot provide access to Toast product information. That information is only available to direct Toast product users.

orderGuid
string

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

originalProcessingFee
number <double>

The original processing fee for this payment. Populated after the payment is captured. Response only.

object (ExternalReference)

A wrapper object with fields that allow reference to a Toast entity by Toast GUID.

paidBusinessDate
integer

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

paidDate
string <date-time>

The date on which the payment was made.

paymentStatus
string

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

Valid values:

  • OPEN - The payment has not been presented for processing.
  • PROCESSING - The payment is being processed.
  • AUTHORIZED_AT_RISK - This value is no longer used.
  • AUTHORIZED - The payment is approved but not yet captured. The card is valid and the funds are available.
  • ERROR - An error occurred during the payment processing.
  • ERROR_NETWORK - Unable to connect to the payment authorizer.
  • DENIED - The payment request was denied. For example, the provided credit card is over its limit.
  • PROCESSING_VOID - A void request for the payment is being processed.
  • VOIDED_AT_RISK - This value is no longer used.
  • CANCELLED - The payment is canceled.
  • CAPTURE_IN_PROGRESS - The payment is in the process of being captured.
  • CAPTURED - The payment is captured. When the payment is captured, the funds are transferred to the restaurant.
  • VOIDED - The payment is voided.
Enum: "OPEN" "PROCESSING" "AUTHORIZED_AT_RISK" "AUTHORIZED" "ERROR" "ERROR_NETWORK" "DENIED" "PROCESSING_VOID" "VOIDED_AT_RISK" "CANCELLED" "CAPTURE_IN_PROGRESS" "CAPTURED" "VOIDED"
object (Refund)

A currency amount removed from a guest payment.

refundStatus
string

Indicates whether the payment was refunded. Response only.

Valid values:

  • NONE - The payment was not refunded.
  • PARTIAL - The payment was partially refunded.
  • FULL - The payment was refunded in full.
Enum: "NONE" "PARTIAL" "FULL"
object (ExternalReference)

A wrapper object with fields that allow reference to a Toast entity by Toast GUID.

tenderTransactionGuid
string

For internal use only.

tipAmount
required
number <double>

The amount tipped on this payment.

type
required
string

The payment method.

When POSTing, only OTHER and CREDIT payment types are supported. For cash payments, you create an external cash payment type in Other Payment Options.

All other types are response only.

Valid values:

  • CASH - The guest paid in cash.
  • CREDIT - The guest used a credit card.
  • GIFTCARD - The guest used a gift card.
  • HOUSE_ACCOUNT - The guest used funds from their house account.
  • REWARDCARD - The guest used the available balance on a rewards card.
  • LEVELUP - The guest used the LevelUp app.
  • TOAST_SV - The guest used their Toast Cash stored value.
  • OTHER - The payment type is a custom type configured by the restaurant.
  • UNDETERMINED - The payment type cannot be determined.
Enum: "CASH" "CREDIT" "GIFTCARD" "HOUSE_ACCOUNT" "REWARDCARD" "LEVELUP" "TOAST_SV" "OTHER" "UNDETERMINED"
object (VoidInformation)

Information about a void applied to a check or item.

Responses
200

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

400

The API cannot process the request.

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",
  • "channelGuid": "3c66b5cf-1850-49e6-aef3-40576e6de979",
  • "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": {
    },
  • "createdInTestMode": true,
  • "appliedPackagingInfo": {
    },
  • "excessFood": true,
  • "displayNumber": "string"
}