Encrypting request fields

Spreedly supports encrypting the payload of individual request fields on select API calls. This is currently available when adding a credit/debit card or a bank account to your Spreedly vault using the create credit card or create bank account API calls.

To use field-level encryption, you must have already created or generated an RSA certificate in your authenticated Spreedly environment using the certificates endpoint. (Note that the certificate must be an RSA certificate. ECC certificates are not supported for this feature.)

Once your Spreedly environment has an RSA certificate, you will use the public key associated with that certificate to encrypt your values. The resulting encrypted values must then be base64-encoded prior to being included in your request.

If you are encrypting any rich object fields, like metadata, you should encrypt the entire JSON object as if it were one value, versus encrypting each element of the object individually.

Note: Sensitive values, such as bank_account_number or a credit card’s number, will always be obscured from any Spreedly response and scrubbed from the transaction’s transcript. However, if you encrypt any field that is not considered sensitive by default, for example email or metadata, then the decrypted value will show up in plaintext in the Spreedly response, and will also be viewable in the transcript of the transaction. Encrypting your request fields is only intended to provide an extra layer of security while data is in transit to Spreedly, and does not by itself signify that a value should be treated as sensitive.

POST /v1/payment_methods.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>

{
  "payment_method": {
    "credit_card": {
      "first_name": "Joe",
      "last_name": "Jones",
      "number": "PKlniC9+6uFMp8D7CN7DqYEtLSPGFvcnTB7jgaZx2NkxakyTzee0S1zJPuaxHoHGgD4nVWKyFJmzO5CEhQoPNFHgQJ6YnDQLLfHnnN+GXKPs38qiyoXJQdUYldGm+WoKKp3Shui6KL2T6SoUOy3GRbMMQEy8DCK3P78YS55jOguonInHA2+bmKGZE/45sWY00rIMdUc8MY4rwkEp4cs5eXPwxAhoaQU1LEfhGjrYqS64JoXEuA1sK1Hm22bbO15AGt/NtQ/LlwAhyfrz6t8Qa9qvYOSOfcGDvGPq73mw/13mEA+Ht5gnXD41aYUBgxWF4YUE/ovzH+HNvyXOta0jfg==",
      "verification_value": "iGKnnyYYLXNWmZgTERFLR5mSno4u1pum12jACuo2KC55bmB9yk4+C+WuUP6TVpJOimjgFMsTh2XOguXG3Ec7RRoWeIsQgQQTviAmydGmeDwNu08KNGQRs9CIqktvzenUOoOzSDb6nSMF7PeznTs2CDt7ElM6ntZHFO8NRfijSAI9kFWiPYb6ZPfTYfUZIVkrDHTwORgjQNa9LtcUxgTgprKY3zanmNUpJ5be9IiQngOes/1yNdcCK0TG0fzju1AznoPN4LDPi4HX8Z4H/7i9kedvENZWU4CQXbCvWU4IBjClToCSbGME2wnwPx9+eqoEpoyHLJFPxqWrRIaYpEPH4w==",
      "month": "3",
      "year": "2029",
      "address1": "33 Lane Road",
      "city": "Wanaque",
      "state": "NJ",
      "zip": "31331",
      "country": "US"
    },
    "email": "joey@example.com",
    "metadata": "csWWNHl9cYgNO6WhNvuch+2jXoe0O7nrZN/Zbf4cKvhvkNUTp+Hl6MkvPiXpXImRUw5sMV6niCMra85bsURByllUWSpd+BfltOrOpk4Lt9am6yrMyMotQ8bkIbGmfTvKepL2S4bWjV9Ky4gDq4FKdKQCsX1DrHlIADbgBUiJvdRNC1Z8wBNWcImUCju359INp1qzzOt8ZjAYqL9xIqzGS2DNM7f+JxuDyMEN8uAdhEL4Dvvs2kSMHX8ho7xtYCP3kYkSopF7vaxOucEqgPRfbXAdsSL9Qkp3ohS4biCdIqbwfuQCJY9la0psHalYebQ6NWN2e60W6N1IrtShRHWXHg==",
    "encryption_certificate_token": "Rkx3hmgN4QRuq8ZUunHdGpSniCg",
    "encrypted_fields": "number, verification_value, metadata"
  }
}
HTTPS/1.1 200 OK
{
  "transaction": {
    "token": "JcfBsU7qUy9y7DcRGJ7gq9btgX2",
    "created_at": "2022-02-16T18:46:11Z",
    "updated_at": "2022-02-16T18:46:11Z",
    "succeeded": true,
    "transaction_type": "AddPaymentMethod",
    "retained": false,
    "state": "succeeded",
    "encrypted_fields": "number, verification_value, metadata",
    "encryption_certificate_token": "Rkx3hmgN4QRuq8ZUunHdGpSniCg",
    "message_key": "messages.transaction_succeeded",
    "message": "Succeeded!",
    "payment_method": {
      "token": "a26wp2B1waCkLQ334eU4g0GY1sV",
      "created_at": "2022-02-16T18:46:11Z",
      "updated_at": "2022-02-16T18:46:11Z",
      "email": "joey@example.com",
      "data": null,
      "storage_state": "cached",
      "test": true,
      "metadata": {
        "key_1": "string value",
        "key_2": 123
      },
      "callback_url": null,
      "last_four_digits": "1111",
      "first_six_digits": "411111",
      "card_type": "visa",
      "first_name": "Joe",
      "last_name": "Jones",
      "month": 3,
      "year": 2029,
      "address1": "33 Lane Road",
      "address2": null,
      "city": "Wanaque",
      "state": "NJ",
      "zip": "31331",
      "country": "US",
      "phone_number": null,
      "company": null,
      "full_name": "Joe Jones",
      "eligible_for_card_updater": true,
      "shipping_address1": null,
      "shipping_address2": null,
      "shipping_city": null,
      "shipping_state": null,
      "shipping_zip": null,
      "shipping_country": null,
      "shipping_phone_number": null,
      "payment_method_type": "credit_card",
      "errors": [

      ],
      "fingerprint": "e3cef43464fc832f6e04f187df25af497994",
      "verification_value": "XXX",
      "number": "XXXX-XXXX-XXXX-1111"
    }
  }
}

