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.

Encryption algorithms

When you request credit card authorization for a payment, you encrypt credit card information. The public key that you receive from Toast integration support uses one of the following encryption algorithms to encrypt credit card information in an authentication request:

  • RSA-OAEP with SHA256 hashing (RSAES-OAEP)

    This algorithm is supported by modern web browsers by default. The Toast technical partnership team issues encryption keys that use this algorithm.

  • RSA-OAEP with SHA1 hashing (RSAES-OAEP)

    Important

    The RSA-OAEP with SHA1 hashing padding encryption algorithm is deprecated.

Identifying the encryption algorithm in an authorization request

The encryption key identifier string that you receive from Toast integration support identifies the algorithm that you use to encrypt credit card information.

Note

You must use the encryption algorithm that corresponds to the encryption key that you receive from Toast integration support. Do not alter any part of the encryption key identifier string. Do not use the contents of the identifier string to control any part of your integration software.

The encryption key identifier string includes:

  • The identification string for the algorithm

  • Two colon characters

  • The identifier of the public encryption key that you received from the Toast technical partnership team

For more information about key identifiers, see Encryption keys and key identifiers.

The following example shows the identification string for an encryption algorithm and the identifier of a public encryption key in a keyId value. 

RSA-OAEP-SHA256::a253759c-1c91-4f22-9db9-71ba24738f8d_MyRestaurantService

The following table includes the identification strings for the encryption algorithms that you can use in credit cards API authorization requests.

Identification strings for encryption algorithms

Algorithm

Identification string

RSA-OAEP with SHA256 hashing

 RSA-OAEP-SHA256

RSA-OAEP with SHA1 hashing, deprecated

RSA-OAEP-SHA1

For more information about making an authorization request, see Authorizing a credit card payment.

Important

The RSA-OAEP with SHA1 hashing encryption algorithm is deprecated.

Example encryption using RSA OAEP with SHA256 hashing

The following example UNIX command-line command uses the openssl version 1.1.1 utility to encrypt and base64 encode a file that contains JSON credit card information. This example command is intended for integration development and testing. It is not suitable for production use.

Example openssl commands to encrypt and base64 encode an encryptedCardData value

openssl pkeyutl \1
-in my-credit-card-information.json \2
-encrypt -pubin -inkey my-public-key.pem \3
-pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_mgf1_md:sha256 -pkeyopt rsa_oaep_md:sha256 \4
| openssl base64 \5
| tr -d "\n"6

1

The pkeyutl command for the openssl utility can encrypt values. For more information, see the openssl utility documentation.

2

The -in argument provides the path to a file holding the JSON credit card information. See Example credit card information for an encryptedCardData value.

3

The -inkey argument provides the path to a file holding the RSA public key that corresponds with your Toast API client identifier.

4

These arguments set openssl utility options to use the RSA-OAEP with SHA256 hashing encryption algorithm.

5

The base64 command for the openssl utility encodes binary data in base64 format.

6

This tr command strips new line characters out of the base64-encoded credit card information. Removing new line characters makes it easier to include the base64-encoded string in the JSON encryptedCardData value for a credit cards API authorization request.