Card Vault connector

PayPal.

Charge a card stored in Card Vault through PayPal's Orders API, without the card number touching your servers.

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/token with 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 to api-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 (and api-m.sandbox.paypal.com for 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 add stored_credential to the card as PayPal documents for merchant-initiated payments.
  • Expiry. ${yyyy}-${mm} becomes the YYYY-MM date PayPal expects, for example 2030-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.