Forward card details to third-party API endpoints

The Vault and Forward API allows you to tokenize and store card details in Stripe’s PCI-compliant vault and route that data to supported processors or endpoints. Leverage the API to:

• Use the Payment Element across multiple processors.
• Use Stripe as your primary vault for card details across processors.
• Route card details to your own PCI compliant token vault.

Forward requests to destination endpoints and populate card details from Stripe’s vault

curl https://api.stripe.com/v1/forwarding/requests \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Idempotency-Key: 
{{IDEMPOTENCY_KEY}}
" \
  -d payment_method=
"{{PAYMENT_METHOD_ID}}" \
  --data-urlencode url="https://endpoint-url/v1/payments" \
  -d "request[headers][0][name]"=Destination-API-Key \
  -d "request[headers][0][value]"={{DESTINATION_API_KEY}} \
  -d "request[headers][1][name]"=Destination-Idempotency-Key \
  -d "request[headers][1][value]"={{DESTINATION_IDEMPOTENCY_KEY}} \
  --data-urlencode "request[body]"="{\"amount\":{\"value\":1000,\"currency\":\"usd\"},\"paymentMethod\":{\"number\":\"\",\"expiryMonth\":\"\",\"expiryYear\":\"\",\"cvc\":\"\",\"holderName\":\"\"},\"reference\":\"{{REFERENCE_ID}}\"}" \
  -d "replacements[0]"=card_number \
  -d "replacements[1]"=card_expiry \
  -d "replacements[2]"=card_cvc \
  -d "replacements[3]"=cardholder_name

{
  id: "fwdreq_123",
  object: "forwarding.request",
  payment_method: "{{PAYMENT_METHOD}}",
  request_details: {
    body: '{
      "amount": {
        "value": 1000,
        "currency": "usd"
      },
      "paymentMethod": {
        "number": "424242******4242",
        "expiryMonth": "03",
        "expiryYear": "2030",
        "cvc": "***",
        "holderName": "First Last",
      },
      "reference": "{{REFERENCE_ID}}"
    }',
    headers: [
      {
        name: "Content-Type",
        value: "application/json",
      },
      {
        name: "Destination-API-Key",
        value: "{{DESTINATION_API_KEY}}",
      },
      {
        name: "Destination-Idempotency-Key",
        value: "{{DESTINATION_IDEMPOTENCY_KEY}}",
      },
      ...
    ]
  },
  request_context: {
      "destination_duration": 234,
      "destination_ip_address": "35.190.113.80"
  },
  response_details: {
    body: '{
      // Response from the third-party endpoint goes here
      ...
    }',
    headers: [
      ...
    ],
    status: 200,
  },
  replacements: [
    "card_number",
    "card_expiry",
    "card_cvc",
    "cardholder_name"
  ]
  ...
}

Configure your Vault and Forward API endpoint

To set up your Vault and Forward API endpoint, you must:

• Confirm that we support the destination endpoint.
• Provide a test and production account with Stripe support.
• Share the production details for the destination endpoint with Stripe support.

Confirm that we support the destination endpoint

Stripe supports forwarding API requests to the following endpoints:

• Adyen:
  • [prefix]-checkout-live.adyenpayments.com/checkout/v68/payments
  • [prefix]-checkout-live.adyenpayments.com/checkout/v68/storedPaymentMethods
  • [prefix]-checkout-live.adyenpayments.com/checkout/v69/payments
  • [prefix]-checkout-live.adyenpayments.com/checkout/v69/storedPaymentMethods
  • [prefix]-checkout-live.adyenpayments.com/checkout/v70/payments
  • [prefix]-checkout-live.adyenpayments.com/checkout/v70/storedPaymentMethods
  • [prefix]-checkout-live.adyenpayments.com/checkout/v71/payments
  • [prefix]-checkout-live.adyenpayments.com/checkout/v71/storedPaymentMethods
• Braintree:
  • payments.braintree-api.com/graphql
• Checkout:
  • api.checkout.com/tokens
  • api.checkout.com/payments
• Fat Zebra:
  • gateway.pmnts.io/v1.0/credit_cards
• FlexPay:
  • api.flexpay.io/v1/gateways/charge
• GMO Payment Gateway:
  • p01.mul-pay.jp/payment/ExecTran.json
• PaymentsOS:
  • api.paymentsos.com/tokens
• SoftBank:
  • stbfep.sps-system.com/api/xmlapi.do
• Spreedly:
  • core.spreedly.com/v1/payment_methods.json
• TabaPay:
  • [prefix]/v1/clients/[ClientID]/accounts
