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

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.

<script src="

Final stage the UI appears as shown below.

In this flow, Shopper also has following options while paying with Vault Id.

  • Change the Funding Source of the Vault
  • Pay using different PayPal Account

    • 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.

    { "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.