How it works
Shift4's charges API at api.shift4.com takes form-encoded requests authorized with your secret key. You build the charge 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 Shift4 and returns Shift4's reply unchanged.
Test and live charges use the same host: your key decides which one the request runs in. This recipe is for the charges API at api.shift4.com, not Shift4's separate payments platform API.
Before you start
- A Shift4 secret key (
sk_test_...orsk_live_...). Shift4 takes it as the user name of HTTP basic authentication with an empty password, which is theAuthorizationheader below:Basicfollowed by the base64 of your key and a colon. - 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.shift4.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
Charges the amount and captures it. amount is in the currency's smallest unit (1000 is $10.00). Add captured=false to authorize only and capture later.
What Shift4 receives
POST https://api.shift4.com/charges, with this body (laid out for reading; the request sends it as one line):
amount=1000
¤cy=USD
&description=Order%201001
&card[number]=${ccn}
&card[expMonth]=${mm}
&card[expYear]=${yyyy}
&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.shift4.com/charges",
"httpMethod": "POST",
"headers": [
{
"name": "Authorization",
"value": "Basic BASE64_OF_YOUR_SECRET_KEY_AND_COLON"
},
{
"name": "Content-Type",
"value": "application/x-www-form-urlencoded"
}
],
"body": "amount=1000¤cy=USD&description=Order%201001&card[number]=${ccn}&card[expMonth]=${mm}&card[expYear]=${yyyy}&card[cvc]=${cvv}"
}
EOF
Reading the reply
The proxy answers 200 with statusCode, contentType, headers and body from Shift4. 200 with "status": "successful" in the JSON body is a completed charge; keep its id for refunds. A decline comes back as an error with "type": "card_error" and a code such as card_declined.
Things to know
- Repeat charges. Shift4 requires
card[cvc]whenever you send a card number, so a charge through the proxy needs the CVV while Card Vault still holds it. For later charges, save the card to a Shift4 customer on the first charge (addcustomerId) and charge that customer's card ID afterwards withtype=merchant_initiatedorsubsequent_recurring; those requests carry no card data, so send them to Shift4 directly. - Expiry.
${mm}is the two-digit month and${yyyy}the four-digit year. - Cardholder name. To send it, add
card[cardholderName]=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.
See also all connectors, the API reference for POST /cardvault/proxy, and the proxy's addresses. Questions: support@enigmavault.io.