How it works
Stripe takes form-encoded requests authorized with your secret key. You build the request as usual, put the Card Vault placeholders where the card data goes, and send it to the Card Vault proxy with the card's token. The proxy fills in the card data, sends the request to Stripe and returns Stripe's reply unchanged.
Test mode and live mode use the same host: your key decides which one the request runs in.
Before you start
- Raw card data access on your Stripe account. Stripe refuses card numbers in API requests until it has turned on raw card data APIs for your account. Ask Stripe support with the subject "Request to enable raw card data APIs". For test mode alone, Stripe asks for no documents. For live mode, Stripe asks for your PCI DSS self-assessment naming Enigma Vault as your third-party service provider, and may ask for our Attestation of Compliance, which is on the developer portal's Artifacts page on paid plans.
- A Stripe secret key (
sk_test_...orsk_live_...), or a restricted key with write access to PaymentIntents (and SetupIntents to save cards). - A card stored in Card Vault, and its token. To send the CVC, store the card with a CVV and a
ttl; the CVV is kept only until then. - If you set a proxy domain allowlist on your client ID, add
api.stripe.com.
Fill in your own values where the examples say YOUR_.... The card placeholders, such as ${ccn}, stay as they are: the proxy replaces them.
Charge a stored card (PaymentIntent)
Creates and confirms a PaymentIntent in one request. amount is in the currency's smallest unit (1000 is $10.00). Send a new Idempotency-Key for each order, so a retry after a timeout cannot charge twice.
What Stripe receives
POST https://api.stripe.com/v1/payment_intents, with this body (laid out for reading; the request sends it as one line):
amount=1000
¤cy=usd
&confirm=true
&payment_method_types[]=card
&payment_method_data[type]=card
&payment_method_data[card][number]=${ccn}
&payment_method_data[card][exp_month]=${mm}
&payment_method_data[card][exp_year]=${yyyy}
&payment_method_data[card][cvc]=${cvv}
&description=Order%201001
The Card Vault proxy request
$ENIGMA_TOKEN is your Enigma Vault access token and $CARD_TOKEN the stored card's token. The quoted EOF keeps your shell from touching the ${...} placeholders.
curl -X POST https://api.enigmavault.io/cardvault/proxy \
-H "Authorization: Bearer $ENIGMA_TOKEN" \
-H "x-api-version: 1.14" \
-H "cardToken: $CARD_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @- <<'EOF'
{
"url": "https://api.stripe.com/v1/payment_intents",
"httpMethod": "POST",
"headers": [
{
"name": "Authorization",
"value": "Bearer YOUR_SECRET_KEY"
},
{
"name": "Content-Type",
"value": "application/x-www-form-urlencoded"
},
{
"name": "Idempotency-Key",
"value": "order-1001"
}
],
"body": "amount=1000¤cy=usd&confirm=true&payment_method_types[]=card&payment_method_data[type]=card&payment_method_data[card][number]=${ccn}&payment_method_data[card][exp_month]=${mm}&payment_method_data[card][exp_year]=${yyyy}&payment_method_data[card][cvc]=${cvv}&description=Order%201001"
}
EOF
Reading the reply
The proxy answers 200 with statusCode, contentType, headers and body from Stripe. The proxy response's statusCode is Stripe's: 200 with "status": "succeeded" in the JSON body is a completed charge. "status": "requires_action" means the card needs 3D Secure authentication by the cardholder, which a server-side request cannot complete. A decline is a 402 whose error.decline_code says why.
Save a stored card to a Stripe customer (SetupIntent)
Attaches the card to an existing Stripe customer as a PaymentMethod you can charge later with off_session=true, for example when you move cards from Card Vault into Stripe. Replace cus_... with your customer's ID.
What Stripe receives
POST https://api.stripe.com/v1/setup_intents, with this body (laid out for reading; the request sends it as one line):
customer=cus_...
&confirm=true
&usage=off_session
&payment_method_types[]=card
&payment_method_data[type]=card
&payment_method_data[card][number]=${ccn}
&payment_method_data[card][exp_month]=${mm}
&payment_method_data[card][exp_year]=${yyyy}
&payment_method_data[card][cvc]=${cvv}
The Card Vault proxy request
$ENIGMA_TOKEN is your Enigma Vault access token and $CARD_TOKEN the stored card's token. The quoted EOF keeps your shell from touching the ${...} placeholders.
curl -X POST https://api.enigmavault.io/cardvault/proxy \
-H "Authorization: Bearer $ENIGMA_TOKEN" \
-H "x-api-version: 1.14" \
-H "cardToken: $CARD_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @- <<'EOF'
{
"url": "https://api.stripe.com/v1/setup_intents",
"httpMethod": "POST",
"headers": [
{
"name": "Authorization",
"value": "Bearer YOUR_SECRET_KEY"
},
{
"name": "Content-Type",
"value": "application/x-www-form-urlencoded"
},
{
"name": "Idempotency-Key",
"value": "order-1001"
}
],
"body": "customer=cus_...&confirm=true&usage=off_session&payment_method_types[]=card&payment_method_data[type]=card&payment_method_data[card][number]=${ccn}&payment_method_data[card][exp_month]=${mm}&payment_method_data[card][exp_year]=${yyyy}&payment_method_data[card][cvc]=${cvv}"
}
EOF
Reading the reply
The proxy answers 200 with statusCode, contentType, headers and body from Stripe. "status": "succeeded" in the JSON body means the card is saved; its ID is in payment_method.
Things to know
- No CVC. For a repeat charge after the CVV has expired, leave out
payment_method_data[card][cvc]. Sending${cvv}with no CVV stored sends an empty value, which Stripe refuses. - Expiry.
${mm}is the two-digit month and${yyyy}the four-digit year, which Stripe accepts as they are. - Cardholder name. To send it, add
payment_method_data[billing_details][name]=with your own URL-encoded value. Card Vault inserts${fullName}exactly as stored, without URL encoding, so a name with a space or&would break the form body. - Merchant-initiated charges. For a charge the cardholder is not present for, add
off_session=true; Stripe then declines rather than asking for authentication.
See also all connectors, the API reference for POST /cardvault/proxy, and the proxy's addresses. Questions: support@enigmavault.io.