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.
To authorize a credit card payment for a check, you send a
PUT
request to the
/merchants/{merchantUuid}/payments/{paymentUuid}
resource of
the credit cards API.
The credit cards API verifies that the credit card account has sufficient funds available and places a hold on the account for the amount of the payment.
PUT request path parameters
-
merchantUuid
- The Toast GUID for the restaurant that will collect the funds from the credit card payment. -
paymentUuid
- A UUID unique identifier for the credit card payment. You generate the UUID for the payment. You use the identifier when you apply the credit card payment to a check. To generate the payment UUID, you must use the algorithm described in version four of the UUID standard.
The message body parameter for the PUT
request is a JSON PaymentAuthorization
object. The
PaymentAuthorization
object includes the information
described in the following list.
PUT request message body parameter information
-
How your integration received the credit card information for the authorization, and whether your organization will store the information for later use
-
Encrypted and non-encrypted information about the credit card account
-
The payment amount and tip amount for the authorization
The following example shows the JSON message body to
PUT
a credit card payment authorization
request.
Authorization request message body
{ "encryptedCardData": "FBRdBx38xrQ8UUQTAVUI3mLddkqtuxX6huPOsI 1WKVS97ffQITY2yToeJU0e16aRo6ehZZxBO6YU0DKUOXiX8Kww1jXE3Rn5J8Do 8n3wSeLV3Qomn0VvAd+5YT8bUijVs0aRUy3u34DpYwMkon0WMkq8BNGQWk3Whd 3qJEdi/SagofuO0yExxlixklflwAIkbuZZ2tHtp+FV7n+UAfXPeSgXRrX6Rkal ir3OKZtUrC8aiymc7Xs9G4w4+bDBa/kArP1D7e3A42+wIsQicc9rL//B0GyQll Cu2dnrEDSllcU3wZSRLVPjuoXmyK28JO40Grzeq2ZKAKepnTDW9m84ag==","keyId": "RSA-OAEP-SHA256::a253759c-1c91-4f22-9db9-71ba24738f8d_PartnerName"
"amount": 98.76,
"tipAmount": 24.69,
"willSaveCard": true,
"cardNumberOrigin": "PARTNER_VAULT",
"requestMetadata": { "localTransactionDate": "2019-08-24T22:00:00.000+0000",
"originIPAddr": "189.219.91.62",
"partnerServiceInfo": { "instanceId": "my-api-client"
}, "cardFirst6": "411111",
"cardLast4": "1111",
"billingAddress": {
"name": "Clark Kent", "phone": "555-555-5555", "address1": "123 Main Street", "address2": "", "city": "Boston", "region": "MA", "postalCode": 02215, "country": "USA" }, "deliveryAddress": {
"name": "Lois Lane", "phone": "111-555-5555", "address1": "789 Grand Avenue", "address2": "", "city": "New York", "region": "NY", "postalCode": 10001, "country": "USA" }, "guestIdentifier": "21f71785-3e78-4416-ae49-ad359ecd00e8",
"guestEmail": "toastyguest@domain.com",
"userAgent": "Browser/1.0",
"appName": "Our Company's Amazing Android App",
"appVersion": "4.2"
} }
Identifying credit card information, including the account number. You must encrypt this information and encode it in base64 format. For more information, see Encrypting credit card information. |
|
The encryption key identifier that you receive from from Toast integration support. The identifier string indicates the algorithm and the specific encryption key used to encrypt the credit card data for the request. For information about encryption algorithms and key identifiers, see Encryption algorithms and Encryption keys and key identifiers. |
|
The price of the check that you will apply the credit card payment to. For information about getting the total price of a check, see Getting check prices before you submit an order. |
|
The amount of the gratuity that the guest applied to the check. |
|
The |
|
The |
|
The date and time, in ISO 8601 format, that the guest presented the credit card payment. |
|
The IP address of the device that the guest used to enter the credit card payment. For example, for an online order, this is the IP address of the computer that the guest used to submit the order. |
|
An identifier for the server or process that operates as an API client to process the credit card authorization. For example, this might be the identifier of a client software process that appears in log information. |
|
The first six digits of the credit card number. The first six
digits are the bank identification number (BIN) for the card. The
value must match exactly the information provided in the encrypted
card data. This value is required when |
|
The last four digits of the credit card number. The value must
match exactly the information provided in the encrypted card data.
This value is required when |
|
The billing address associated with the credit card. When
|
|
A delivery address for the order. |
|
A stable identifier for the guest making the payment, such as
an email address or a UUID. This value is required when
|
|
The email address of the guest placing the payment. |
|
For payments taken through a web browser, the browser's user agent string. |
|
A company-specific name for the mobile app (if any) the payment is made through. For example, use 'MyCompany Android App' instead of 'Android App'. |
|
The version of the mobile app (if any) that the payment is made through. You can use any string to represent the app version. There are no format or content requirements. |