Skip to main content

Backup Stripe.com Tokens

One of the central value-propositions of Hellgate® is ensuring to keep our customers' payment data in their hands. This is why we provide a way to backup Stripe.com card payment-methods to Hellgate®. With Hellgate® the tokens are free to be used with any processor, to match the ever changing needs of our customers and the markets.

In this documentation we describe two ways to backup the Stripe.com payment-method data. Before diving into the options, a quick explaination of the backup process will help to understand the concepts.

Backup Approach​

Stripe.com offers a forward API, with which you can forward payment-method data to third-party services.

info

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

Conceptionally, the backup process is first a call to the forward API with the reference to payment-method, which triggers Stripe.com to forward the sensitive cardholder data (CHD) to Hellgate®. Hellgate® imports the data and returns a Hellgate® token in exchange. This token is the returned by the forward API to the original caller.

Hellgate Token Use-Case

As the forward API is gated, you need to request access first. In order to do so, you need to 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 Hellgate® as our vault provider. Please find their PCI DSS Attestation of Compliance attached.
The destination endpoint is https://api.hellgate.com/cde-import

You will need the PCI DSS Attestation of Compliance from Starfish.team, which you can get from your account representative. Please let us know if you encounter any issues with this step

Option 1 - Selective Backup​

In case you want to backup only a selected set of your payment methods at Stripe.com, you can trigger the forward API for each of these payment-methods.

Request​

Given a selected payment-method id from Stripe.com, you can trigger the forward API with the following request. You will need to replace the placeholders with the actual values:

  • <STRIPE-API-KEY>: Your Stripe.com API key
  • <STRIPE-PAYMENT-METHOD-ID>: The payment-method id from Stripe.com
  • <HELLGATE-API-KEY>: Your Hellgate® 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://staging.hellgate.dev/cde-import" \
  -d "request[headers][0][name]"=X-API-Key \
  -d "request[headers][0][value]"="<HELLGATE-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​

In the response you will receive the created Hellgate® token, which ID you can savely store in your system for reference. If you send in the Stripe.com payment-method id as metadata, you can always trace back the token to its origin 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"
}

Option 2 - Automatic Sync​

In case you want to synchronize the entire payment-method set from Stripe.com to Hellgate. You can use our import automation service. It will automatically trigger the forward API on your behalf and import the payment-methods into Hellgate®. Depending on the amount of payment-methods, this process can take a while.

tip

Inform your Hellgate® account representative about your import plans, so we can allocate the appropriate resources for your import.

To use the import automation service you request an import via API. The system then processes the request and will send a webhook notification as soon as the import was completed. Hellgate® will store the original payment-method id (business_key) with the token, so you can always trace back the token to its origin.

Create an Import Request​

For the import you need to pass in your Stripe.com API key. This key is used to authenticate the request to Stripe.com and to trigger the forward API. The key will only be used for the import and is not exposed to any other system.

curl -i -X POST \
  https://api.hellgate.io/tokens/imports \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: <YOUR_HELLGATE_API_KEY>' \
  -d '{
    "provider": "stripe",
    "stripe": {
      "api_key": "<YOUR_STRIPE_API_KEY>"
    }
  }'

In return you will receive an ID of the import job that was created. This ID can be used to track the progress of the import, by requesting the import status.

Check Import Status​

curl -i -X GET \
  'https://api.hellgate.io/tokens/imports/{id}' \
  -H 'X-API-KEY: <YOUR_HELLGATE_API_KEY>'

The import will start in the state preparing and will change to running as soon as the import was started. Once the import is completed, the state will change to finished.

See the API documentation for more details on the import API.