Back Up Stripe.com Tokens

This guide describes how to back up Stripe.com payment-method data to Commerce.

Backup Approach

Stripe.com offers a forward API to forward payment-method data to third-party services.

The API is a gated feature on the Stripe.com platform. You need to request access from support.

Conceptually, the backup process is a call to the forward API with a reference to a payment method. Stripe.com then forwards the sensitive cardholder data (CHD) to Commerce. Commerce imports the data and returns a Commerce token in exchange; this token is returned by the forward API to the caller.

As the forward API is gated, you need to request access first. Create a Stripe.com support request on your account with the following information:

What do you need help with? Payment APIs
What is your question? I require access to the Vault and Forward API
Tell us more — how can we help? We would like to request access to the Stripe Forward API in order to store payment method information with my vault. We use Commerce as our vault provider. Please find their PCI DSS Attestation of Compliance attached. The destination endpoint is https://api.hellgate.io/cde-import

You will need the PCI DSS Attestation of Compliance from Starfish, which you can get from your account representative.

Commerce accepts imports on /cde-import only when CDE import is enabled for your account, which requires at least SAQ D PCI DSS compliance. Requests forwarded by Stripe.com are no exception.

Back Up a Payment Method

Trigger the forward API once for each payment method you want to back up.

Request

Replace the placeholders with your actual values:

STRIPE_API_KEY: Your Stripe.com API key
STRIPE_PAYMENT_METHOD_ID: The payment-method id from Stripe.com
COMMERCE_API_KEY: Your Commerce API key

curl -v https://api.stripe.com/v1/forwarding/requests \
  -u "STRIPE_API_KEY:" \
  -d payment_method="STRIPE_PAYMENT_METHOD_ID" \
  --data-urlencode url="https://api.hellgate.io/cde-import" \
  -d "request[headers][0][name]"=X-API-Key \
  -d "request[headers][0][value]"="COMMERCE_API_KEY" \
  --data-urlencode "request[body]"='{"metadata":{"business_key":"STRIPE_PAYMENT_METHOD_ID"},"card":{"number":"","exp_month":"","exp_year":"","cvc":"","name":""}}' \
  -d "replacements[0]"=card_number \
  -d "replacements[1]"=card_expiry \
  -d "replacements[2]"=card_cvc \
  -d "replacements[3]"=cardholder_name

Response

The response includes the created Commerce token; you can store its ID in your system. If you send the Stripe.com payment-method id as metadata, you can trace the token back via the business_key attribute.

{
  "id": "5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d",
  "business_key": "STRIPE_PAYMENT_METHOD_ID",
  "cardholder_name": "John Doe",
  "created_at": "2023-10-01T00:00:00Z",
  "expiry_month": 4,
  "expiry_year": 2033,
  "masked_account_number": "424242******4242",
  "scheme": "VISA"
}

Using the Dashboard

Integration & Security

Backup Approach

Back Up a Payment Method

Request

Response

​Backup Approach

​Back Up a Payment Method

​Request

​Response

Backup Approach

Back Up a Payment Method

Request

Response