Save Card without Payment

In some scenarios, you may wish to save (tokenize) a customer’s card without charging them the full purchase amount right away. One way to achieve this is to initiate a small (micropayment) authorization — for example, 0.10 EUR — to validate and tokenize the card. Once the transaction completes successfully, you can void the micropayment so the customer is not actually charged. The result is a saved card (token) for future transactions.

Flow Overview

1. Create a Micropayment Request

   • Use a minimal amount (e.g., 0.10 EUR).
   • Include saveCard: 1 to ensure the card is tokenized.
   • Set cardTransactionMode to auth so the amount is only authorized (not captured).

2. Wait for the Transaction to Complete

   • Check the status. If complete-ok, the token (cardId) is generated and tied to the customer.

3. Void the Authorization

   • Send a delete (void) transaction with reason "customer-demand" (or similar) and a relevant message.
   • This removes the financial hold for the micropayment but keeps the token active.

4. Token Is Now Available

   • The card is saved and can be referenced in future payment requests using its cardId, without additional card input from the customer.

Example Micropayment Request

Below is a minimal JSON request illustrating how to create a micropayment while saving the card:

{
  "siteId": 10077,
  "customer": {
    "identifier": "cardOnlyFlow"
  },
  "order": {
    "orderId": "saveCardTest1",
    "type": "purchase",
    "amount": 0.10,
    "currency": "EUR",
    "description": "Micropayment to save card"
  },
  "cardTransactionMode": "auth",
  "saveCard": 1
}

Notes

• Amount: 0.10 EUR is just an example. Use any minimal amount you prefer.
• Order Type: Typically purchase.
• cardTransactionMode: Setting this to auth authorizes the amount only, so you can void it later, preventing an actual charge.
• saveCard: Setting this to 1 ensures a token (cardId) is created.

When the customer enters their card details, xMoney will generate a token once the payment status is complete-ok.

Check Transaction Status and Extract cardId

After the micropayment is authorized, you receive the final transaction status (e.g., via webhook or direct response). A typical successful response (decrypted if using opensslResult) looks like:

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

1. Confirm that transactionStatus is complete-ok.
2. Store the cardId for future use. This is the customer's token.

Void the Authorization

To ensure the customer isn’t charged for the test amount, void the micropayment immediately after receiving a successful authorization.

curl -X DELETE "https://api-stage.xmoney.com/transaction/1234" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "amount=0.10" \
  --data-urlencode "reason=customer-demand" \
  --data-urlencode "message=card-saved"

• transactionId: Replace 1234 with the actual ID of the authorized micropayment.
• amount: The authorized amount.
• reason and message: Provide a concise explanation, such as "customer-demand" and "card-saved" or "transaction-failed", depending on your business logic.

Future Payments with the Saved Card

After you’ve voided the authorization, the card remains tokenized:

{
  "siteId": 10077,
  "customer": {
    "identifier": "cardOnlyFlow"
  },
  "order": {
    "orderId": "followUpOrder1",
    "type": "purchase",
    "amount": 99.99,
    "currency": "EUR",
    "description": "Product purchase using saved card"
  },
  "cardTransactionMode": "authAndCapture",
  "cardId": 98765
}

• Replace cardId with the token you stored.
• The customer no longer needs to enter full card details again.
• 3D Secure may still apply based on issuer/regulatory requirements.

Best Practices

1. Communicate Clearly: Inform the customer that a minimal charge is being performed to validate their card, but it will not be finalized.
2. 3D Secure: If the card requires 3DS authentication, additional steps may be necessary during the challenge or frictionless flow. Future use of the token might also require 3DS.
3. Customer Satisfaction: Promptly voiding the micropayment helps avoid any confusion or unexpected temporary holds on the customer’s account.

Conclusion

By using a micropayment flow with cardTransactionMode set to auth, you can safely validate and tokenize a card without performing a full transaction. Once you receive a complete-ok status and cardId, simply void the authorization. This process gives you a saved card on file, ready for future purchases and a streamlined checkout for returning customers.