Vault overview

The Vault API provides a secure way to store customer credit cards. By storing cards with PayPal, you can avoid storing them on your servers.

Support for direct payments with credit cards varies by country.

Using Vault

To store a customer credit card, specify the card details in a call to the Vault API. A card ID is returned. To take a payment with the card, specify the card ID (instead of specifying the credit card details). If you provided a payer ID when you stored the card, include the payer ID when you charge the card.

After you make your first call, you are ready to try out the Vault API. You also can look up or delete a card.

Store and use a customer credit card

Direct credit card payment and related features are restricted in some countries.

To avoid storing credit card details on your server, you can use the /vault/credit-card call to store a customer credit card with PayPal. You can then use a /payment call to complete the payment using the ID we provide to you.

  1. Store a credit card
  2. Use a stored credit card

Try It!: Store and use a credit card now using our interactive tool.

Store a credit card

First, store a credit card with a /vault/credit-card call. Include the credit card details in the body. Although not required, we recommend including a unique payer_id in the request. This will help distinguish this credit card from others and helps to prevent potential misuse of the card.


curl -v https://api.sandbox.paypal.com/v1/vault/credit-card \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer ' \
-d '{
 "payer_id":"user12345",
 "type":"visa",
 "number":"4417119669820331",
 "expire_month":"11",
 "expire_year":"2018",
 "first_name":"Joe",
 "last_name":"Shopper"
}'

Important: The sample requests in this guide are examples only and not runnable as-is. You should substitute all call-specific parameters, such as tokens and IDs, with your own.

We'll return a credit-card object with a credit card id and a valid_until expiration date. For security purposes, the credit card number is redacted in all responses.


{
  "id":"CARD-1MD19612EW4364010KGFNJQI",
  "valid_until":"2016-05-07T00:00:00Z",
  "state":"ok",
  "payer_id":"user12345",
  "type":"visa",
  "number":"xxxxxxxxxxxx0331",
  "expire_month":"11",
  "expire_year":"2018",
  "first_name":"Betsy",
  "last_name":"Buyer",
  "links":[
    {
      "href":"https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-1MD19612EW4364010KGFNJQI",
      "rel":"self",
      "method":"GET"
    },
    {
      "href":"https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-1MD19612EW4364010KGFNJQI",
      "rel":"delete",
      "method":"DELETE"
    }
  ]
}

Tip: You can delete a credit card once it is stored.

Use a stored credit card

To complete a payment using a stored card, include the id returned in the /vault/credit-card call as the credit_card_id in a /payment call. Notice that, instead of passing a credit_card in the funding_instrument as you would for a regular credit card payment, you're passing a credit_card_token. If you included a payer_id when you stored the credit card, you'll need to include that as well when using the stored credit card.


curl -v https://api.sandbox.paypal.com/v1/payments/payment \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer ' \
-d '{
  "intent":"sale",
  "payer":{
    "payment_method":"credit_card",
    "funding_instruments":[
      {
        "credit_card_token":{
          "credit_card_id":"CARD-1MD19612EW4364010KGFNJQI",
          "payer_id":"ppuser12345"
        }
      }
    ]
  },
  "transactions":[
    {
      "amount":{
        "total":"6.70",
        "currency":"USD"
      },
      "description":"This is the payment transaction description."
    }
  ]
}'

Note: If you want to handle credit card details on your own server, you can directly pass details to PayPal using the payment call along with a credit-card object.

Note: PayPal currently does not validate credit card information that is stored using the /vault/credit-card call.

More Vault information

References and other resources for the Vault API are available at the following locations: