Skip to Content
ConceptsPaymentsStored payment cards

Using stored payment cards

Sharetribe allows you to store the payment card of a customer for future purchases. Doing this provides multiple benefits: it streamlines the checkout process for existing customers and allows you to place additional charges to the payment card of the customer.

Overview

The Sharetribe Web Template provides an interface via which users can store their payment card for future use. Once they’ve stored it, they are offered the option to use the same card for subsequent purchases without entering the details again.

Users can access their saved payment methods through their account settings. On this page, the user can store a new credit card, delete a stored card, or replace a stored card with a new one.

Currently, it is only possible to save one card, which becomes the default payment method. I.e. if there is already one payment card saved, your only option is to replace the card with a new one.

Read API documentation on storing credit cards 

Saving a payment method outside a transaction

You can save a payment method to a user profile without performing a payment at the same time. The user in question needs to be authenticated to perform these steps.

Create Stripe Setup Intent

Create Stripe Setup Intent  through Sharetribe API. A Stripe Setup Intent enables you to save a payment method for future payments.

Make a note of the client secret in the API response to use it in the next step.

Read more about Stripe Setup Intents in Stripe’s documentation:

Collect payment method information in your user interface

Your payment methods page needs to have a Stripe card element or payment element to collect the payment method’s details. Currently, only cards are supported in Sharetribe as saved payment methods.

Handle card setup with Stripe

Call stripe.confirmCardSetup with the client secret from step 1. This endpoint will confirm the card setup, and handle user actions like 3D Secure authentication if required.

Read more about stripe.confirmCardSetup in Stripe’s documentation:

Sharetribe Web Template uses stripe.handleCardSetup to set up a payment method, and the parameters are different from stripe.confirmCardSetup.

Read more about stripe.handleCardSetup in Stripe’s documentation:

Save the payment method to a Stripe Customer

The response from stripe.confirmCardSetup (or stripe.handleCardSetup, if you are using the Sharetribe Web Template) contains the ID of the payment method created with the SetupIntent under SetupIntent.payment_method.

To save that payment method to the current user, the user needs to have a Stripe Customer associated with their profile.

First, fetch the currentUser resource and include the stripeCustomer.defaultPaymentMethod relationships to see if the user already has either an associated Stripe Customer or a saved default payment method.

  • If the user does not have a stripeCustomer attached, use the Sharetribe API stripeCustomer.create endpoint and pass the payment method id as the stripePaymentMethodId parameter.

  • If the user already has a stripeCustomer, but they don’t have a defaultPaymentMethod, you can use stripeCustomer.addPaymentMethod to associate the payment method id with the user.

  • If the user has a stripeCustomer.defaultPaymentMethod, and you want to replace it with the new payment method, you need to first remove the previous card and then add the new one.


Endpoint(s)
No Stripe Customer

stripeCustomer.create 

Existing Stripe Customer, no defaultPaymentMethod

stripeCustomer.addPaymentMethod 

Existing Stripe Customer and defaultPaymentMethod

stripeCustomer.deletePaymentMethod , stripeCustomer.addPaymentMethod 

Saving a payment method when making a payment

You can also save the payment method that the user uses to make a payment, if the user indicates they want to do so. This requires some specific steps when creating the PaymentIntent associated with the payment.

Check currentUser for an existing saved payment method

Before initiating the payment transition, fetch the currentUser resource and include the stripeCustomer.defaultPaymentMethod relationships to see if the user already has either an associated Stripe Customer or a saved default payment method. Doing this before starting the payment flow means that we can take the correct steps once the payment itself has been handled.

Pass setupPaymentMethodForSaving parameter to payment request

When requesting payment i.e. creating the PaymentIntent, the stripe-create-payment-intent action requires a specific parameter – setupPaymentMethodForSaving – to be passed if the payment method needs to be saved at the same time.

If you don’t pass this parameter in the transition API call, then the payment method in question cannot be saved to the user in the later step.

In the Sharetribe Web Template this is handled by default in the first step of the processCheckoutWithPayment function.

Read more about the stripe-create-payment-intent action and its parameters:

Process the next steps of the transaction

Storing a payment method does not affect the following steps of handling the payment, such as making the stripe.confirmCardPayment call, triggering the confirm-payment transition, and possible other actions you need to process. You can handle them as you would in a regular transaction.

However, you will need to access the PaymentIntent resource of the transaction, either by fetching it from Stripe or retrieving it from an API response when confirming the payment with Stripe.

