Forward card details to third-party API endpoints

To collect card details, use the Payment Element to create a PaymentMethod. After you create a PaymentMethod, we automatically store card details in Stripe’s PCI compliant vault. If you have your own frontend, you can still use the Vault and Forward API by creating a PaymentMethod directly.

Typically, you can only reuse PaymentMethods by attaching them to a Customer. However, the Vault and Forward API accepts all PaymentMethod objects, including those not attached to a customer.

Similarly, the Vault and Forward API doesn’t confirm or capture PaymentIntents. As a result, you might unintentionally use them to capture a payment on Stripe that was already captured on another processor.

CVCs expire automatically after a certain time period and also expire when used with the Vault and Forward API. If you require a CVC after either of these conditions are met, you must re-collect the card details.

To send card details from Stripe’s vault, you must Create a ForwardingRequest and include the following parameters:

• payment_method: Object that enables Stripe to identify your customer’s card details within Stripe’s vault and insert that data into the request body.
• url: The exact destination endpoint of your request.
• request.body: The API request body that you want to send to the destination endpoint (for example, the payments request you send to another processor). Leave any field where you normally input your customer’s card details blank.
• replacements: Fields that you want Stripe to substitute in the request.body. The available fields that we recommend always setting are card_number, card_expiry, card_cvc, and cardholder_name. For example, including card_number in the replacements array replaces the appropriate card number field for your destination endpoint in the request.body.

You must format your request based on the data that the destination endpoint expects. In the example below, the destination endpoint expects an Idempotency-Key header and accepts a JSON body with the payment details.

curl https://api.stripe.com/v1/forwarding/requests \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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

Stripe makes a request to the destination endpoint on your behalf by inserting the card details from the PaymentMethod into the request.body. Where enabled and available, the Card Account Updater (CAU) automatically attempts to update and provide the latest available card details for requests.

Stripe then forwards the request to the destination endpoint. For example:

1. Stripe makes a POST request to the endpoint:

   POST /v1/payments HTTP/1.1
   User-Agent: Stripe
   Accept: */*
   Host: endpoint-url
   Content-Type: application/json
   Content-Length: 321
   

2. Stripe includes the following headers:

   Destination-API-Key: {{DESTINATION_API_KEY}}
   Destination-Idempotency-Key: {{DESTINATION_IDEMPOTENCY_KEY}}
   

3. Stripe includes the following JSON body in the request:

   {
     amount: {
       value: 1000,
       currency: 'usd'
     },
     paymentMethod: {
       number: '4242424242424242',
       expiryMonth: '03',
       expiryYear: '2030',
       cvc: '123',
       holderName: 'First Last',
     },
     reference: '{{REFERENCE_ID}}'
   }
   

When you use the Vault and Forward API to forward card details to a third-party processor, Stripe synchronously waits for a response from the destination endpoint. The timeout period for this response is less than a minute. Stripe redacts identified PCI-sensitive data, stores the redacted response from the destination endpoint, and returns a ForwardingRequest object, which contains data about the request and response.

{
  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"
  ]
  ...
}