Vault overview

Use the Vault API to securely store customer credit cards in the PayPal vault rather than on your server.

When you use the API to store a customer credit card, the API returns the ID of the vaulted card. To take a payment with the vaulted card, you specify the ID of the vaulted card instead of credit card details.

Notes:

  • PayPal does not validate credit card information that you store in the vault.

  • Some countries restrict direct credit card payments and related features.

Integration steps

To store a credit card in the vault and pay with a vaulted credit card:

1. Required Meet the prerequisites.
2. Required Store credit card in the vault.
3. Required Pay with vaulted card.
4. Optional Delete vaulted card.

Prerequisites

Before you can use the Vault API, you must make your first call and learn about REST API authentication and headers. If you are a non-US developer, see International Developer Questions.

Important: The following requests are samples that you cannot run as-is. Replace all call-specific parameter values, such as tokens and IDs, with your own values.

Store credit card in the vault

When you store a credit card in the PayPal vault, include the credit card details in the JSON request body. To help distinguish this credit card from others and prevent potential misuse of the card, include a unique external_customer_id in the request:

curl -v -X POST https://api.sandbox.paypal.com/v1/vault/credit-cards/ \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "number":"4417119669820331",
  "type":"visa",
  "expire_month":11,
  "expire_year":2018,
  "cvv2":"874",
  "first_name":"Joe",
  "last_name":"Shopper",
  "billing_address":{
    "line1":"52 N Main St",
    "city":"Johnstown",
    "country_code":"US",
    "postal_code":"43210",
    "state":"OH",
    "phone":"408-334-8890"
  },
  "external_customer_id":"joe_shopper408-334-8890"
}'

The response returns 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-1SW33690TH184423CKM2ZMVY",
  "state":"ok",
  "type":"visa",
  "number":"4417119669820331",
  "expire_month":11,
  "expire_year":2018,
  "first_name":"Joe",
  "last_name":"Shopper",
  "billing_address":{
    "line1":"52 N Main St",
    "city":"Johnstown",
    "state":"OH",
    "postal_code":"43210",
    "country_code":"US",
    "phone":"408-334-8890"
  },
  "external_customer_id":"joe_shopper408-334-8890",
  "valid_until":"2017-03-27T00:00:00Z",
  "create_time":"2017-03-28T15:33:43Z",
  "update_time":"2017-03-28T15:33:43Z",
  "links":[
    {
      "href":"https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-1SW33690TH184423CKM2ZMVY",
      "rel":"self",
      "method":"GET"
    },
    {
      "href":"https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-1SW33690TH184423CKM2ZMVY",
      "rel":"delete",
      "method":"DELETE"
    },
    {
      "href":"https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-1SW33690TH184423CKM2ZMVY",
      "rel":"patch",
      "method":"PATCH"
    }
  ]
}

Next, pay with the vaulted card.

Pay with vaulted card

To pay with a vaulted card, include the id returned in the store credit card response as the credit card ID in a create payment call.

Instead of passing a credit_card object in the funding_instrument as you would for a standard credit card payment, you pass a credit_card_token object.

Include these parameters in the credit_card_token object:

Parameter Description
credit_card_id The id that was returned in the store credit card response.
external_customer_id If you included a external_customer_id when you stored the credit card, include that same ID in this request.
curl -v https://api.sandbox.paypal.com/v1/payments/payment \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "id":"CPPAY-13U467758H032001PKPIFQZI",
  "intent":"sale",
  "payer":{
    "payment_method":"credit_card",
    "funding_instruments":[
      {
        "credit_card_token":{
          "credit_card_id":"CARD-1MD19612EW4364010KGFNJQI",
          "external_customer_id":"joe_shopper408-334-8890"
        }
      }
    ]
  },
  "transactions":[
    {
      "amount":{
        "total":"6.70",
        "currency":"USD"
      },
      "description":"Payment by vaulted credit card."
    }
  ]
}'

The response shows the payment details:

{
  "id":"CPPAY-13U467758H032001PKPIFQZI",
  "create_time":"2017-07-23T21:49:52.052Z",
  "update_time":"2017-07-23T21:49:53.053Z",
  "state":"created",
  "intent":"sale",
  "payer":{
    "payment_method":"credit_card",
    "funding_instruments":[
      {
        "credit_card_token":{
          "credit_card_id":"CARD-1MD19612EW4364010KGFNJQI",
          "external_customer_id":"joe_shopper408-334-8890"
        }
      }
    ]
  },
  "transactions":[
    {
      "amount":{
        "total":"6.70",
        "currency":"USD"
      },
      "description":"Payment by vaulted credit card.",
      "related_resources":[
        {
          "sale":{
            "id":"CP-6213590091777521231461232211",
            "create_time":"2017-07-23T21:49:52.052Z",
            "update_time":"2017-07-23T21:49:53.053Z",
            "state":"completed",
            "amount":{
              "total":"0.01",
              "currency":"GBP"
            },
            "parent_payment":"CPPAY-9CD04042CX382792NKPIJA3Q",
            "links":[
              {
                "href":"https://api.sandbox.paypal.com/v1/payments/sale/CP-6213590091777521231461232211",
                "rel":"self",
                "method":"GET"
              },
              {
                "href":"https://api.sandbox.paypal.com/v1/payments/payment/CP-6213590091777521231461232211",
                "rel":"refund",
                "method":"GET"
              },
              {
                "href":"https://api.sandbox.paypal.com/v1/payments/refund/CPPAY-9CD04042CX382792NKPIJA3Q",
                "rel":"parent_payment",
                "method":"GET"
              }
            ]
          }
        }
      ]
    }
  ],
  "links":[
    {
      "href":"https://api.sandbox.paypal.com/v1/payments/payment/CPPAY-9CD04042CX382792NKPIJA3Q",
      "rel":"self",
      "method":"GET"
    }
  ]
}

Next, you can optionally delete the vaulted card.

Delete vaulted card

To delete a vaulted card, specify the ID of the vaulted card in the request:

curl -v -X DELETE https://api.sandbox.paypal.com/v1/vault/credit-cards/CARD-54E6956910402550WKGRL6EA \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

A successful calls returns the HTTP 204 No Content status code.

Next

You can list vaulted credit cards, show vaulted credit card details, and update vaulted credit card.

Additional information