How it works
PayPal charges a card when you create an order whose payment source is that card. You build the order 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 PayPal and returns PayPal's reply unchanged.
Before you start
- Card payments on your PayPal account. Taking card details through the API needs PayPal's advanced card payments (Expanded Checkout) on your business account, and PayPal requires you to be PCI DSS compliant for it. Enigma Vault's Attestation of Compliance is on the developer portal's Artifacts page on paid plans.
- A PayPal access token. Get it from
POST /v1/oauth2/tokenwith your REST app's client ID and secret; that call carries no card data, so make it directly, not through the proxy. Tokens last about nine hours. For testing, use a sandbox app; its requests go toapi-m.sandbox.paypal.com. - A card stored in Card Vault, and its token. To send the CVV, 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-m.paypal.com(andapi-m.sandbox.paypal.comfor testing).
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 (create order, intent CAPTURE)
Creates the order and captures the payment in one request. Change value and reference_id for each order, and send a new PayPal-Request-Id each time, so a retry after a timeout cannot charge twice.
What PayPal receives
POST https://api-m.paypal.com/v2/checkout/orders (testing: https://api-m.sandbox.paypal.com/v2/checkout/orders), with this body (laid out for reading; the request sends it as one line):
{
"intent": "CAPTURE",
"purchase_units": [
{
"reference_id": "order-1001",
"amount": {
"currency_code": "USD",
"value": "10.00"
}
}
],
"payment_source": {
"card": {
"number": "${ccn}",
"expiry": "${yyyy}-${mm}",
"security_code": "${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-m.paypal.com/v2/checkout/orders",
"httpMethod": "POST",
"headers": [
{
"name": "Authorization",
"value": "Bearer YOUR_ACCESS_TOKEN"
},
{
"name": "Content-Type",
"value": "application/json"
},
{
"name": "PayPal-Request-Id",
"value": "order-1001-attempt-1"
}
],
"body": "{\"intent\":\"CAPTURE\",\"purchase_units\":[{\"reference_id\":\"order-1001\",\"amount\":{\"currency_code\":\"USD\",\"value\":\"10.00\"}}],\"payment_source\":{\"card\":{\"number\":\"${ccn}\",\"expiry\":\"${yyyy}-${mm}\",\"security_code\":\"${cvv}\"}}}"
}
EOF
Reading the reply
The proxy answers 200 with statusCode, contentType, headers and body from PayPal. PayPal answers 201 with "status": "COMPLETED" when the card was charged; the capture's ID and result are under purchase_units[0].payments.captures. A capture whose status is DECLINED was declined; 422 means PayPal refused the request, with the reason in details.
Things to know
- No CVV. For a repeat charge after the CVV has expired, leave out
security_code, and addstored_credentialto the card as PayPal documents for merchant-initiated payments. - Expiry.
${yyyy}-${mm}becomes theYYYY-MMdate PayPal expects, for example2030-03. - Cardholder name. To send it, add
"name": "${fullName}"to the card. Card Vault inserts the name exactly as stored, without JSON escaping, so a name containing a quotation mark would break the body. - Authorize now, capture later. Use
"intent": "AUTHORIZE"instead; PayPal answers with the authorization, which you capture later with a call that carries no card data.
See also all connectors, the API reference for POST /cardvault/proxy, and the proxy's addresses. Questions: support@enigmavault.io.