APIs for Vault Id Creation Without a Purchase
SetExpress for Vault Id Creation
As mentioned for most part management of PayPal Vault Id transactions (creation and payment) utilize the same API calls as a regular PayPal transction. To review the regular SetExpress API details see PayPal SetExpress
The specific use-case for a Vault Id Creation request with out a purchase is for shoppers to save the PayPal payment method to a webstore wallet.
URI Description
| Action | URI Template | URI Example | Request Content Type | Response Content Type |
|---|---|---|---|---|
| POST | /vM.m/stores/{StoreID}/payments/paypal/setExpress.xml | /v1.0/stores/TMSUS/payments/paypal/setExpress.xml | application/xml or text/xml | application/xml or text/xml |
Request Elements
When preparing the request, consider the following data notes:
- Negative Line Items Amounts are allowed in order to apply discounts, and LineItemsTotal is also allowed to have a negative value. However, the request Amount, which equals the sum of LineItemsTotal + ShippingTotal + TaxTotal, cannot be negative.
- AddressOverride must be set to 0 if the user chooses Express checkout, or 1 if the user chooses Standard checkout.
PayPal Vault Id Without Purchase Specific Elements
Since Merchants are initiating a Vault Id transaction without a purchase, set the Recurring field to true and the amount in the SetExpress request to 0.
Optionally, set the AutoCapture flag to false, based on Merchant's requirements.
Let PayPal generate the Customer Id automatically.
Radial Payments will respond to this request with an ApprovalUrl. This url is generated by PayPal and is unique for each PayPal Vault Id request. The purpose is to direct the shopper to login and approve the Vault Id creation.
| Element | Required | Description | Type | Restriction |
|---|---|---|---|---|
| StoreId | Yes | Store identifier used in the URL. | String | 20 Characters |
| OrderId | Yes | Order identifier. | String | 20 Characters |
| ReturnUrl | Yes | URL to which the customer's browser is returned after choosing to pay with PayPal. | String | Cannot be empty. (Minimum of 1 character) |
| CancelUrl | Yes | URL to which the customer is returned if the customer does not approve the use of PayPal. | String | Cannot be empty. (Minimum of 1 character) |
| LocaleCode | Yes | Locale code for the user's language in combination with a country. | String | Cannot be empty. (Minimum of 1 character). Example: en_US |
| Amount | Yes | For a creation of a Vault Id without a purchase the amount is 0.00 | Decimal | 2 precision points. (123.34) |
| Amount/ @currencyCode |
Yes | Type of currency used for the order | String | 3-character ISO 4217 code (for example, USD, CAD, EUR). See
http://en.wikipedia.org/ wiki/ISO_4217. |
| AddressOverride | No | Identifies Express Checkout (set to 0) or Standard Checkout (set to 1). | String | 0, 1 |
| NoShippingAddressDisplay | No | Hides shipping address on PayPal checkout review page when set to 1. Shows the shipping address when set to 0 or when not specified. When set to 2 will display the shipping address. If the shipping address is not provided it will be obtained from the buyer's account information. | String | 0, 1, 2 |
| ShipToName | No | The name of the person shipped to | String | 128 Characters |
| ShippingAddress | No | Address the order will be shipped to. | Complex Type | Includes: Line1, Line2, Line3, Line4, City, MainDivision, CountryCode, PostalCode |
| ShippingAddress/ Line1 |
Yes | Line 1 of the address. | String | Between 1 and 70 Characters. |
| ShippingAddress/ Line2 |
No | Line 2 of the address. | String | Between 1 and 70 Characters. |
| ShippingAddress/ Line3 |
No | Line 3 of the address. | String | Between 1 and 70 Characters. |
| ShippingAddress/ Line4 |
No | Line 4 of the address. | String | Between 1 and 70 Characters. |
| ShippingAddress/ City |
Yes | City the order will be shipped to. | String | Between 1 and 40 Characters. |
| ShippingAddress/ MainDivision |
No | This is the State/Province name | String | Between 1 and 35 Characters. Use of the ISO 3166-2 code is recommended but not required. |
| ShippingAddress/ CountryCode |
Yes | Country the order will be shipped to. | String | 2 Characters. Two digit ISO 3166 alpha 2 code country code. See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. |
| ShippingAddress/ PostalCode |
No | Postal Code the order will be shipped to. | String | Between 1 and 15 Characters. |
| ShippingOptions | No | Shipping options provided for the customer to choose | Complex Type | Includes: ShippingId and multiple ShippingOption (Applicable for PayPal Version 2 only) |
| ShippingOptions/ ShippingId |
No | It represents the shipping option that the payee or merchant expects to be pre-selected for the payer when they first view the shipping | String | Between 1 and 127 Characters |
| ShippingOption | No | Represent a single shipping option | Complex Type | Includes: ShippingId, ShippingLabel, DeliveryOption and ShippingCost |
| ShippingOptions/ ShippingId |
No | A unique ID that identifies a payer-selected shipping option. | String | Between 1 and 127 Characters. |
| ShippingOptions/ ShippingLabel |
No | A description that the payer sees, which helps them choose an appropriate shipping option. For example, Free Shipping, USPS Priority Shipping, Expédition prioritaire USPS, or USPS yōuxiān fā huò. | String | Between 1 and 127 Characters. |
| ShippingOptions/ DeliveryOption |
No | The method by which the payer wants to get their items. SHIPPING or PICKUP | String | Between 1 and 15 Characters. |
| ShippingOptions/ ShippingCost |
No | The shipping cost for the selected option. | Decimal | 2 precision points. (123.34). |
| ShippingOptions/ @currencyCode |
No | Type of currency used for the order | String | 3-character ISO 4217 code (for example, USD, CAD, EUR). See
http://en.wikipedia.org/ wiki/ISO_4217. |
| LineItems | No | Represents the items in the Order. | Complex Type | Includes: LineItemsTotal, ShippingTotal, TaxTotal and multiple LineItem elements. |
| LineItems/ LineItemsTotal |
Yes | Total amount for all line items excluding shipping and tax. Calculated as: LineItemsTotal = (First-LineItem-Quantity * First-LineItem-Amount) + other line items. | Decimal | 2 precision points. (123.34). Negative is allowed. However, LineItemsTotal + ShippingTotal + TaxTotal cannot be negative. |
| LineItems/ ShippingTotal |
Yes | Total shipping amount for all line items. | Decimal | 2 precision points. (123.34). |
| LineItems/ TaxTotal |
Yes | Total tax amount for all line items. | Decimal | 2 precision points. (123.34). |
| LineItems/ LineItem |
No | Represents a single item on the order. | Complex Type | Includes: Name, SequenceNumber, Quantity, UnitAmount |
| LineItems/ LineItem/ Name |
Yes | Line item name. | String | No Restrictions. |
| LineItems/ LineItem/ SequenceNumber |
No | Sequence number of current line item in cart if available. | String | No Restrictions. |
| LineItems/ LineItem/ Quantity |
Yes | Quantity for this line item. | Int | No Restrictions. |
| LineItems/ LineItem/ UnitAmount |
Yes | Unit price amount for a line item. | Decimal | 2 precision points. (123.34). Negative is allowed. |
| Installment (deprecated with latest PayPal upgrade) | No | Indicates whether this payment will be made using PayPal's Credit installment payment. | Boolean | true/false |
| SolutionType (deprecated with latest PayPal upgrade) | No | Type of checkout flow.
|
Enum | Mark / Sole |
| SchemaVersion | Yes |
Although marked as optional in the the schema, this element needs to be passed at all times with a value of 1.1 or greater in order to receive elements like 'ErrorMessage', 'ShortErrorMessage', 'ErrorCode' in the Response message. |
String |
pattern = "([0-9]+\.)*[0-9]+". |
| Recurring | true |
Recurring is true to set up Vault Id for recurring payment, else it must be false. |
Boolean | true/false |
| AutoCapture | No |
If Merchant's payment is automatically captured immediately upon authorization, Enable the AutoCapture else Disable it. |
Boolean | true/false |
| CustomerId | No |
PayPal will automatically generate a Customer Id for the shopper. If Merchant's have a preferred Customer Id, they can pass it in the request. |
String | Between 1 and 22 Characters. |
| MerchantDescriptor | No |
Merchants to pass their soft description to be displayed on the shoppers PayPal statement, generally business name in short form. |
String | Min 1 characters Max 127 characters. |
SetExpress Request Message
The request is a PayPalSetExpressCheckoutRequest message.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PayPalSetExpressCheckoutRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<OrderId>11111123</OrderId>
<ReturnUrl>http://webstore.com/return</ReturnUrl>
<CancelUrl>http://webstore.com/cancel</CancelUrl>
<LocaleCode>en_US</LocaleCode>
<Amount currencyCode="USD">0.00</Amount>
<ShipToName>John Doe</ShipToName>
<ShippingAddress>
<Line1>630 Allendale Road</Line1>
<City>King of Prussia</City>
<MainDivision>PA</MainDivision>
<CountryCode>US</CountryCode>
<PostalCode>19406</PostalCode>
</ShippingAddress>
<ShippingOptions>
<ShippingId>SHIP_123</ShippingId>
<ShippingOption>
<ShippingId>SHIP_123</ShippingId>
<ShippingLabel>1-Day-Shipping</ShippingLabel>
<DeliveryOption>SHIPPING</DeliveryOption>
<ShippingCost currencyCode="USD">8.00</ShippingCost>
</ShippingOption>
<ShippingOption>
<ShippingId>SHIP_124</ShippingId>
<ShippingLabel>Free-Shipping</ShippingLabel>
<DeliveryOption>SHIPPING</DeliveryOption>
<ShippingCost currencyCode="USD">0.00</ShippingCost>
</ShippingOption>
<ShippingOption>
<ShippingId>SHIP_456</ShippingId>
<ShippingLabel>Pick up in Store</ShippingLabel>
<DeliveryOption>PICKUP</DeliveryOption>
<ShippingCost currencyCode="USD">0.00</ShippingCost>
</ShippingOption>
</ShippingOptions>
<Recurring>true</Recurring>
<SchemaVersion>1.2</SchemaVersion>
</PayPalSetExpressCheckoutRequest>
Response Elements
| Element | Required | Description | Type | Restriction |
|---|---|---|---|---|
| OrderId | Yes | Order identifier. | String | 20 Characters |
| ResponseCode | Yes | Response Code returned from Payment Service. | String | Success, Failure |
| Token | Yes | The timestamped token value that was returned by PayPalSetExpressCheckoutReply and passed on PayPalGetExpressCheckoutRequest. | String | Generated by PayPal |
| ApprovalUrl | Yes | This url is generated by PayPal and is unique for each PayPal Vault Id request. The purpose is to direct the shopper to login and approve the Vault Id creation. | String | Generated by PayPal |
| ErrorMessage | No | Full Error Description. | String | Present only when the ResponseCode is Failure and SchemaVersion in the Request is equal to or greater than 1.2. |
| ShortErrorMessage | No | Short Error Description. | String | Present only when the ResponseCode is Failure and SchemaVersion in the Request is equal to or greater than 1.2. |
| ErrorCode | No | Error code coming from PayPal. | String | Present only when the ResponseCode is Failure and SchemaVersion in the Request is equal to or greater than 1.2. |
Success Response Example
The response is a PayPalSetExpressCheckoutReply message for Vault Id Creation without purchase. Which has Approval URL.
<?xml version="1.0" encoding="UTF-8"?>
<PayPalSetExpressCheckoutReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<OrderId>12345</OrderId>
<ResponseCode>Success</ResponseCode>
<Token>EC-5YE59312K56892714</Token>
<ApprovalUrl>https://www.sandbox.paypal.com/agreements/approve?approval_session_id=0BG166119J8265422</ApprovalUrl>
</PayPalSetExpressCheckoutReply>
Funding Source Selection and Approval
Vault Id Creation API
After the shopper selects a funding source and approves the Vault Id Creation, the webstore will call the API to create the Vault Id.
Overview
The 'PayPal Vault Id Creation' API generates is the call that actually creates the Vault Id.
The response includes a payPalVaultData element, that contains the Vault Id and the merchant can store in their webstore wallet along with the customerid that was returned in the response to the Vault Id Creation request.
URI Description
| Action | URI Template | URI Example | Request Content Type | Response Content Type |
|---|---|---|---|---|
| POST | /vM.m/stores/{StoreID}/payments/payment-method/create/{tenderType}.json | /v1.0/stores/TMSUS/payments/payment-method/create/PY.json | application/json | application/json |
Request Elements
When preparing the request, consider the following data notes:
The request and response are JSON.
- In the request, the payPalVaultData element contains the token ID returned by the SetExpress API.
- Amount is always 0
| Element | Required | Description | Type | Restriction |
|---|---|---|---|---|
| createTimestamp | Required | Timestamp when the request is sent | String | dateTime |
| @requestId | Yes | RequestId is used to uniquely identify a request, including as part of idempotent duplicate request processing. The value must be unique. It is recommended to use a variant 4 UUID for the request ID. The same request ID should only be reused if a read timeout occurs when attempting to receive a response from the payment service, or the payment service responds with a fault response. In all other cases a new request ID must be sent for retried requests, including responses such as Fail, Timeout or PaymentProcessorTimeout. | String | 40 Characters |
| OrderInformation/ OrderId |
Yes | Order identifier. | String | minLength: 3, maxLength: 40 |
| Amount/ Total/ Value |
Yes | The value always be 0. | Decimal | 2 precision points. (123.34) |
| Amount/ Total/ CurrencyCode |
Yes | Preferred currency. | String | 3-character ISO 4217 code (for example, USD, CAD, EUR). See
http://en.wikipedia.org/ wiki/ISO_4217. |
| PaymentMethod/ PayPalVaultData/ Token |
Yes | Token from SetExpress response | String | 20 single-byte characters |
| PaymentMethod/ PayPalVaultData/ CustomerId |
No | Customer Id is used to link the Vault Ids Merchants can create their own - however, PayPal will create on for Merchants and send it in the response. | String | Between 1 and 22 Characters. |
Request Example
The request is JSON data.
{
"orderInformation": {
"orderId": "17032025-jo-PY-2"
},
"amounts": {
"total": {
"value": 0,
"currencyCode": "USD"
}
},
"paymentMethod": {
"payPalVaultData": {
"token": "393808972K310902T"
}
},
"requestId": "17020505-012",
"createTimestamp": "2025-02-14T05:06:48Z"
}
Success Response Example
The response is a JSON data.
{
"success" : true,
"requestId" : "17020505-012",
"result" : {
"responseCode" : "Success",
"responseCodeDescription" : "PayPal vault successfully created.",
"paymentMethod" : {
"tender" : "PY",
"tenderDescription" : "PayPal",
"payPalVaultData" : {
"id" : "3a169526pa987743f",
"customerId" : "pLGjyKxgzK"
}
}
}
}
For more details of the API request and response specific to PayPal Vault Creation, see PayPal Vault Creation
PayPaL Vault Data
The response includes the PayPal Vault Data for both the Vault Id - shown here as "id" : "3a169526pa987743f". The customerId is also returned as "customerId" : "pLGjyKxgzK". The customerId will be important for processing a transaction
Shopper Checkout With Vault id
The Vault Id and the Customer Id received from the vault create should be saved to the merchants wallet account.When the shopper returns to make a purchase this information will be used to create the vault experience on the checkout page for the shopper.
The flow and details of enabling a Shopper Checkout with Vault Id are detailed Shopper Checkout With Vault Id