By offering Processor Tokenization, Silverflow provides an API that safely stores sensitive card information and provides a unique key that can be used across the Silverflow platform to authenticate and authorize initial and subsequent recurring transactions. The goal and benefit of using Processor Tokenization is that the key replaces the card input object, which helps limit exposure to PCI-DSS requirements and minimizes the use of sensitive data in API calls while still enabling the functionality for recurring transaction sequences that the card networks provide.

This form of tokenization is commonly referred to as 'proprietary' or 'acquirer' tokenization. The provided unique keys can only perform actions on the Silverflow platform. This differs from Network Tokens, which can be processed with the acquirer-processor of choice. For more information on this, see our documentation on Network Tokenization.

Create a Processor Token

When you want to store a card safely in our Token vault, you can obtain a processorTokenKey by posting the required card data to the /processorTokens endpoint.

The CVC is optional, as we also allow providing the CVC in the other endpoints, such as /3ds, /charges, and /mit. If the CVC is provided, the cvcPresent indicator is set to true.

The CVC will be automatically removed from the Processor Token after a successfully authorized charge. Additionally, the cvcPresentindicator will be set to false, and the version of the entity will be incremented.

The response to the Create a Card call also provides cardInfo, which allows you to determine whether a card is co-branded.

Get a Processor Token

You can use a GET on the /processorTokens endpoint with the processorTokenKey as a path parameter to fetch the card metadata linked to the card stored under the processorTokenKey. This will result in

The lastActionDate on the response shows when this processorTokenKey was last used on the Silverflow platform.

Archive a Processor Token

It is possible to archive a Processor Token on the platform. DELETE can do this with the processorTokenKey as a path parameter to the /processorTokens/{processorTokenKey} endpoint.

Retrieve Card Data

The Get Processor Token's Card Data endpoint can be used to retrieve the underlying card data of a Processor Token. We use a combination of asymmetrical and symmetrical encryption to allow you to retrieve card data in a secure manner.

The steps required to retrieve card data are:

Generate an RSA Key Pair: First, generate a standard RSA-2048 key pair.
Share your Public Key: Send your public key to your Silverflow Technical Account Manager via email in the PEM (Privacy Enhanced Mail) format. We'll register it in our system.
Receive your Key ID: We will provide you with a unique identifier for your key, the processorTokenPublicKey. You'll use this ID to make API requests.
Request the Encrypted Data: Make a GET request to the Get Processor Token's Card Data endpoint, passing your processorTokenPublicKey as a query parameter.
Receive the payload: You'll get back a JSON response containing three crucial, Base64url-encoded fields: encryptedCardData, encryptedDataKey, and iv.
Decode the fields: Before decryption, you must Base64url-decode the encryptedCardData, encryptedDataKey, and iv values.
Decrypt the data key: Use your private RSA key to decrypt the decoded encryptedDataKey. This reveals the one-time symmetric AES-256-CBC data encryption key.
Decrypt the card data: Finally, use the secret key from the previous step and the decoded iv to decrypt the decoded encryptedCardData. The result is the plain-text JSON string containing the card details.

Ensure your cryptographic library is configured with these settings for successful decryption:

Asymmetric Algorithm: RSA-2048
RSA Padding Mode: RSA_PKCS1_OAEP_PADDING
OAEP Hash Function: SHA-256
Symmetric Algorithm: AES-256-CBC
Encoding: All encrypted fields including the iv are Base64url encoded.
Final Output: The decrypted card data has to be encoded in utf-8 to read the card data which is a JSON string that follows the schema in the createProcessorToken documentation.