Store Payment Data (Tokenization)
This process, also known as tokenization, simply involves securely storing your customer’s card data in our systems.
This means that, as a Merchant, you can retain your customers' card details to facilitate future purchases through one-click payments or subscriptions.
The process will create a token identifier. Behind that identifier, our platform securely stores the complete card data except for the CVV.
This model is known as local tokenization, meaning that the token identifier can only be used on our platform.
We support two local tokenization models:
- Traditional
- Token Wallet
| Traditional | Token Wallet | |
|---|---|---|
| Who stores the token identifier | The Merchant, in its database | Sipay, associated with the user identifier (user_id) |
| Multiple cards per user | You must model and maintain the relationship in your system | Available without changes to your data model |
| What the Merchant provides | Storage of the token per user | A stable, opaque user identifier |
| Synchronization with Sipay | The Merchant's responsibility | Not needed |
| When it fits | Full control of the data and its lifecycle | Lower integration and maintenance effort |
Traditional
In this model, the merchant must manage the token identifier and store it in their own database along with other user data.
To capture card data, you can use any of our integration methods:
Token Wallet
In the Token Wallet model, Sipay manages your users' stored cards for you. The Merchant stores neither cards nor token identifiers: it only needs an opaque user identifier it already uses in its system. Sipay associates every card the user saves with that identifier.
You send that identifier in the user_id field when generating the payment link. The value "0" is reserved and means not to store or retrieve cards.
What the Merchant gets
- No card state in your system. You do not store token identifiers or manage their lifecycle.
- Multiple cards per user without changing your data model. No new tables, relationships or migrations.
- Less code to maintain. No need to synchronize your database with Sipay's when a user adds, changes or removes a card.
- Card management interface already available (see the image at the end of this section).
What the Merchant must provide
A user identifier that is stable, unique and opaque (see User identifier requirements).
Diagram 2 shows how a Merchant would have to implement multiple tokens per user with the traditional model:
Diagram 3 shows the solution our platform provides, with no changes to your database:
The visual aspect you’ll get in our product will look similar to the following image:
User identifier requirements
The identifier you send to Sipay must meet all of these requirements:
- Opaque: it must not contain or be directly derived from personal data (name, email, phone number, national ID, date of birth), not even through a hash.
- Stable: it must not change while the user's account exists.
- Unique per user within your merchant account.
- Unpredictable: we recommend a UUID v4 or a random value generated by your system, not an auto-incrementing number.
An unkeyed hash of a low-entropy value (national ID, phone number, email) can be reversed by brute force. Do not use it as the identifier.
Alternative if you cannot generate a new identifier
If you need to derive the identifier from data you already have and cannot generate a new one, use HMAC-SHA256 with a secret key owned by the Merchant, stored securely. Note that if you lose or rotate that key, you will lose the link to the stored cards.
In the Token Wallet, the user identifier gives access to that user's stored cards. Therefore:
- Use it only from your server. Never expose it to, or accept it from, the user's browser or mobile app without validating it.
- Take the identifier from the user's authenticated session in your system. Do not receive it as a parameter the client can edit: the API requires
user_idto not be modifiable by the client. - If the identifier is predictable (for example, auto-incrementing), a third party could try to access other users' cards.
Identifier lifecycle
TODO(michel): confirm with Product what happens if the user identifier changes in the Merchant's system (is there a card migration, or must cards be registered again?) and how to delete one card and all the cards of a user (right to erasure, GDPR). The documented API only allows deleting an individual token.
Example: show a user's stored cards
TODO(michel): a Traditional / Token Wallet comparison example is missing. The API documentation has no endpoint to list the cards associated with a user_id, so the example cannot be written without inventing it. Confirm whether that endpoint exists or whether the list is only shown on Sipay's payment page.