This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

This section provides reference information about the endpoints and data types of the Toast credit cards API. For more information about using the credit cards API and code examples, see Credit card payments. For general information about working with Toast APIs, see API overview.

Credit Cards API

Base URL: /ccpartner/v1, Version: 1.0.0

A simple, single request, synchronous API to authorize credit card transactions associated with an orders API order.

Default response content-types: application/json
Schemes: https

Summary

Path Operation Description
/merchants/{merchantUuid}/payments/{paymentUuid} PUT

Authorize a credit card

Paths

Authorize a credit card

PUT /merchants/{merchantUuid}/payments/{paymentUuid}

Authorize a credit card payment. Funds will be held until the payment is voided or captured.

You must submit an orders API request to apply the payment to a check within five minutes of authorization, otherwise the payment will be automatically voided.

Payment must be captured within four days of authorization, otherwise the payment will be automatically voided. Capture occurs the evening after the order is fulfilled by the restaurant.

The authorization request, including encrypted credit card information and payment details.

merchantUuid

The Toast GUID of the merchant (restaurant) that will receive the payment. This is the same value as the Toast-Restaurant-External-ID.

path string
paymentUuid

The unique identifier (UID) of this authorization, generated by the restaurant organization or integration partner.

path string
Toast-Restaurant-External-ID

The GUID of the restaurant used as the context of the request.

header string

Uses default content-types: application/json

200 OK

The authorization request was processed. See the response for details.

400 Bad Request

The request was not valid. A required field may be missing.

404 Not Found

The merchant (restaurant) does not exist.

409 Conflict

An authorization request was already made for this payment UUID. Verify that you are generating unique payment UUIDs for each request. This can also occur if the same request is resubmitted, but the state has since been changed by another system (for example, voided on the POS).

422 Unprocessable Entity

The request failed validation. The structure is not correct. A message with more information is returned if using the certification environment.

500 Internal Server Error

Unexpected error

Schema definitions

AuthorizationMetadata: object

Additional details about a payment, typically displayed on a receipt and logged by the partner.

localTransactionDate: string (date-time)

A copy of the localTransactionDate provided by the partner, in ISO 8601 format.

cardBrand: string

The brand of the credit card. For example, AMEX, Discover, Visa, or Mastercard.

authorizationCode: string

A code generated by card processing networks upon accepting an authorization request.

last4: string

The final four digits of the credit card number.

BillingAddress: object

An international billing address including name and phone number. A BillingAddress object for a PaymentRequestMetadata billingAddress value must exactly match address information you provide in encrypted credit card data.

name: string

The name attached to the billing address. This is not necessarily the same as the name on the card.

phone: string

The phone number associated with the account in E.164 format.

address1: string

Line 1 of the address

address2: string

Line 2 of the address

city: string

City of the address

region: string

Region or state of the address

postalCode: string

Postal or ZIP code. If using a code with an extra four digits, for example a US ZIP+4 code, do not separate the extra digits. For example, 123451234.

country: string

Country code using the ISO 3166-1 alpha-3 standard

DeliveryAddress: object

A generic international delivery address including name and phone number.

name: string

The name associated with the address.

phone: string

The phone number associated with the account in E.164 format.

address1: string

Line 1 of the address

address2: string

Line 2 of the address

city: string

City of the address

region: string

Region or state of the address

postalCode: string

Postal or ZIP code. If using a code with an extra four digits, for example a US ZIP+4 code, do not separate the extra digits. For example, 123451234.

country: string

Country code using the ISO 3166-1 alpha-3 standard

PartnerServiceInfo: object

Information about the client that made the payment request. This information can be used for troubleshooting problems.

instanceId: string

An identifier for the client that made the authorization request. For example, this might be a partner service instance ID that is visible in log messages.

additionalInfo: string

Additional information about the service. For example, this might be a JSON structure containing the IP address and service version.

PaymentAuthorization: object

A request to authorize a credit card payment.

cardNumberOrigin: string , x ∈ { END_USER , PARTNER_VAULT }

The way that the credit card was provided for the payment request. The value is END_USER if the cardholder entered the card number (PAN) as part of a web order. The value is PARTNER_VAULT if the PAN was retrieved from a vault controlled by the integration partner.

This value is used with willSaveCard to report information about stored credit card numbers to credit card provider networks. If your organization is using stored credit card information for a credit card authorization, this value must be PARTNER_VAULT. The default value is END_USER.

willSaveCard: boolean

Indicates whether your organization will save the restaurant guests' credit card information for future use.

Toast reports information about stored credit card information to some credit card providers. This "card on file" or "stored credentials" reporting is required by some credit card provider networks. These networks may impose fees for non-compliance with "card on file" reporting requirements.

Note that integration partners are responsible for any and all fees incurred, and must comply with all applicable law and rules relevant to, "card on file" consent, storage, use and reporting requirements in accordance with card brand regulations and the integration partner agreement.

encryptedCardData: object

A base64-encoded version of the encrypted card data payload. For information about encrypting and encoding credit card information, see the Toast API Developer's Guide.

amount: number (double)

The check price that should be charged to the credit card, not including the tip. For example, the value 10.00 represents ten USD and zero cents. The amount must not be negative. The total of the amount value and the tipAmount value must be greater than zero.

keyId: string

The identifier of the encryption key and algorithm used to encrypt the credit card data. Toast integration support provides this identifier along with the encryption key itself. If you received an encryption key before June 2018, you may omit this field. For all API users, supplying a keyId value prevents downtime during key rotations.

tipAmount: number (double)

The tip that should be charged to the credit card. For example, the value 1.00 represents one USD and zero cents. The tip amount must not be negative. The total of the amount value and the tipAmount value must be greater than zero.

requestMetadata: PaymentRequestMetadata

PaymentRequestMetadata: object

Metadata about the request being made.

partnerServiceInfo: PartnerServiceInfo
localTransactionDate: string (date-time)

The date and time, in ISO 8601 format, when the consumer made the payment request.

originIPAddr: string

The public ipv4 or ipv6 address of the cardholder making the payment.

cardFirst6: string

The first six digits of the credit card number. The first six digits are the bank identification number (BIN) for the card. Must exactly match that provided in the encrypted card data.

cardLast4: string

The last four digits of the credit card number. Must exactly match that provided in the encrypted card data.

billingAddress: BillingAddress
deliveryAddress: DeliveryAddress
userAgent: string

For payments taken through a browser, the browser's user agent string.

guestIdentifier: string

A stable identifier for the guest making the payment. This may be, for instance, an email address or a UUID. Must consist of the following characters: a-z, A-Z, 0-9, =, ., -, _, +, @, :, &, ^, %, !, $

guestEmail: string

The email address of the guest placing the payment.

appName: string

A company-specific name for the mobile app (if any) the payment is made through. For instance, use 'MyCompany Android App' instead of 'Android App'

appVersion: string

The version of the mobile app (if any) the payment is made through. You can use any string to represent the app version. There are no format or content requirements.

PaymentStatus: object

Status of a payment.

paymentState: string , x ∈ { AUTHORIZED , ACKNOWLEDGED , DENIED }

The state of the payment. Toast may add values to this field. Make sure that your implementation can handle additional values.

authorizationMetadata: AuthorizationMetadata
amount: object

The amount of this payment, not including tip.

tipAmount: object

The tip amount of this payment.

denialReason: string

The reason a payment was denied. This must be displayed to the consumer.

error: string

If the payment is in an error state, this will contain the error.

ToastError: object

Contains error details.

description: string

A human-readable description of the problem.

detail: string

Error details, such as an exception and stack trace.