• Worldpay:
  • access.worldpay.com/api/payments
  • access.worldpay.com/cardPayments/customerInitiatedTransactions
  • access.worldpay.com/tokens
  • secure.worldpay.com/jsp/merchant/xml/paymentService
• Your own PCI-compliant token vault

Stripe supports HTTPS-based APIs that accept JSON/XML requests and return JSON/XML responses. If your destination endpoint isn’t supported or you require a different API format, share the endpoint details with Stripe support to get support for your specific needs.

Supported countries

The Vault and Forward API can only forward requests to the following countries:

Additionally, ensure that your Stripe account is registered in one of these countries:

Provide test accounts to Stripe support

To access the Vault and Forward API, share the account IDs (acct_xxxx) for your test accounts with Stripe support.

Share production details

Share the production details for destination endpoint with Stripe support. These include the following for destination endpoint: URL, HTTP method, documentation, fields, request headers, and encryption keys. Stripe then sets up destination endpoint for use with the Vault and Forward API in live mode.

To share third-party API keys, you must encrypt them by using the Stripe public key that’s specific to the Vault and Forward API. Start by importing a public key using the GNU Privacy Guard (PGP). After you familiarize yourself with the basics of PGP, use the following PGP key to encrypt your third-party API keys:

-----BEGIN PGP PUBLIC KEY BLOCK-----

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
UraCYX03loNHRxLCyeHR4GA=
=bbos
-----END PGP PUBLIC KEY BLOCK-----

To encrypt your third-party API keys with the Vault and Forward API PGP key:

1. Create a file named hash_encrypt_key.sh with the content below. The script generates a SHA256 hash of your API key, encrypts it with Stripe’s public key, and then Base64 encodes it.

   Required utilities

   To run the script, you must first install the sha256sum, gpg, and base64 utilities.

   Command Line

   #!/bin/sh
   set -euo pipefail
   fail () { printf "Error: $1\n" >&2 && exit 1; }
   
   STRIPE_PUBLIC_KEY=AE863ADA1603150856C0A853A7B203177D034588
   API_KEY=$(printf "$1" | tr -d '\n' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
   
   [ -x "$(command -v sha256sum)" ]                    || fail "sha256sum is not installed."
   [ -x "$(command -v gpg)" ]                          || fail "gpg is not installed."
   [ -x "$(command -v base64)" ]                       || fail "base64 is not installed."
   [ ! -z "$API_KEY" ]                                 || fail "Please pass in an API key."
   grep -iqv "Basic \|Bearer " <<< "$API_KEY"          || fail "Please omit the Basic/Bearer prefix."
   gpg --list-keys $STRIPE_PUBLIC_KEY > /dev/null 2>&1 || fail "Stripe public key not imported."
   
   printf "$API_KEY" | sha256sum | cut -d " " -f 1 | tr -d '\n' | gpg -e -r $STRIPE_PUBLIC_KEY --always-trust | base64 > encrypted_hashed_key.txt
   printf "Successfully generated encrypted_hashed_key.txt\n"

2. Run the script by passing your third-party API key in single quotes, omitting any Bearer or Basic prefix. The key must be the exact key that you use for actual requests to the destination endpoint, not including any prefix.

   The script produces a file named encrypted_hashed_key.txt.

   Command Line

   sh hash_encrypt_key.sh '<THIRD_PARTY_API_KEY>'

Test your integration

To confirm that your integration works correctly with destination endpoint, initiate a ForwardingRequest using the PaymentMethod you created. This example uses pm_card_visa as a payment method.

curl https://api.stripe.com/v1/forwarding/requests \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Idempotency-Key: 
{{IDEMPOTENCY_KEY}}
" \
  -d payment_method=pm_card_visa \
  -d url="{{DESTINATION ENDPOINT}}" \
  -d "request[headers][0][name]"=Destination-API-Key \
  -d "request[headers][0][value]"={{DESTINATION_API_KEY}} \
  -d "request[headers][1][name]"=Destination-Idempotency-Key \
  -d "request[headers][1][value]"={{DESTINATION_IDEMPOTENCY_KEY}} \
  --data-urlencode "request[body]"="{\"amount\":{\"value\":1000,\"currency\":\"usd\"},\"paymentMethod\":{\"number\":\"\",\"expiryMonth\":\"\",\"expiryYear\":\"\",\"cvc\":\"\",\"holderName\":\"\"},\"reference\":\"{{REFERENCE_ID}}\"}" \
  -d "replacements[0]"=card_number \
  -d "replacements[1]"=card_expiry \
  -d "replacements[2]"=card_cvc \
  -d "replacements[3]"=cardholder_name

View your request logs in the Dashboard

You can view request logs and errors related to the Vault and Forward API in Workbench. Additionally, you can use the List API to fetch the logs from Stripe.