Shopper Purchase With Vault Id
This section explains how a shopper can make a purchase using a Vault Id.
PayPal's JavaScript SDK and Buttons
During the purchase, use the Customer Id generated by the Vault Id creation and saved to our webstore wallet to call the OAuth Token API shown below. This API returns an id-token, id-token must be passed while loading the SDK below.
Request Details
| Action | URI Template | URI Example | Content Type | Request Headers | Request Parameters | Response Sample |
|---|---|---|---|---|---|---|
| GET | https://paypal-host/v1/oauth2/token> | https://api-m.sandbox.paypal.com/v1/oauth2/token | application/x-www-form-urlencoded | Content-Type: application/x-www-form-urlencoded, Authorization: AUTHORIZATION-TOKEN' | grant_type=client_credentials, response_type=id_token, target_customer_id=customer-id-generated-by-create-vault-api | { "scope": "https://uri.paypal.com/services/checkout/one-click-with-merchant-issued-token", "access_token": "A21AAI9wtWIhcPP7qrQiq_zsYX07qLtqHDC0mBeNceIJyEvBlXcgxHMpzg6sW0ugjDbXs11DRCoHxw5uuYuo6btCbhj7p-xUg", "token_type": "Bearer", "app_id": "APP-80W284485P519543T", "expires_in": 32400, "id_token": "eyJraWQiOiJhMDRiMjEwZDYzYjU0NWQzODEwOWUxNDM", "nonce": "2025-05-05T03:09:51ZovMVmHtv7PchAvNXn-5N8k3ORkQkWA87_R3GAMRGHXM" } |
Find the curl Command below
Copy
curl --location 'https://api-m.sandbox.paypal.com/v1/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: AUTHORIZATION-TOKEN' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'response_type=id_token' \
--data-urlencode 'target_customer_id=customer-id-generated-by-create-vault-api'
Load the SDK
The SDK URL below loads the Vault UI
Copy
<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&intent=authorize&commit=false&data-user-id-token=%22id_token from-token-response%22"></script>
Final stage the UI appears as shown below.
In this flow, Shopper also has following options while paying with Vault Id.
Lifecycle Diagram
Similar to the Vault Creation Without a Purchase APIs, first create the Vault Id and Customer Id. During the shopper purchase, pass the Customer Id and Vault Id in the regular Payment Authorization Using Vault Id API, as explained below.
This is the final API call in the PayPal checkout flow, and it is used to finally authorize the payment.If the ResponseCode from the API response is Success then the Order has been placed successfully and the PayPal checkout flow is complete.
URI Description
| Action | URI Template | URI Example | Request Content Type | Response Content Type |
|---|---|---|---|---|
| POST | /vM.m/stores/{StoreID}/payments/authorization/create/{tenderType}.json | /v1.0/stores/TMSUS/payments/authorization/create/PY.json | application/json | application/json |
Request Elements
| Element | Required | Description | Type | Restriction |
|---|---|---|---|---|
| createTimestamp | Yes | Timestamp when the request is sent | String | dateTime |
| orderInformation | Yes | Information about the order which is the unique identifier of an order. | ObjectType | |
| orderInformation.orderId | Yes | Unique identifier for an order. | String | Min 3 char Max 40 characters |
| orderInformation.softDescriptor | Yes | Merchants to pass their soft description to be displayed on the shoppers bank statement, generally business name in short form. | String | Min 1 characters Max 130 characters |
| paymentMethod | Yes | Unique identifier of the payment transaction for the order. | ObjectType | |
| paymentMethod.payPalVaultData | Yes | Payment Information of the PayPal. | ObjectType | |
| paymentMethod.payPalVaultData.id | Yes | PayPal Vault Id is created through the PayPal Vault Id Create With Purchase . | String | Min 4 characters |
| paymentMethod.payPalVaultData.customerId | No | PayPal customer id through the PayPal Vault Id Create With Purchase . | String | Min 4 characters |
| amounts | Yes | Amount value and currency code of the order | ObjectType | |
| amounts.total | Yes | Total amount value and currency code of the order | ObjectType | |
| amounts.total.currencyCode | Yes | The currency of the order amount | ISO 4217 currency code | |
| amounts.total.value | Yes | Total value of the authorization. | Decimal | Min 0.00 Max 9 digits Fraction 2 digits |
| billingInformation | Yes | Represents Billing Information of the order. Contains Shopper's Contact Information and Address. | ObjectType | |
| billingInformation.address | Yes | Represents Shopper's billing address information. | ObjectType | |
| billingInformation.address.line1 | Yes | The line1 components contain the street address. | String | Min 1 character Max 70 characters |
| billingInformation.address.city | Yes | City of the Billing Address. | String | Min 1 character Max 40 characters |
| billingInformation.address.mainDivision | Yes | Typically, a two- or three-digit postal abbreviation for the state or province. | ObjectType | |
| billingInformation.address.mainDivision.code | Yes | Typically, a two- or three-digit postal abbreviation for the state or province. This does not necessarily conform to the ISO 3166-2 code. | String | Min 1 character Max 5 characters |
| billingInformation.address.country | Yes | Two-digit ISO country code conforming to ISO 3166 alpha 2. See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 | String | |
| billingInformation.address.postalCode | Yes | Postal code of the Billing Address. | String | Min 1 character Max 35 characters |
| billingInformation.contact | Yes | Represents Shopper's billing contact information. | ObjectType | |
| billingInformation.contact.person | Yes | Represents Shopper billing contact person information. | ObjectType | |
| billingInformation.contact.person.name | Yes | Represents Shopper billing contact person name information. | ObjectType | |
| billingInformation.contact.person.name.firstName | Yes | The first name of the Shopper placing the order. | String | Min 1 Character Max 64 characters |
| billingInformation.contact.person.name.lastName | Yes | The last name of the Shopper placing the order. | String | Min 1 Character Max 64 characters |
| billingInformation.contact.emailAddresses | Yes | Email address of the Shopper. | Array of String | Min 3 characters Max 150 characters |
| billingInformation.contact.phoneNumbers | Yes | Shopper phone number used for order follow-up. | Array of String | Min 10 characters Max 40 characters |
| shippingInformation | Yes | Represents Shipping Information of the order. Contains Shopper Contact Information and Address. | ObjectType | |
| shippingInformation.address | Yes | Represents Shopper shipping address information. | ObjectType | |
| shippingInformation.address.line1 | Yes | The line1 components contain the street address. | String | Min 1 character Max 70 characters |
| shippingInformation.contact.phoneNumbers | Yes | Shopper phone number used for order follow-up. | String | Min 10 characters Max 40 characters |
| shippingInformation.address.city | Yes | City of the Shipping Address. | String | Min 1 character Max 40 characters |
| shippingInformation.address.mainDivision | Yes | Typically, a two- or three-digit postal abbreviation for the state or province. | ObjectType | |
| shippingInformation.address.mainDivision.code | Yes | Typically, a two- or three-digit postal abbreviation for the state or province. This does not necessarily conform to the ISO 3166-2 code. | String | Min 1 character Max 5 characters |
| shippingInformation.address.country | Yes | Two-digit ISO country code conforming to ISO 3166 alpha 2. See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 | String | |
| shippingInformation.address.postalCode | Yes | Postal code of the Shipping Address. | String | Min 1 character Max 35 characters |
| shippingInformation.contact | Yes | Represents Shopper shippingInformation contact information. | ObjectType | |
| shippingInformation.contact.person | Yes | Represents Shopper shippingInformation contact person information. | ObjectType | |
| shippingInformation.contact.person.name | Yes | Represents Shopper shippingInformation contact person name information. | ObjectType | |
| shippingInformation.contact.person.name.firstName | Yes | The first name of the Shopper placing the order. | String | Min 1 Character Max 64 characters |
| shippingInformation.contact.person.name.lastName | Yes | The last name of the Shopper placing the order. | String | Min 1 Character Max 64 characters |
| shippingInformation.contact.emailAddresses | Yes | Email address of the Shopper. | Array of String | Min 3 characters Max 150 characters |
| processingOptions | No | Processing options. | ObjectType | |
| processingOptions.authorizationMode | No | Processing option for the shipment. | Enum | In the shopper purchase with Vault Id use case, processingOptions object is not required. |
Request Example
Payment Authorization request with Vault Id and Customer Id.
Copy
{
"orderInformation": {
"orderId": "365",
"softDescriptor": "Paypal*Amazon*5699 $40.00"
},
"requestId": "PAYAU541501814",
"createTimestamp": "2025-04-02T09:29:13Z",
"paymentMethod": {
"payPalVaultData": {
"id": "7c282279pb3649525",
"customerId": "92279uy36497"
}
},
"amounts": {
"total": {
"currencyCode": "USD",
"value": 45
}
},
"billingInformation": {
"address": {
"city": "King of Prussia",
"country": "US",
"line1": "935 First Ave",
"mainDivision": {
"code": "PA"
},
"postalCode": "19406"
},
"contact": {
"emailAddresses": [
"testtest@gmail.com"
],
"person": {
"name": {
"firstName": "Test",
"lastName": "Tester"
}
},
"phoneNumbers": [
"9876543120"
]
}
}
}
For details of the API request and response, see PayPal Payment Authorization Using Vault Id.