Authorize a credit card

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.

Securityoauth2
Request
path Parameters
merchantUuid
required
string

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

paymentUuid
required
string

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

header Parameters
Toast-Restaurant-External-ID
required
string

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

Request Body schema: application/json

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

amount
required
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.

cardNumberOrigin
required
string

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.

Enum: "END_USER" "PARTNER_VAULT"
encryptedCardData
required
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.

keyId
required
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.

required
object (PaymentRequestMetadata)

Metadata about the request being made.

tipAmount
required
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.

willSaveCard
required
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.

Responses
200

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

400

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

404

The merchant (restaurant) does not exist.

409

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

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

500

Unexpected error

put/merchants/{merchantUuid}/payments/{paymentUuid}
Request samples
application/json
{
  • "cardNumberOrigin": "END_USER",
  • "willSaveCard": true,
  • "encryptedCardData": { },
  • "amount": 0,
  • "keyId": "string",
  • "tipAmount": 0,
  • "requestMetadata": {
    }
}
Response samples
application/json
{
  • "paymentState": "AUTHORIZED",
  • "authorizationMetadata": {
    },
  • "amount": { },
  • "tipAmount": { },
  • "denialReason": "string",
  • "error": "string"
}