PayPal Vault

PayPal Vault is a feature merchants can use for subscription payments, when the shopper is not present, and for adding PayPal to their wallet feature in their webstore to facilitate faster checkouts for their shoppers using PayPal.

The Vault feature securely stores payment details for future use. When shoppers save their PayPal payment details, a Vault Id is generated. This Vault Id is stored in the merchants wallet on the webstore. The next time a shopper checks out, they can use the Vault Id to complete the transaction. without having to log in to PayPal again.

The Vault Id can be used for merchants to initiate subscription payments and other use cases for managing transactions when the shopper is not present.

At this time, the Vault feature is not compatible with Venmo.

PayPal Vault Flow, Creation and Usage

PayPal Vault usage conceptionally can be considerd as a two step process. First the a Vault Id is requested as part of a purchase transaction or when the Shopper wants to save the PayPal payment method in the webstore's wallet (without purchase). The second step is when the Vault Id is used to complete a transaction. For a Shopper, this could be the next time they check out. For a Merchant, this could be when a subscription payment is due.

The PayPal Vault flow, for the most part, does not require changing the overall transaction flow for a normal PayPal transaction. This means that Merchants will continue to utilize:

  1. SetExpress

  2. DoExpress

  3. DoAuthorization

  4. DoCapture

As detailed below, the changes are in the elements in the requests themselves.

PayPal Vault Benefits

In summary, the benefits of using PayPal Vault are:

  1. Faster checkouts for repeat shoppers.

  2. Enabling subscription payments - when the shopper is not present.

  3. Increases conversion rates by simplifying the payment flow.

The sections below will outline how to enable and use Vault-based payments for the following use-cases.

Vault Id Creation Without Purchase

Shopper wishes to have a faster checkout experience and saves their PayPal payment method to the merchant's webstore wallet.

Shopper Purchase With Vault Id

Once a shopper has saved their PayPal payment method to the merchant's webstore wallet they can use the Vault Id to complete a purchase.

The flow and details of enabling a Shopper Purchase with Vault are detailed Shopper Purchase With Vault Id

Vault Creation With Purchase

A Merchant interested in using the Vault feature for subscription payments can create a Vault Id as part of a purchase transaction. Again, it is a two step process:

  1. Merchant requests a Vault Id with a Shopper initiated purchase.

  2. Merchant uses the Vault Id to complete a subscription payment.

Subscription Payment With Vault Id

After a Merchant has created a Vault Id as part of a purchase, the Merchant can use the Vault Id to complete a subscription payment.

PayPal Vault Id Creation Without Purchase

A request to create a PayPal Vault Id without a purchase is illustrated below:

Lifecycle Diagram

To achieve this, two API calls are required:

  1. SetExpress
  2. PayPal Vault Creation API Call

SetExpress Call For Vault Id Creation Without Purchase

For details of the SetExpress XML request and response specific to Vault Id creation, see PayPal SetExpress For Vault Id Creation Without Purchase.

Vault Id Creation With Purchase

Vault Id is created along with purchase, by Shopper and the Vault Id is saved to the Merchant's subscription engine.

A request to create a PayPal Vault Id with a purchase is illustrated below:

To achieve this, these API calls are required:

  • SetExpress
    • Set Recurring is true
    • Set Amount is greater than 0.00
  • GetExpress
  • DoExpress
  • DoAuthorization
    • Returns Vault Id and Customer Id.

For details of the API request and response specific to Vault Id creation with a purchase, see PayPal SetExpress For Vault Id Creation With Purchase.

Subscription Payment with Vault Id

The Request refers the Vault created though With Purchase API, the Merchant can make purchases by passing the Vault Id in the request using the PayPal Payment Authorization with Vault API.

Initiated by Merchant’s Subscription Engine.

Lifecycle Diagram

The flow and details of enabling a subscription Purchase with Vault are detailed Subscription Purchase with Vault

Payment Capture Flows

There are two methods for capturing the funds from a transaction. The first is Post-Authorization Capture and the second is Auto-Capture. The primary difference is timing.

Post-Authorization Capture Flow

In the Post-Authorization Capture Flow, payment is first authorized and captured separately at a later stage, typically when the order is ready for fulfillment. This method provides flexibility for Merchants, allowing them to verify inventory, prevent fraud, or handle order modifications before capturing funds.

Post-Authorization Capture is the default capture flow for Radial Payment APIs. This means that specifying the authorizationMode in the authorization request is optional. For details of the PayPal Payment Authorization using Vault request and response, see PayPal Payment Authorization Using Vault Id.

Auto-Capture Flow

In Auto-Capture (Pre-Capture) Flow, the payment is captured immediately upon authorization, eliminating the need for a separate capture call.

Merchants must specify the authorization mode is Auto Capture by passing authorizationMode = AUTO_CAPTURE in the authorization request.

In addition, Merchants must ensure that intent is set as capture in SDK URL.

Example for SDK URL

https://api.radial.com/v1/payments/paypal/vault/authorize?intent=capture&commit=false

For details of the PayPal Payment Authorization using Vault request and response, see PayPal Payment Authorization Using Vault Id.

Deleting a PayPal Vault Id

If a Vault Id is no longer needed, the Merchant can delete it using the Payment Method Delete API call.

Vault Id Deleted Webhook Subscription

Once the Vault Id is deleted, a deletion notification will be sent to the Merchant via the topic or webhook.

Radial will either provide the topic or collect the webhook URL from the Merchant. The Merchant can then choose to subscribe to the topic or register their webhook URL with Radial.

If Merchant prefers to enable the feature, refer to the Event Bridge Webhook Subscription API call.