Save card on Payment

Tokenization allows you to store a token in place of a customer’s raw card data. Instead of collecting the full card details for every future payment, you can use the stored token—improving both security and user experience. This is especially useful for recurring or subscription-based billing.

Tokenization flow

1. Customer Enters Card Details: During their first purchase, customers can consent to save (tokenize) their card.
2. Token Generation: xMoney converts the customer’s card details into a token (cardId) and stores it securely.
3. Subsequent Payments: For future orders, simply reference the token instead of requiring the full card details again.

Generating a token

To generate a token at checkout, follow these steps:

Add saveCard to your Pay Form

In your pay form template (HTML), include a “Save Card” option that xMoney can use to determine whether the customer’s card should be tokenized. For example:

<div class="clearfix"></div>

{{ saveCard }}

Visibility: You can choose to make this checkbox or button visible to the customer (so they can opt in or out) or hide it (so the card is always saved).

Mark the order to save card

In your order request data, set saveCard to true. Example:

{
  "siteId": 10077,
  "customer": {
    "identifier": "testSaveCard"
  },
  "order": {
    "orderId": "testSaveCard1",
    "type": "purchase",
    "amount": 21,
    "currency": "EUR",
    "description": "product description"
  },
  "cardTransactionMode": "authAndCapture",
  "saveCard": true
}

When the customer submits payment with the above parameters and enters their card details, xMoney will generate:

• An orderId
• A transactionId
• A cardId (the actual token)

The cardId is then tied to the customer’s identifier (e.g., "testSaveCard") in your system.

Handling response

After the payment completes (authorization and capture), xMoney returns a response indicating success or failure. This response is provided via opensslResult if you have IPN/webhook notifications or direct server responses enabled.

A successful transaction with saveCard enabled will include a cardId.

Example of a decrypted response:

{
  "transactionStatus": "complete-ok",
  "orderId": 1234,
  "transactionId": 1234,
  "cardId": 98765,
  "customerId": 1001,
  "amount": 21,
  "currency": "EUR",
  ...
}

Storing the cardId

1. Decrypt and parse the opensslResult payload to read the JSON data.
2. Extract the cardId field.
3. Associate the cardId with the correct customerId or identifier in your database.
4. Store it for future transactions (e.g., in your user profile or an internal tokens table).

Using the token in future orders

Once you have a cardId, you can use it for subsequent orders without requiring the full card number, expiry date, etc.:

{
  "siteId": 10077,
  "customer": {
    "identifier": "testSaveCard"
  },
  "order": {
    "orderId": "testSaveCard11",
    "type": "purchase",
    "amount": 1,
    "currency": "EUR",
    "description": "product description"
  },
  "cardTransactionMode": "authAndCapture",
  "cardId": 98765
}

Best practices

1. Customer Consent: Clearly explain how their card data is saved.
2. Identifier Management: Use unique customer identifiers to avoid mixing tokens between different users.
3. Subscription Flow: For recurring charges, consider hiding the “Save Card” option on the initial transaction if you want to guarantee a token is created. You will have to send the saveCard: true param when creating the order.

Conclusion

Card Tokenization through xMoney streamlines checkout, enhances security, and supports recurring payments. By including saveCard in your request, parsing the resulting cardId from the response, and referencing that token in future purchases, you eliminate the need for repeated card entry—leading to a faster, more user-friendly payment flow.