On this page
No Headings
A resource representing a request to vault PayPal Wallet.
objectdescriptionstring^.*$The description displayed to the consumer on the approval flow for a digital wallet, as well as on the merchant view of the payment token management experience. exp: PayPal.com.
usage_patternstring"IMMEDIATE", "DEFERRED", "RECURRING_PREPAID", "RECURRING_POSTPAID", "THRESHOLD_PREPAID", "THRESHOLD_POSTPAID", "UNSCHEDULED_POSTPAID", "UNSCHEDULED_PREPAID", "SUBSCRIPTION_PREPAID", "SUBSCRIPTION_POSTPAID", "INSTALLMENT_POSTPAID", "INSTALLMENT_PREPAID"^[0-9A-Z_]+$Expected business/charge model for the billing agreement.
shippingobjectThe shipping details.
nameobjectThe name of the party.
full_namestringWhen the party is a person, the party's full name.
email_addressstringppaas_common_email_address_v2^(?:[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[A-Za-z0-9-]*[A-Za-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])$The email address of the recipient of the shipped items, which may belong to either the payer, or an alternate contact, for delivery.
phone_numberobjectThe phone number, in its canonical international E.164 numbering plan format.
country_coderequiredstring^[0-9]{1,3}?$The country calling code (CC), in its canonical international E.164 numbering plan format. The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
national_numberrequiredstring^[0-9]{1,14}?$The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
typestring"SHIPPING", "PICKUP_IN_PERSON", "PICKUP_IN_STORE", "PICKUP_FROM_PERSON"^[0-9A-Z_]+$A classification for the method of purchase fulfillment (e.g shipping, in-store pickup, etc). Either type or options may be present, but not both.
addressobjectThe portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.
address_line_1stringThe first line of the address, such as number and street, for example, 173 Drury Lane. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address.
address_line_2stringThe second line of the address, for example, a suite or apartment number.
admin_area_2stringA city, town, or village. Smaller than admin_area_level_1.
admin_area_1stringThe highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example, CA and not California. Value, by country, is:
postal_codestringThe postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
country_coderequiredstringppaas_common_country_code_v2^([A-Z]{2}|C2)$The 2-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGBand notUKas used in the top-level domain names for that country. Use theC2country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
permit_multiple_payment_tokensbooleanfalseCreate multiple payment tokens for the same payer, merchant/platform combination. Use this when the customer has not logged in at merchant/platform. The payment token thus generated, can then also be used to create the customer account at merchant/platform. Use this also when multiple payment tokens are required for the same payer, different customer at merchant/platform. This helps to identify customers distinctly even though they may share the same PayPal account. This only applies to PayPal payment source.
usage_typestring"MERCHANT", "PLATFORM"^[0-9A-Z_]+$The usage type associated with a digital wallet payment token.
customer_typestring"CONSUMER", "BUSINESS"^[0-9A-Z_]+$The customer type associated with a digital wallet payment token. This is to indicate whether the customer acting on the merchant / platform is either a business or a consumer.
billing_planobjectThe merchant level Recurring Billing plan metadata for the Billing Agreement.
billing_cyclesrequiredarrayAn array of billing cycles for trial billing and regular billing. A plan can have at most two trial cycles and only one regular cycle.
itemsobjectThe billing cycle providing details of the billing frequency, amount, duration and if the billing cycle is a free, discounted or regular billing cycle. The sequence of the billing cycle will be in the following order - free trial billing cycle(s), discounted trial billing cycle(s), regular billing cycle(s).
tenure_typerequiredstring"REGULAR", "TRIAL"^[A-Z_]+$The tenure type of the billing cycle identifies if the billing cycle is a trial(free or discounted) or regular billing cycle.
pricing_schemeobjectThe active pricing scheme for this billing cycle. A free trial billing cycle does not require a pricing scheme.
priceobjectThe price the customer will be charged based on the pricing model
currency_coderequiredstringThe three-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.pricing_modelrequiredstring"FIXED", "VARIABLE", "AUTO_RELOAD"^[A-Z_]+$The pricing model for the billing cycle.
reload_threshold_amountobjectThe threshold amount on which the reload charge would be triggered. This will be associated with the account-balance where if the account-balance goes below this amount then customer would incur reload charge.
currency_coderequiredstringThe three-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.frequencyThe frequency details for this billing cycle.
total_cyclesintegerint321The number of times this billing cycle gets executed. Trial billing cycles can only be executed a finite number of times (value between 1 and 999 for total_cycles). Regular billing cycles can be executed infinite times (value of 0 for total_cycles) or a finite number of times (value between 1 and 999 for total_cycles).
sequenceintegerint321The order in which this cycle is to run among other billing cycles. For example, a trial billing cycle has a sequence of 1 while a regular billing cycle has a sequence of 2, so that trial cycle runs before the regular cycle.
start_datestringppaas_date_notime_v2^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$The start date for the billing cycle, in YYYY-MM-DD. This field should be not be provided if the billing cycle starts at the time of checkout. When this field is not provided, the billing cycle amount will be included in any data validations confirming that the total provided by the merchant match the sum of individual items due at the time of checkout. Only one billing cycle (with sequence equal to 1) can have a no start date.
productProduct details associated with any one-time product purchase.
one_time_chargesrequiredobjectPrice and currency for any one-time charges due at plan signup.
setup_feeobjectThe setup fee for the recurring plan.
currency_coderequiredstringThe three-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.shipping_amountobjectThe shipping amount due at the time of checkout.
currency_coderequiredstringThe three-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.taxesobjectThe taxes due at the time of checkout.
currency_coderequiredstringThe three-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.product_priceobjectThe product price for any one-time product purchased at the time of checkout.
currency_coderequiredstringThe three-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.subtotalobjectThe subtotal at the time of checkout. This is calculated by using the formula x + y + z where x is first-recurring-charge, y is setup-fee and z is item-price.
currency_coderequiredstringThe three-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.total_amountrequiredobjectThe total amount at the time of checkout. This is calculated by using the formula x + y + z where x is subtotal, y is shipping-amount and z is taxes.
currency_coderequiredstringThe three-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.namestring^[A-Za-z0-9() +',.:-]+$Name of the recurring plan.
experience_contextobjectA resource representing an experience context of vault PayPal Wallet.
brand_namestring^.*$The label that overrides the business name in the PayPal account on the PayPal site. The pattern is defined by an external party and supports Unicode.
localestringppaas_common_language_v3^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$The BCP 47-formatted locale of pages that the PayPal vaulting experience shows. PayPal supports a five-character code. For example, DA-DK, HE-IL, ID-ID, JA-JP, NO-NO, PT-BR, RU-RU, SV-SE, TH-TH, ZH-CN, ZH-HK, or ZH-TW.
return_urlstringuriThe URL where the customer is redirected after customer approves leaves the flow. It is a required field for contingency flows like PayPal wallet, 3DS.
cancel_urlstringuriThe URL where the customer is redirected after customer cancels or leaves the flow. It is a required field for contingency flows like PayPal wallet, 3DS.
shipping_preferencestring"GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS"^[0-9A-Z_]+$"GET_FROM_FILE"The shipping preference. This only applies to PayPal payment source.
vault_instructionstring"ON_CREATE_PAYMENT_TOKENS", "ON_PAYER_APPROVAL"^[A-Z_]+$"ON_CREATE_PAYMENT_TOKENS"DEPRECATED. Vault Instruction on action to be performed after a successful payer approval.
app_switch_contextobjectMerchant provided details of the native app or mobile web browser to facilitate buyer's app switch to the PayPal consumer app.
native_appobjectMerchant provided, buyer's native app preferences to app switch to the PayPal consumer app.
os_typestring"ANDROID", "IOS", "OTHER"^[A-Z_]+$Operating System type of the device that the buyer is using.
os_versionstring^.*$Operating System version of the device that the buyer is using.
mobile_webobjectBuyer's mobile web browser context to app switch to the PayPal consumer app.
return_flowstring"AUTO", "MANUAL"^[A-Z_]+$"AUTO"Merchant preference on how the buyer can navigate back to merchant website post approving the transaction on the PayPal App.
buyer_user_agentstring^.*$User agent from the request originating from the buyer's device. This will be used to identify the buyer's operating system and browser versions. NOTE: Merchants must not alter or modify the buyer's device user agent.
user_actionstring"SETUP_NOW", "CONTINUE"^[A-Z_]+$"CONTINUE"User Action on action to be performed after a successful payer approval.