You will use the payment_method attribute of the PaymentIntent when associating the payment method with a Stripe Customer in the next step.

Create a Stripe customer and attach the payment method

In step 1, you fetched the currentUser resource to see if the user already has either an associated Stripe Customer or a saved default payment method.

To save the payment method from the PaymentIntent to the current user, the user needs to have a Stripe Customer associated with their profile.

The payment method ID of the PaymentIntent is in the attribute PaymentIntent.payment_method.

  • If the user does not have a stripeCustomer attached, use the Sharetribe API stripeCustomer.create endpoint and pass the payment method id as the stripePaymentMethodId parameter.

  • If the user already has a stripeCustomer, but they don’t have a defaultPaymentMethod, you can use stripeCustomer.addPaymentMethod to associate the the payment intent’s payment method id with the user.

  • If the user has a stripeCustomer.defaultPaymentMethod, and you want to replace it with the new payment method, you need to first remove the previous card and then add the new one.


Endpoint(s)
No Stripe Customer

stripeCustomer.create 

Existing Stripe Customer, no defaultPaymentMethod

stripeCustomer.addPaymentMethod 

Existing Stripe Customer and defaultPaymentMethod

stripeCustomer.deletePaymentMethod , stripeCustomer.addPaymentMethod 

Once you set up your payment flow to properly save a card with the Payment Intents or Setup Intents API, Stripe will mark any subsequent off-session payment as a merchant-initiated transaction to reduce the need to authenticate. Merchant-initiated transactions require an agreement (also known as a “mandate”) between you and your customer. Read more about merchant-initiated transactions in Stripe’s documentation:

Charging saved cards

If the user has a default payment method and they choose to use it to make a payment, you need to make the following adjustments to the default payment initiation.

First, when you call the transition that has stripe-create-payment-intent and want to use a customer’s saved payment method, you need to pass the payment method id as an API call parameter to use the saved payment method.

Read more about the stripe-create-payment-intent action and its parameters:

Second, when you are confirming the payment intent toward Stripe with stripe.confirmCardPayment, you do not need to pass the card element parameter since you are using the default payment method.

Read more about stripe.confirmCardPayment in Stripe’s own documentation:

Frequently asked questions about storing payment cards

How many payment cards can I store per customer?

Right now you can only store one payment card per customer. If you store a new card, the old one is replaced.

How do I edit the details of a stored credit card?

You can’t edit the details of a stored payment card. Instead, you need to delete the card and create a new card.

Can I create delayed charges?

Sometimes you might want to store the payment card details of the customer when they make a booking, but initiate the actual charge only later. A typical example could be booking a venue for a wedding. The initial booking might be done a year in advance, but the charge might happen only a bit before the event, or even after it.

It’s possible for you to adjust your transaction process to add a transition that attempts to automatically charge the card of the customer at a specific point in time. This is called an off-session payment, and we have a separate article describing how you can build such a process.

Read more about automatic off-session payments:

Can I create extra charges to the payment card of the customer?

Sometimes you might want to create extra charges for a stored card after an initial purchase. For example, if a rented item is stolen or damaged by the customer or returned late, you might want to charge the customer extra to cover these costs.

If your marketplace uses Strong Customer Authentication to verify credit card purchases, you cannot create additional charges to their card without allowing them to approve the charge with Strong Customer Authentication.

If that is not the case, you can initiate additional charges directly from your Stripe dashboard. You should always notify the customer in question about why an extra charge was placed on their card. The additional charges won’t get displayed in Sharetribe Console. The money from the extra charges is placed to your platform’s Stripe balance, from which it is moved to your bank account. If a payout to the provider (in this case the owner of the item) is needed, you will need to handle it manually from your own bank account.

Can I enable recurring / subscription payments?

Stripe supports subscriptions , which could be used to allow your providers to charge recurring payments from your customers. As an example, a customer might rent a storage unit from a provider. You might want to create a subscription that automatically charges the customer’s card every month, until the customer cancels the storage subscription.

Right now, Sharetribe doesn’t offer support for Stripe subscriptions. However, there is a workaround with custom development. Once the customer has made the initial payment, you would send a request to your own backend component, for instance the server of your Sharetribe Web Template, which would then create a subscription with the stored credit card of the customer. The subsequent subscription payments would then not be visible in Sharetribe Console, but you could monitor them from Stripe dashboard.

Last updated on
Providers and customers on your Stripe PlatformOff-session payments