POST /v1/payment_methods.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>

<payment_method>
  <credit_card>
    <first_name>Joey</first_name>
    <last_name>Jones</last_name>
    <number>PKlniC9+6uFMp8D7CN7DqYEtLSPGFvcnTB7jgaZx2NkxakyTzee0S1zJPuaxHoHGgD4nVWKyFJmzO5CEhQoPNFHgQJ6YnDQLLfHnnN+GXKPs38qiyoXJQdUYldGm+WoKKp3Shui6KL2T6SoUOy3GRbMMQEy8DCK3P78YS55jOguonInHA2+bmKGZE/45sWY00rIMdUc8MY4rwkEp4cs5eXPwxAhoaQU1LEfhGjrYqS64JoXEuA1sK1Hm22bbO15AGt/NtQ/LlwAhyfrz6t8Qa9qvYOSOfcGDvGPq73mw/13mEA+Ht5gnXD41aYUBgxWF4YUE/ovzH+HNvyXOta0jfg==</number>
    <verification_value>iGKnnyYYLXNWmZgTERFLR5mSno4u1pum12jACuo2KC55bmB9yk4+C+WuUP6TVpJOimjgFMsTh2XOguXG3Ec7RRoWeIsQgQQTviAmydGmeDwNu08KNGQRs9CIqktvzenUOoOzSDb6nSMF7PeznTs2CDt7ElM6ntZHFO8NRfijSAI9kFWiPYb6ZPfTYfUZIVkrDHTwORgjQNa9LtcUxgTgprKY3zanmNUpJ5be9IiQngOes/1yNdcCK0TG0fzju1AznoPN4LDPi4HX8Z4H/7i9kedvENZWU4CQXbCvWU4IBjClToCSbGME2wnwPx9+eqoEpoyHLJFPxqWrRIaYpEPH4w==</verification_value>
    <month>3</month>
    <year>2029</year>
    <address1>33 Lane Road</address1>
    <city>Wanaque</city>
    <state>NJ</state>
    <zip>31331</zip>
    <country>US</country>
  </credit_card>
  <email>joey@example.com</email>
  <metadata>csWWNHl9cYgNO6WhNvuch+2jXoe0O7nrZN/Zbf4cKvhvkNUTp+Hl6MkvPiXpXImRUw5sMV6niCMra85bsURByllUWSpd+BfltOrOpk4Lt9am6yrMyMotQ8bkIbGmfTvKepL2S4bWjV9Ky4gDq4FKdKQCsX1DrHlIADbgBUiJvdRNC1Z8wBNWcImUCju359INp1qzzOt8ZjAYqL9xIqzGS2DNM7f+JxuDyMEN8uAdhEL4Dvvs2kSMHX8ho7xtYCP3kYkSopF7vaxOucEqgPRfbXAdsSL9Qkp3ohS4biCdIqbwfuQCJY9la0psHalYebQ6NWN2e60W6N1IrtShRHWXHg==</metadata>
  <encryption_certificate_token>Rkx3hmgN4QRuq8ZUunHdGpSniCg</encryption_certificate_token>
  <encrypted_fields>number, verification_value, metadata</encrypted_fields>
