PayPal Vault

Vaulting lets you securely store a customer's PayPal wallet so that future payments can be processed without requiring the customer to log into PayPal again. This is ideal for repeat customers and subscription-style flows.

📘
Customer Consent Required
Your customer must explicitly agree to the vaulting terms when approving the PayPal Order. Without that agreement, a vaultId will not be returned and the wallet will not be saved.

Step 1 — Vault the Wallet

To vault a wallet, create a PayPal Order via /v1/paypal/orders with "vault": true added to the request body. Everything else follows the standard create order flow.

Request

{
  "amount": 1001,
  "currencyCode": "GBP",
  "displayName": "Brand Name",
  "intent": "capture",
  "customerOrderCode": "ABC123",
  "locale": "en-US",
  "invoiceId": "{{$guid}}",
  "enableShippingAddress": true,
  "shippingAddressEditable": false,
  "vault": true,
  "returnUrl": "https://www.example.com/return",
  "cancelUrl": "https://www.example.com/cancel",
  "shippingAddressOverride": {
    "address1": "Line 1",
    "address2": "Line 2",
    "town": "Edinburgh",
    "county": "State",
    "postcode": "EH10 8E1",
    "country": "GB",
    "phoneNumber": "4084396009",
    "recipientName": "John Doe",
    "buildingNumberOrName": "20"
  },
  "lineItems": [
    {
      "name": "T-Shirt",
      "description": "Blue T-Shirt",
      "quantity": 1,
      "unitAmount": 1000,
      "unitTax": 1
    }
  ],
  "customer": {
    "accountId": "GR9MNXKHQTBY8",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phoneNumber": "4084396009",
    "country": "GB",
    "creationTimestamp": "2024-12-09T19:14:55.277-0:00"
  }
}

The initial response will be the same as a standard PayPal create order response — you'll receive an orderId and redirectUrl. Redirect the customer to PayPal as normal.

Step 2 — Retrieve the Vault ID

The vaultId is returned on successful completion of the order's intent. For a capture intent, it appears in the capture response under psp.additionalInfo.paymentSource.

Capture Response (with vaultId)

{
  "code": "1000",
  "message": "Approved",
  "id": "691b0cf0252154ac56383ce42fdddb10",
  "paymentId": "1aa76e6a-15ba-4f46-a6e7-3080aba5a229",
  "orderId": "2NF630639H718704B",
  "status": "COMPLETED",
  "amount": 1001,
  "psp": {
    "name": "PayPal-Direct",
    "transactionId": "6EW22835YU8376810",
    "additionalInfo": {
      "type": "payPal",
      "paymentSource": {
        "name": "John Doe",
        "email": "[email protected]",
        "accountId": "BYENZRGXD228J",
        "vaultId": "0tb28273r6584005e"
      }
    }
  },
  "account": {
    "accountId": "BYENZRGXD228J"
  }
}

Store the vaultId securely against the customer's record in your system.

🚧
No vaultId in the Response?
If a vaultId is not returned after a successful authorize or capture, the customer did not complete the vaulting agreement during approval. You will need to prompt them to accept the agreement again on a future payment.

Step 3 — Pay with the Vault ID

For subsequent payments, pass the saved vaultId in a new create order request to /v1/paypal/orders. The customer will not need to log into PayPal.

📘
When the user is present in the subsequent payment flow you must support PayPal fraudnet.

All subsequent PayPal payments using a Vault ID are processed as direct captures. Split authorisation & capture is not supported on the subsequent payment using a Vault ID.

Request

{
  "amount": 1001,
  "currencyCode": "GBP",
  "displayName": "Brand Name",
  "intent": "capture",
  "customerOrderCode": "ABC123",
  "locale": "en-US",
  "invoiceId": "{{$guid}}",
  "enableShippingAddress": true,
  "shippingAddressEditable": false,
  "vaultId": "0tb28273r6584005e",
  "returnUrl": "https://www.example.com/return",
  "cancelUrl": "https://www.example.com/cancel",
  "customer": {
    "accountId": "GR9MNXKHQTBY8",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phoneNumber": "4084396009",
    "country": "GB",
    "creationTimestamp": "2024-12-09T19:14:55.277-0:00"
  }
}

Response

{
  "code": "1000",
  "message": "Approved",
  "id": "691b0d0e7d3a166312c45f5d732de421",
  "orderId": "90D935043S1840408",
  "status": "COMPLETED",
  "intent": "capture",
  "creationTimestamp": "2025-11-17T11:54:55Z",
  "psp": {
    "name": "PayPal-Direct",
    "transactionId": "06U72085DG203890L",
    "additionalInfo": {
      "type": "payPal",
      "paymentSource": {
        "name": "John Doe",
        "email": "[email protected]",
        "accountId": "BYENZRGXD228J"
      }
    }
  },
  "paymentId": "c0aae33a-ebcf-443a-9710-2e04ad1f5fcd"
}