Broadleaf Microservices
  • v1.0.0-latest-prod

Saving a Payment Method for Future Use

During checkout, companies may provide logged-in customers the opportunity to save a payment method for future use. Often this is done with a newly-provided credit card. In our experience, this typically involves interacting with the payment gateway to tokenize the credit card data, which can produce a single-use token or a multi-use token. Note, it’s important to understand which type of token is provided by the payment gateway’s tokenization interaction.

When creating a Payment, the following properties are especially important:

  • shouldSavePaymentForFutureUse = true - Declares the user’s intention to save the payment method for future use.

  • isSingleUsePaymentMethod - Declares whether the provided payment method (often the credit card token) can be used once. If false, then the payment method can be used multiple times.

  • paymentMethodProperties - Map used to hold the properties that define the payment method (e.g. the credit card token)

Often payment gateways provide the ability to produce a multi-use token while executing a transaction against the single-use token. If this is the case, then the new multi-use token will be included in the PaymentResponse#paymentMethodProperties map. From there, the PaymentResponse#paymentMethodProperties are added to the Payment#paymentMethodProperties map.

Finally, when the first transaction for the payment is executed (AUTHORIZE or AUTHORIZE_AND_CAPTURE), a SavedPaymentMethod or PaymentAccount is created based on the Payment.

If the save payment storage location is configured to use CustomerServices, the saved payment method is stored as PaymentAccount. Otherwise, it is stored as SavedPaymentMethod, which is the PaymentTransactionServices' representation of saved payment method. For more details on saved payment handling service configuration, please see Saved Payment Method Configurations