</payment_method>

HTTPS/1.1 200 OK
<transaction>
  <token>JcfBsU7qUy9y7DcRGJ7gq9btgX2</token>
  <created_at type="dateTime">2022-02-16T18:46:11Z</created_at>
  <updated_at type="dateTime">2022-02-16T18:46:11Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <transaction_type>AddPaymentMethod</transaction_type>
  <retained type="boolean">false</retained>
  <state>succeeded</state>
  <encrypted_fields>number, verification_value, metadata</encrypted_fields>
  <encryption_certificate_token>Rkx3hmgN4QRuq8ZUunHdGpSniCg</encryption_certificate_token>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <payment_method>
    <token>a26wp2B1waCkLQ334eU4g0GY1sV</token>
    <created_at type="dateTime">2022-02-16T18:46:11Z</created_at>
    <updated_at type="dateTime">2022-02-16T18:46:11Z</updated_at>
    <email>joey@example.com</email>
    <data nil="true"></data>
    <storage_state>cached</storage_state>
    <test type="boolean">true</test>
    <metadata>
      <key_1>String Value</key_1>
      <key_2>123</key_2>
    </metadata>
    <callback_url nil="true"></callback_url>
    <last_four_digits>4111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Joey</first_name>
    <last_name>Jones</last_name>
    <month type="integer">3</month>
    <year type="integer">2032</year>
    <address1>33 Lane Road</address1>
    <address2 nil="true"></address2>
    <city>Wanaque</city>
    <state>NJ</state>
    <zip>31331</zip>
    <country>US</country>
    <phone_number nil="true"></phone_number>
    <company nil="true"></company>
    <full_name>Joey Jones</full_name>
    <eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
    <shipping_address1 nil="true"></shipping_address1>
    <shipping_address2 nil="true"></shipping_address2>
    <shipping_city nil="true"></shipping_city>
    <shipping_state nil="true"></shipping_state>
    <shipping_zip nil="true"></shipping_zip>
    <shipping_country nil="true"></shipping_country>
    <shipping_phone_number nil="true"></shipping_phone_number>
    <payment_method_type>credit_card</payment_method_type>
    <errors>
    </errors>
    <verification_value>XXX</verification_value>
    <number>XXXX-XXXX-XXXX-1111</number>
    <fingerprint>3cef43464fc832f6e04f187df25af497994</fingerprint>
  </payment_method>
</transaction>

Request body

Name	Description
`transaction`	Root request element
`encryption_certificate_token` (required)	The token of the certificate used for encryption
`encrypted_fields` (required)	A list of all request fields that are encrypted, in the format “`field_1`, `field_2`” or “[`field_1`, `field_2`]”

Response body

Notable response elements include:

Name	Description
`transaction`	Root element
`encryption_certificate_token`	The certificate token sent in the request
`encrypted_fields`	The list of encrypted fields sent in the request