Back up Your Stripe Tokens

In the ever-evolving world of online transactions, prioritizing innovation and operational efficiency is becoming critical to organizational payment divisions. This is even more true with the potential for sudden Stripe account terminations, the need for scalable payment processing solutions beyond a single provider, and other payment services to drive new revenue and cost savings. In some cases, merchants and platforms with a multiprocessor payment ecosystem must create a unified wallet system or single source of truth for consumer profiles.

This guide explores using the Stripe Forwarding API in tandem with Basis Theory's secure Vault to open access to card data and enable new opportunities without making any changes to your existing Stripe integration.

Getting Started

To get started, you will need to create a Basis Theory Account and a TEST Tenant.

Sign Up

Sign In

Make sure to use your work email (e.g., john.doe@yourcompany.com)

Request Access to Stripe Forwarding API

Click here to create a Stripe support request following this template:

Account
Select your Stripe account

What do you need help with?
Payment APIs

What is your question?
I need access to the Vault and Forward API

Tell us more — how can we help?
I would like to request access to the Vault and Forward API
to store payment method details with my own token vault,
outsourced by Basis Theory. Please find their PCI Attestation of Compliance attached.
The target endpoint is https://api.basistheory.com/tokens

Make sure to attach Basis Theory PCI DSS Attestation of Compliance to your request.

If you need help with this step, or anytime along the way, don't hesitate to reach out to us.

Creating a Public Application

Next you will need a Public Application using our PCI-compliant template Collect PCI Data. Click here to create one.

This will create an application with the following Access Controls:

• Permissions: token:create, token:update
• Containers: /pci/
• Transform: mask

Save the API Key from the created Public Application as it will be used later in this guide.

Vaulting Cards

Once you are granted access to the Stripe's Forwarding API and created the Basis Theory Public API Key, choose your favorite HTTP Client for your server-side language and call the forwarding endpoint:

In the metadata object you can pass any of the Basis Theory token properties documented here.

Vault a Card

curl --location 'https://api.stripe.com/v1/forwarding/requests' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer <STRIPE_API_KEY>' \
--data-urlencode 'payment_method=<STRIPE_PAYMENT_METHOD_ID>' \
--data-urlencode 'url=https://api.basistheory.com/connections/stripe-forward/tokenize' \
--data-urlencode 'request[headers][0][name]=BT-API-KEY' \
--data-urlencode 'request[headers][0][value]=<BT_API_KEY>' \
--data-urlencode 'request[body]={"card": { "number": "", "exp_month": "", "exp_year": "", "cvc": "", "name: "" }, "metadata": { } }' \
--data-urlencode 'replacements[0]=card_number' \
--data-urlencode 'replacements[1]=card_expiry' \
--data-urlencode 'replacements[2]=card_cvc'\
--data-urlencode 'replacements[3]=cardholder_name'

Make sure to replace the Stripe API Key, Payment Method Identified (twice) and Basis Theory API Key.

You should receive a response containing a new Basis Theory token aliased to the Stripe token. This means the credit card data is backed up in Basis Theory Vault using the same Payment Method identifier by Stripe.

Keeping Cards In Sync

Enterprise

Saved Stripe payment methods can receive updates from Networks when consumers receive new cards (e.g., replacing stolen, lost or expired cards). When an update to a payment method happens, Stripe fires webhooks which can be leveraged to also update your Basis Theory Vault.

1. Set up Stripe webhooks for payment_method.updated and payment_method.automatically_updated events, following their documentation.
2. When any of those are fired and hit your endpoints, initiate a forward request (see request example above) to Stripe in order to update the existing Basis Theory token.

If you are interested in using Stripe's Account Updater in combination with Basis Theory Vault, let's talk.

Alternatively, you can leverage Basis Theory Account Updater to have a single source of truth for the latest and greatest card information, while keeping multiple Payment Processors tokens up-to-date, including Stripe.