Authorizing a credit card payment

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.

Authorizing a credit card payment

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 willSaveCard value indicates whether organizations store restaurant guests' credit card information for future use. true indicates that your organization stores credit card information used in a credit card authorization. false indicates that your organization does not store the credit card information used in a credit card authorization.

The cardNumberOrigin value is used for "card on file" reporting. If your organization uses stored credit card information for a credit card authorization, you must set the value of cardNumberOrigin to PARTNER_VAULT. The default value for cardNumberOrigin is END_USER. For more information, see Using card number origin values.

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.

Important

The origin IP address is essential for detecting and preventing fraud attempts in credit card authorization requests. To prevent disruption to your transaction workflow, ensure the correct origin IP address is used.

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 cardNumberOrigin is END_USER.

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 cardNumberOrigin is END_USER.

The billing address associated with the credit card. When cardNumberOrigin is END_USER, billingAddress is required and must include at least a postalCode and country.

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 cardNumberOrigin is END_USER. For more information, see Using guestIdentifier values.

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.