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.

Encrypting credit card information

Important

DISCLAIMER: Compliance with PCI DSS and all other regulations or laws is solely your responsibility. The information provided is for informational purposes only and should not be relied upon or used as a substitute for consultation with a Qualified Security Assessor or other legal advisor. Please consult a professional advisor for a qualified opinion on the applicability of requirements to your business operations.

When you send a PUT request to authorize a payment in the credit cards API, you include identifying credit card information in the message body data. The JSON payment authorization object in the message body data includes an encryptedCardData value that contains a base64 representation of the encrypted credit card information.

To compose the encryptedCardData value, you include credit card information in a JSON object and encrypt it using the encryption algorithm and RSA public key that corresponds to the encryption key identifier (keyId) that you receive from Toast integration support.

For information about supported encryption algorithms, see Encryption algorithms. For information about key identifiers, see Encryption keys and key identifiers.

The following example shows credit card information that you encrypt and base64 encode in order to generate an encryptedCardData value.

Example credit card information for an encryptedCardData value

{
  "cardNumber" : "4111111111111111",1
  "zipCode" : "01234",2
  "cvv" : "321",3
  "expMonth" : "01",4
  "expYear" : "20",5
  "country" : "USA"6
}

1

The primary account number (PAN) of the card, which the API validates using the ISO-standard Luhn algorithm.

2

The ZIP or postal code of the card holder's billing address. This value is required, must be numeric, and must not be an empty string. Do not include hyphens (-) in the string.

3

The three- or four-digit card verification value (CVV) of the card. When cardNumberOrigin is PARTNER_VAULT in the credit card authorization request, the CVV is not required, but it is validated for correctness if it is submitted. If you do not submit a CVV on a credit card authorization request, you can either omit the cvv value on your authorization, or submit a cvv value of null. The cvv value you submit should not be an empty string ("").

4

The two-digit month of the expiration date for the card.

5

The two-digit year of the expiration date for the card.

6

The country of the card holder's billing address, in ISO 3166-1 alpha-3 format.


The following example shows the base64-encoded and encrypted credit card information in the encryptedCardData value.

Base64-encoded and encrypted credit card information in the encryptedCardData value

{
  "encryptedCardData": "yu3BmKwL65F3UVOrsQEZxhrSyN//QkwIhEjgAFVYV
    nl28IyQ+bHIdez1bcU0CSuljngjkQHGTAjQumBpSfqqDd61bKQw/drHJAWR10
    bIZU/q0iLHPf3bvt6h1rA0ViN0byr+zkFDo5tosGGf9VeJz6Dd5OMNunbgViO
    HC1TPDS6bE90oqczsJjVwjS2/n2hO444gb1wPl3GbcwHmsrGDxW4KYn99FOk7
    gLzY4C5QvQG5bNRm4mA/30bMEAeu9hzlQSGS0b/J2EKAjkHV1+b1jA91rwHDV
    +DQ0iRPRQIvAY/UF4qrQwMC0SgmEHLMqaoPtCi4qEvWe0JCQ48LxeUmDg==",
  "keyId": "RSA-OAEP-SHA256::dff3e2eb-3abd-458c-b7fc-7692202d5895_myKeyIdentifier",
  "willSaveCard": false,
  "cardNumberOrigin": "END_USER",
  "amount": 100.00,
  "tipAmount": 25.00,
  "requestMetadata": {
    "localTransactionDate": "2019-03-11T17:32:00.000+0000",
    "originIPAddr": "123.456.78.90",
    "partnerServiceInfo": {
      "instanceId": "myClient"
    }
  }
}