On this page
No Headings
The order request details.
objectintentrequiredstring"CAPTURE", "AUTHORIZE"The intent to either capture payment immediately or authorize a payment for an order after order creation.
payerobjectThe customer who approves and pays for the order. The customer is also known as the payer.
DEPRECATED. The customer is also known as the payer. The Payer object was intended to only be used with the payment_source.paypal object. In order to make this design more clear, the details in the payer object are now available under payment_source.paypal. Please use payment_source.paypal. DEPRECATED
| See | Since Version |
|---|---|
| payment_source.paypal | 2.9 |
purchase_unitsrequiredarrayAn array of purchase units. Each purchase unit establishes a contract between a payer and the payee. Each purchase unit represents either a full or partial order that the payer intends to purchase from the payee.
itemsobjectThe purchase unit request. Includes required information for the payment contract.
The purchase unit. Establishes a contract between a payer and the payee.
reference_idstring^[\S\s]*$The API caller-provided external ID for the purchase unit. Required for multiple purchase units when you must update the order through PATCH. If you omit this value and the order contains only one purchase unit, PayPal sets this value to default.
amountrequiredobjectThe total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specify amount.breakdown, the amount equals item_total plus tax_total plus shipping plus handling plus insurance minus shipping_discount minus discount.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.
The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specify amount.breakdown, the amount equals item_total plus tax_total plus shipping plus handling plus insurance minus shipping_discount minus discount.
The amount must be a positive number. The amount.value field supports up to 15 digits preceding the decimal. For a list of supported currencies, decimal precision, and maximum charge amount, see the PayPal REST APIs Currency Codes.
payeeobjectThe merchant who receives the funds and fulfills the order. The merchant is also known as the payee.
The merchant who receives payment for this transaction.
payment_instructionobjectAny additional payment instructions to be consider during payment processing. This processing instruction is applicable for Capturing an order or Authorizing an Order.
platform_feesarrayAn array of various fees, commissions, tips, or donations. This field is only applicable to merchants that been enabled for PayPal Complete Payments Platform for Marketplaces and Platforms capability.
itemsobjectThe platform or partner fee, commission, or brokerage fee that is associated with the transaction. Not a separate or isolated transaction leg from the external perspective. The platform fee is limited in scope and is always associated with the original payment for the purchase unit.
amountrequiredobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The fee for this transaction.
currency_coderequiredstring^[\S\s]*$The 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.payeeobjectThe details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee.
The recipient of the fee for this transaction.
email_addressobject^.*(?:[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])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-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 internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
The email address of merchant.
merchant_idobject^[2-9A-HJ-NP-Z]{13}$The account identifier for a PayPal account.
The encrypted PayPal account ID of the merchant.
disbursement_modeobject"INSTANT", "DELAYED""INSTANT"The funds that are held on behalf of the merchant.
The funds that are held payee by the marketplace/platform. This field is only applicable to merchants that been enabled for PayPal Complete Payments Platform for Marketplaces and Platforms capability.
payee_pricing_tier_idstring^.*$This field is only enabled for selected merchants/partners to use and provides the ability to trigger a specific pricing rate/plan for a payment transaction. The list of eligible 'payee_pricing_tier_id' would be provided to you by your Account Manager. Specifying values other than the one provided to you by your account manager would result in an error.
payee_receivable_fx_rate_idstring^.*$FX identifier generated returned by PayPal to be used for payment processing in order to honor FX rate (for eligible integrations) to be used when amount is settled/received into the payee account.
descriptionstring^[\S\s]*$This field supports up to 3,000 characters, but any content beyond 127 characters (including spaces) will be truncated. The 127 character limit is reflected in the response representation of this field.The purchase description. The maximum length of the character is dependent on the type of characters used. The character length is specified assuming a US ASCII character. Depending on type of character; (e.g. accented character, Japanese characters) the number of characters that that can be specified as input might not equal the permissible max length.
custom_idstring^[\S\s]*$The API caller-provided external ID. Used to reconcile client transactions with PayPal transactions. Appears in transaction and settlement reports but is not visible to the payer.
invoice_idstring^[\S\s]*$The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives. invoice_id values are required to be unique within each merchant account by default. Although the uniqueness validation is configurable, disabling this behavior will remove the account's ability to use invoice_id in other APIs as an identifier. It is highly recommended to keep a unique invoice_id for each Order.
soft_descriptorstring^[\S\s]*$This field supports up to 127 characters, but any content beyond 22 characters (including spaces) will be truncated. The 22 character limit is reflected in the response representation of this field.The soft descriptor is the dynamic text used to construct the statement descriptor that appears on a payer's card statement.
PAYPAL_prefix+(space)+merchant_descriptor+(space)+ soft_descriptorNote: The merchant descriptor is the descriptor of the merchant’s payment receiving preferences which can be seen by logging into the merchant account https://www.sandbox.paypal.com/businessprofile/settings/info/editThe
PAYPAL prefix uses 8 characters. Only the first 22 characters will be displayed in the statement. PAYPAL *.Janes Gift.800-123-1234.PAYPAL * Janes Gift 80.itemsarrayAn array of items that the customer purchases from the merchant.
itemsobjectThe details for the items to be purchased.
The item.
namerequiredstring^[\S\s]*$The item name or title.
This field supports up to 3000 characters, but any content beyond 127 characters (including spaces) will be truncated. The 127 character limit is reflected in the response representation of this field.
unit_amountrequiredobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The item price or rate per unit. If you specify unit_amount, purchase_units[].amount.breakdown.item_total is required. Must equal unit_amount * quantity for all items. unit_amount.value can not be a negative number.
currency_coderequiredstring^[\S\s]*$The 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.taxobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The item tax for each unit. If tax is specified, purchase_units[].amount.breakdown.tax_total is required. Must equal tax * quantity for all items. tax.value can not be a negative number.
currency_coderequiredstring^[\S\s]*$The 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.quantityrequiredstring^[1-9][0-9]{0,9}$The item quantity. Must be a whole number.
descriptionstring^[\S\s]*$This field supports up to 4000 characters, but any content beyond 2048 characters (including spaces) will be truncated. The 2048 character limit is reflected in the response representation of this field.
skustring^[\S\s]*$The stock keeping unit (SKU) for the item.
urlstringuriThe URL to the item being purchased. Visible to buyer and used in buyer experiences.
categorystring"DIGITAL_GOODS", "PHYSICAL_GOODS", "DONATION"The item category type.
image_urlstringuriThe URL of the item's image. File type and size restrictions apply. An image that violates these restrictions will not be honored.
upcobjectThe Universal Product Code of the item.
The Universal Product Code of the item.
typerequiredstring"UPC-A", "UPC-B", "UPC-C", "UPC-D", "UPC-E", "UPC-2", "UPC-5"The Universal Product Code type.
coderequiredstring^[0-9]{0,17}$The UPC product code of the item.
billing_planobjectMetadata for merchant-managed recurring billing plans. Valid only during the saved payment method token or billing agreement creation.
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"The tenure type of the billing cycle identifies if the billing cycle is a trial(free or discounted) or regular billing cycle.
pricing_schemeobjectThe pricing scheme details.
The active pricing scheme for this billing cycle. A free trial billing cycle does not require a pricing scheme.
priceobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The price the customer will be charged based on the pricing model
currency_coderequiredstring^[\S\s]*$The 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"The pricing model for the billing cycle.
reload_threshold_amountobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The 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_coderequiredstring^[\S\s]*$The 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_cyclesinteger1The 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).
sequenceinteger1The 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_dateobject^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.
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.
setup_feeobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The setup fee for the recurring plan. Ensure its part of the item amount.
currency_coderequiredstring^[\S\s]*$The 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.
shippingobjectThe shipping details.
The name and address of the person to whom to ship the items.
nameobjectThe name of the party.
The name of the person to whom to ship the items. Supports only the full_name property.
prefixstring^[\S\s]*$The prefix, or title, to the party's name.
given_namestring^[\S\s]*$When the party is a person, the party's given, or first, name.
surnamestring^[\S\s]*$When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
middle_namestring^[\S\s]*$When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
suffixstring^[\S\s]*$The suffix for the party's name.
full_namestring^[\S\s]*$When the party is a person, the party's full name.
email_addressobject^(?:[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 internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
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.
The phone number of the recipient of the shipped items, which may belong to either the payer, or an alternate contact, for delivery. [Format - canonical international E.164 numbering plan]
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).
extension_numberstring^[0-9]{1,15}?$The extension number.
typestring"SHIPPING", "PICKUP_IN_PERSON", "PICKUP_IN_STORE", "PICKUP_FROM_PERSON""SHIPPING"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.
optionsarrayAn array of shipping options that the payee or merchant offers to the payer to ship or pick up their items.
itemsobjectThe options that the payee or merchant offers to the payer to ship or pick up their items.
The option that the payee or merchant offers to the payer to ship or pick up their items.
idrequiredstring^[\S\s]*$A unique ID that identifies a payer-selected shipping option.
labelrequiredstring^[\S\s]*$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ò. Localize this description to the payer's locale.
typeobject"SHIPPING", "PICKUP", "PICKUP_IN_STORE", "PICKUP_FROM_PERSON""SHIPPING"A classification for the method of purchase fulfillment.
A classification for the method of purchase fulfillment.
amountobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The shipping cost for the selected option.
currency_coderequiredstring^[\S\s]*$The 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.selectedrequiredbooleanIf the API request sets selected = true, it represents the shipping option that the payee or merchant expects to be pre-selected for the payer when they first view the shipping.options in the PayPal Checkout experience. As part of the response if a shipping.option contains selected=true, it represents the shipping option that the payer selected during the course of checkout with PayPal. Only one shipping.option can be set to selected=true.
addressobjectThe portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.
The address of the person to whom to ship the items. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties. admin_area_1 is required for addresses located in Argentina, Brazil, China, Canada, India, Indonesia, Japan, Mexico, Thailand, and the United States.
address_line_1string^[\S\s]*$The 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_2string^[\S\s]*$The second line of the address, for example, a suite or apartment number.
address_line_3string^[\S\s]*$The third line of the address, if needed. Examples include a street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.
admin_area_4string^[\S\s]*$The neighborhood, ward, or district. This is smaller than admin_area_level_3 or sub_locality. Value is:
admin_area_3string^[\S\s]*$The sub-locality, suburb, neighborhood, or district. This is smaller than admin_area_level_2. Value is:
admin_area_2string^[\S\s]*$A city, town, or village. Smaller than admin_area_level_1.
admin_area_1string^[\S\s]*$The 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_codestring^[\S\s]*$The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
country_coderequiredstring^([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.
address_detailsobjectThe non-portable additional address details include fine-grain address information for Compliance, Risk, and other scenarios. This isn't portable with common third-party and open source applications. This can include data that is redundant with core fields. For example, address_portable.address_line_1 is usually a combination of address_details.street_number, street_name, and street_type.
street_numberstring^[\S\s]*$The street number.
street_namestring^[\S\s]*$The street name. Just Drury in Drury Lane.
street_typestring^[\S\s]*$The street type. For example, avenue, boulevard, road, or expressway.
delivery_servicestring^[\S\s]*$The delivery service. Post office box, bag number, or post office name.
building_namestring^[\S\s]*$A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, Craven House.
sub_buildingstring^[\S\s]*$The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.
supplementary_dataobjectSupplementary data about a payment. This object passes information that can be used to improve risk assessments and processing costs, for example, by providing Level 2 and Level 3 payment data.
Contains Supplementary Data.
cardobjectMerchants and partners can add Level 2 and 3 data to payments to reduce risk and payment processing costs. For more information about processing payments, see checkout or multiparty checkout.
Merchants and partners can add Level 2 and 3 data to payments to reduce risk and payment processing costs. For more information about processing payments, see checkout or multiparty checkout.
level_2objectThe level 2 card processing data collections. If your merchant account has been configured for Level 2 processing this field will be passed to the processor on your behalf. Please contact your PayPal Technical Account Manager to define level 2 data for your business.
invoice_idstring^[\w‘\-.,":;\!?]*$Use this field to pass a purchase identification value of up to 127 ASCII characters. The length of this field will be adjusted to meet network specifications (25chars for Visa and Mastercard, 17chars for Amex), and the original invoice ID will still be displayed in your existing reports.
tax_totalobjectThe currency and amount for a financial transaction, such as a balance or payment due.
Use this field to break down the amount of tax included in the total purchase amount. The value provided here will not add to the total purchase amount. The value can't be negative, and in most cases, it must be greater than zero in order to qualify for lower interchange rates. Value, by country, is:
UK. A county.
US. A state.
Canada. A province.
Japan. A prefecture.
Switzerland. A kanton.
currency_coderequiredstring^[\S\s]*$The 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.level_3objectThe level 3 card processing data collections, If your merchant account has been configured for Level 3 processing this field will be passed to the processor on your behalf. Please contact your PayPal Technical Account Manager to define level 3 data for your business.
shipping_amountobjectThe currency and amount for a financial transaction, such as a balance or payment due.
Use this field to break down the shipping cost included in the total purchase amount. The value provided here will not add to the total purchase amount. The value cannot be negative.
currency_coderequiredstring^[\S\s]*$The 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.duty_amountobjectThe currency and amount for a financial transaction, such as a balance or payment due.
Use this field to break down the duty amount included in the total purchase amount. The value provided here will not add to the total purchase amount. The value cannot be negative.
currency_coderequiredstring^[\S\s]*$The 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.discount_amountobjectThe currency and amount for a financial transaction, such as a balance or payment due.
Use this field to break down the discount amount included in the total purchase amount. The value provided here will not add to the total purchase amount. The value cannot be negative.
currency_coderequiredstring^[\S\s]*$The 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_addressobjectThe portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.
The address of the person to whom to ship the items. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.
address_line_1string^[\S\s]*$The 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_2string^[\S\s]*$The second line of the address, for example, a suite or apartment number.
address_line_3string^[\S\s]*$The third line of the address, if needed. Examples include a street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.
admin_area_4string^[\S\s]*$The neighborhood, ward, or district. This is smaller than admin_area_level_3 or sub_locality. Value is:
admin_area_3string^[\S\s]*$The sub-locality, suburb, neighborhood, or district. This is smaller than admin_area_level_2. Value is:
admin_area_2string^[\S\s]*$A city, town, or village. Smaller than admin_area_level_1.
admin_area_1string^[\S\s]*$The 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_codestring^[\S\s]*$The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
country_coderequiredstring^([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.
address_detailsobjectThe non-portable additional address details include fine-grain address information for Compliance, Risk, and other scenarios. This isn't portable with common third-party and open source applications. This can include data that is redundant with core fields. For example, address_portable.address_line_1 is usually a combination of address_details.street_number, street_name, and street_type.
street_numberstring^[\S\s]*$The street number.
street_namestring^[\S\s]*$The street name. Just Drury in Drury Lane.
street_typestring^[\S\s]*$The street type. For example, avenue, boulevard, road, or expressway.
delivery_servicestring^[\S\s]*$The delivery service. Post office box, bag number, or post office name.
building_namestring^[\S\s]*$A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, Craven House.
sub_buildingstring^[\S\s]*$The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.
ships_from_postal_codestring^[a-zA-Z0-9_'.-]*$Use this field to specify the postal code of the shipping location.
line_itemsarrayA list of the items that were purchased with this payment. If your merchant account has been configured for Level 3 processing this field will be passed to the processor on your behalf.
itemsobjectThe line items for this purchase. If your merchant account has been configured for Level 3 processing this field will be passed to the processor on your behalf.
riskobjectAdditional information necessary to evaluate the risk profile of a transaction.
Merchants and partners can add additional customer parameters that can help with better fraud protection and reduced risk for unbranded card payments.
customerobjectProfile information of the sender or receiver.
ip_addressobject^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$|^(([a-zA-Z]|[a-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*([A-Za-z]|[A-Za-z][A-Za-z0-9\-]*[A-Za-z0-9])$|^\s*((([0-9A-Fa-f]{1,4}:){7}([0-9A-Fa-f]{1,4}|:))|(([0-9A-Fa-f]{1,4}:){6}(:[0-9A-Fa-f]{1,4}|((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){5}(((:[0-9A-Fa-f]{1,4}){1,2})|:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){4}(((:[0-9A-Fa-f]{1,4}){1,3})|((:[0-9A-Fa-f]{1,4})?:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){3}(((:[0-9A-Fa-f]{1,4}){1,4})|((:[0-9A-Fa-f]{1,4}){0,2}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){2}(((:[0-9A-Fa-f]{1,4}){1,5})|((:[0-9A-Fa-f]{1,4}){0,3}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){1}(((:[0-9A-Fa-f]{1,4}){1,6})|((:[0-9A-Fa-f]{1,4}){0,4}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(:(((:[0-9A-Fa-f]{1,4}){1,7})|((:[0-9A-Fa-f]{1,4}){0,5}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:)))(%.+)?\s*$An Internet Protocol address (IP address). This address assigns a numerical label to each device that is connected to a computer network through the Internet Protocol. Supports IPv4 and IPv6 addresses.
The consumer's IP address, which can be represented in either IPv4 or IPv6 format.
payment_sourceobjectThe payment source definition.
cardobjectThe payment card to use to fund a payment. Can be a credit or debit card.
Note: Passing card number, cvv and expiry directly via the API requires PCI SAQ D compliance.
PayPal offers a mechanism by which you do not have to take on the PCI SAQ D burden by using hosted fields - refer to this Integration Guide.
vault_idobject^[0-9a-zA-Z_-]+$The PayPal-generated ID for the vaulted payment source. This ID should be stored on the merchant's server so the saved payment source can be used for future transactions.
The PayPal-generated ID for the saved card payment source. Typically stored on the merchant's server.
single_use_tokenobject^[0-9a-zA-Z_-]+$The PayPal-generated, short-lived, one-time-use token, used to communicate payment information to PayPal for transaction processing.
The PayPal-generated, short-lived, one-time-use token, used to communicate payment information to PayPal for transaction processing.
stored_credentialobjectProvides additional details to process a payment using a card that has been stored or is intended to be stored (also referred to as stored_credential or card-on-file).
Parameter compatibility:
payment_type=ONE_TIME is compatible only with payment_initiator=CUSTOMER.usage=FIRST is compatible only with payment_initiator=CUSTOMER.previous_transaction_reference or previous_network_transaction_reference is compatible only with payment_initiator=MERCHANT.previous_transaction_reference and previous_network_transaction_reference - can be present in the request.payment_initiatorrequiredstring"CUSTOMER", "MERCHANT"The person or party who initiated or triggered the payment.
payment_typerequiredstring"ONE_TIME", "RECURRING", "UNSCHEDULED"Indicates the type of the stored payment_source payment.
usagestring"FIRST", "SUBSEQUENT", "DERIVED""DERIVED"Indicates if this is a first or subsequent payment using a stored payment source (also referred to as stored credential or card on file).
previous_network_transaction_referenceobjectReference values used by the card network to identify a transaction.
idrequiredstring^[a-zA-Z0-9-_@.:&+=*^'~#!$%()]+$Transaction reference id returned by the scheme. For Visa and Amex, this is the "Tran id" field in response. For MasterCard, this is the "BankNet reference id" field in response. For Discover, this is the "NRID" field in response. The pattern we expect for this field from Visa/Amex/CB/Discover is numeric, Mastercard/BNPP is alphanumeric and Paysecure is alphanumeric with special character -.
datestring^[0-9]+$The date that the transaction was authorized by the scheme. This field may not be returned for all networks. MasterCard refers to this field as "BankNet reference date". For some specific networks, such as MasterCard and Discover, this date field is mandatory when the previous_network_transaction_reference_id is passed.
networkobject"VISA", "MASTERCARD", "DISCOVER", "AMEX", "SOLO", "JCB", "STAR", "DELTA", "SWITCH", "MAESTRO", "CB_NATIONALE", "CONFIGOGA", "CONFIDIS", "ELECTRON", "CETELEM", "CHINA_UNION_PAY", "DINERS", "ELO", "HIPER", "HIPERCARD", "RUPAY", "GE", "SYNCHRONY", "EFTPOS", "CARTE_BANCAIRE", "STAR_ACCESS", "PULSE", "NYCE", "ACCEL", "UNKNOWN"The card network or brand. Applies to credit, debit, gift, and payment cards.
Name of the card network through which the transaction was routed.
acquirer_reference_numberstring^[a-zA-Z0-9]+$Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks.
network_tokenobjectThe Third Party Network token used to fund a payment.
A 3rd party network token refers to a network token that the merchant provisions from and vaults with an external TSP (Token Service Provider) other than PayPal.
numberrequiredstring^[0-9]{13,19}$Third party network token number.
expiryrequiredobject^[0-9]{4}-(0[1-9]|1[0-2])$The year and month, in ISO-8601 YYYY-MM date format. See Internet date and time format.
The card expiration year and month, in Internet date format.
cryptogramstring^.*$An Encrypted one-time use value that's sent along with Network Token. This field is not required to be present for recurring transactions.
eci_flagstring"MASTERCARD_NON_3D_SECURE_TRANSACTION", "MASTERCARD_ATTEMPTED_AUTHENTICATION_TRANSACTION", "MASTERCARD_FULLY_AUTHENTICATED_TRANSACTION", "FULLY_AUTHENTICATED_TRANSACTION", "ATTEMPTED_AUTHENTICATION_TRANSACTION", "NON_3D_SECURE_TRANSACTION"Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data elements that indicate the transaction was processed electronically. This should be passed on the authorization transaction to the Gateway/Processor.
token_requestor_idstring^[0-9A-Z_]+$A TRID, or a Token Requestor ID, is an identifier used by merchants to request network tokens from card networks. A TRID is a precursor to obtaining a network token for a credit card primary account number (PAN), and will aid in enabling secure card on file (COF) payments and reducing fraud.
experience_contextobjectCustomizes the payer experience during the 3DS Approval for payment.
return_urlobjecturiDescribes the URL.
The URL where the customer will be redirected upon successfully completing the 3DS challenge.
cancel_urlobjecturiDescribes the URL.
The URL where the customer will be redirected upon cancelling the 3DS challenge.
tokenobjectThe tokenized payment source to fund a payment.
idrequiredstring^[0-9a-zA-Z_-]+$The PayPal-generated ID for the token.
typerequiredstring"BILLING_AGREEMENT"The tokenization method that generated the ID.
paypalobjectA resource that identifies a PayPal Wallet is used for payment.
Indicates that PayPal Wallet is the payment source. Main use of this selection is to provide additional instructions associated with this choice like vaulting.
vault_idobject^[0-9a-zA-Z_-]+$The PayPal-generated ID for the vaulted payment source. This ID should be stored on the merchant's server so the saved payment source can be used for future transactions.
The PayPal-generated ID for the payment_source stored within the Vault.
email_addressobject^.*(?:[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])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-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 internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
The email address of the PayPal account holder.
nameobjectThe name of the party.
The name of the PayPal account holder. Supports only the given_name and surname properties.
prefixstring^[\S\s]*$The prefix, or title, to the party's name.
given_namestring^[\S\s]*$When the party is a person, the party's given, or first, name.
surnamestring^[\S\s]*$When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
middle_namestring^[\S\s]*$When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
suffixstring^[\S\s]*$The suffix for the party's name.
full_namestring^[\S\s]*$When the party is a person, the party's full name.
phoneobjectThe phone information.
The phone number of the customer. Available only when you enable the Contact Telephone Number option in the Profile & Settings for the merchant's PayPal account. The phone.phone_number supports only national_number.
phone_typestring"FAX", "HOME", "MOBILE", "OTHER", "PAGER"The phone type.
phone_numberrequiredobjectA structured representation of a phone number conforming to the international E.164 numbering plan format,requiring only the national_number field.
The phone number, in its canonical international E.164 numbering plan format. Supports only the national_number property.
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).
birth_dateobject^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.
The birth date of the PayPal account holder in YYYY-MM-DD format.
tax_infoobjectThe tax ID of the customer. The customer is also known as the payer. Both tax_id and tax_id_type are required.
The tax information of the PayPal account holder. Required only for Brazilian PayPal account holder's. Both tax_id and tax_id_type are required.
tax_idrequiredstring^.*([a-zA-Z0-9]).*$The customer's tax ID value.
tax_id_typerequiredstring"BR_CPF", "BR_CNPJ"The customer's tax ID type.
addressobjectThe portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.
The address of the PayPal account holder. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties. Also referred to as the billing address of the customer.
address_line_1string^[\S\s]*$The 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_2string^[\S\s]*$The second line of the address, for example, a suite or apartment number.
address_line_3string^[\S\s]*$The third line of the address, if needed. Examples include a street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.
admin_area_4string^[\S\s]*$The neighborhood, ward, or district. This is smaller than admin_area_level_3 or sub_locality. Value is:
admin_area_3string^[\S\s]*$The sub-locality, suburb, neighborhood, or district. This is smaller than admin_area_level_2. Value is:
admin_area_2string^[\S\s]*$A city, town, or village. Smaller than admin_area_level_1.
admin_area_1string^[\S\s]*$The 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_codestring^[\S\s]*$The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
country_coderequiredstring^([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.
address_detailsobjectThe non-portable additional address details include fine-grain address information for Compliance, Risk, and other scenarios. This isn't portable with common third-party and open source applications. This can include data that is redundant with core fields. For example, address_portable.address_line_1 is usually a combination of address_details.street_number, street_name, and street_type.
street_numberstring^[\S\s]*$The street number.
street_namestring^[\S\s]*$The street name. Just Drury in Drury Lane.
street_typestring^[\S\s]*$The street type. For example, avenue, boulevard, road, or expressway.
delivery_servicestring^[\S\s]*$The delivery service. Post office box, bag number, or post office name.
building_namestring^[\S\s]*$A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, Craven House.
sub_buildingstring^[\S\s]*$The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.
attributesobjectAdditional attributes associated with the use of this PayPal Wallet.
Additional attributes associated with the use of this wallet.
customerobjectThe details about a customer in PayPal's system of record.
idstring^[0-9a-zA-Z_-]+$The unique ID for a customer generated by PayPal.
email_addressobject^.*(?:[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])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-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 internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
Email address of the customer as provided to the merchant or on file with the merchant. Email Address is required if you are processing the transaction using PayPal Guest Processing which is offered to select partners and merchants.
phoneobjectThe phone information.
The phone number of the customer as provided to the merchant or on file with the merchant. The phone.phone_number supports only national_number.
phone_typestring"FAX", "HOME", "MOBILE", "OTHER", "PAGER"The phone type.
phone_numberrequiredobjectA structured representation of a phone number conforming to the international E.164 numbering plan format,requiring only the national_number field.
The phone number, in its canonical international E.164 numbering plan format. Supports only the national_number property.
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).
nameobjectThe name of the party.
The full name of the customer as provided to the merchant or on file with the merchant.
prefixstring^[\S\s]*$The prefix, or title, to the party's name.
given_namestring^[\S\s]*$When the party is a person, the party's given, or first, name.
surnamestring^[\S\s]*$When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
middle_namestring^[\S\s]*$When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
suffixstring^[\S\s]*$The suffix for the party's name.
full_namestring^[\S\s]*$When the party is a person, the party's full name.
merchant_customer_idstring^[0-9a-zA-Z-_.^*$@#]+$Merchants and partners may already have a data-store where their customer information is persisted. Use merchant_customer_id to associate the PayPal-generated customer.id to your representation of a customer.
vaultobjectResource consolidating common request and response attributes for vaulting PayPal Wallet.
Attributes used to provide the instructions during vaulting of the PayPal Wallet.
experience_contextobjectCustomizes the payer experience during the approval process for payment with PayPal.
Note: Partners and Marketplaces might configurebrand_nameandshipping_preferenceduring partner account setup, which overrides the request values.
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.
localeobject^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.
The BCP 47-formatted locale of pages that the PayPal payment 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.
shipping_preferencestring"GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS""GET_FROM_FILE"The location from which the shipping address is derived.
contact_preferencestring"NO_CONTACT_INFO", "UPDATE_CONTACT_INFO", "RETAIN_CONTACT_INFO""NO_CONTACT_INFO"The preference to display the contact information (buyer’s shipping email & phone number) on PayPal's checkout for easy merchant-buyer communication.
return_urlobjecturiDescribes the URL.
The URL where the customer will be redirected upon approving a payment.
cancel_urlobjecturiDescribes the URL.
The URL where the customer will be redirected upon cancelling the payment 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.
Merchants can use this to switch buyers from their website/application to the PayPal consumer app to review and approve the transaction.
native_appobjectMerchant provided, buyer's native app preferences to app switch to the PayPal consumer app.
os_typestring"ANDROID", "IOS", "OTHER"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""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.
landing_pagestring"LOGIN", "GUEST_CHECKOUT", "NO_PREFERENCE", "BILLING""NO_PREFERENCE"The type of landing page to show on the PayPal site for customer checkout.
user_actionstring"CONTINUE", "PAY_NOW""CONTINUE"Configures a Continue or Pay Now checkout flow.
payment_method_preferencestring"UNRESTRICTED", "IMMEDIATE_PAYMENT_REQUIRED""UNRESTRICTED"The merchant-preferred payment methods.
order_update_callback_configobjectCallBack Configuration that the merchant can provide to PayPal/Venmo.
Merchant provided Order Update callback configuration for PayPal Wallet.PayPal will call back merchant when the specified event occurs.we recommend merchants to pass both the shipping_options and shipping_address callback events. Not supported when shipping.type is specified or when 'application_context.shipping_preference' is set as 'NO_SHIPPING' or 'SET_PROVIDED_ADDRESS'.
callback_eventsrequiredarrayAn array of callback events merchant can subscribe to for the corresponding callback url.
itemsstring"SHIPPING_ADDRESS", "SHIPPING_OPTIONS"CallBack event.
callback_urlrequiredstringuriMerchant provided CallBack url.PayPal/Venmo will use this url to call the merchant back when the events occur .PayPal/Venmo expects a secured url usually in the https format.merchant can append the cart id or other params part of the url as query or path params.
billing_agreement_idstring^[a-zA-Z0-9-]+$The PayPal billing agreement ID. References an approved recurring payment for goods or services.
stored_credentialobjectProvides additional details to process a payment using the PayPal wallet billing agreement or a vaulted payment method that has been stored or is intended to be stored.
payment_initiatorrequiredstring"CUSTOMER", "MERCHANT"The person or party who initiated or triggered the payment.
charge_patternobject"IMMEDIATE", "DEFERRED", "RECURRING_PREPAID", "RECURRING_POSTPAID", "THRESHOLD_PREPAID", "THRESHOLD_POSTPAID", "SUBSCRIPTION_PREPAID", "SUBSCRIPTION_POSTPAID", "UNSCHEDULED_PREPAID", "UNSCHEDULED_POSTPAID", "INSTALLMENT_PREPAID", "INSTALLMENT_POSTPAID"Expected business/pricing model for the billing agreement.
DEPRECATED. Expected business/pricing model for the billing agreement, Please use usage_pattern instead. DEPRECATED
| See |
|---|
| usage_pattern |
usage_patternstring"IMMEDIATE", "DEFERRED", "RECURRING_PREPAID", "RECURRING_POSTPAID", "THRESHOLD_PREPAID", "THRESHOLD_POSTPAID", "SUBSCRIPTION_PREPAID", "SUBSCRIPTION_POSTPAID", "UNSCHEDULED_PREPAID", "UNSCHEDULED_POSTPAID", "INSTALLMENT_PREPAID", "INSTALLMENT_POSTPAID"Expected business/pricing model for the billing agreement.
usagestring"FIRST", "SUBSEQUENT", "DERIVED""DERIVED"Indicates if this is a first or subsequent payment using a stored payment source (also referred to as stored credential or card on file).
bancontactobjectInformation needed to pay using Bancontact.
Bancontact is the most popular online payment in Belgium. More Details.
namerequiredobject^[\S\s]*$The full name representation like Mr J Smith.
The name of the account holder associated with this payment method.
country_coderequiredobject^([A-Z]{2}|C2)$The two-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.
The two-character ISO 3166-1 country code.
experience_contextobjectCustomizes the payer experience during the approval process for the payment.
Customizes the payer experience during the approval process for the payment.
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.
localeobject^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.
The BCP 47-formatted locale of pages that the PayPal payment 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.
shipping_preferencestring"GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS""GET_FROM_FILE"The location from which the shipping address is derived.
return_urlobjecturiDescribes the URL.
The URL where the customer is redirected after the customer approves the payment.
cancel_urlobjecturiDescribes the URL.
The URL where the customer is redirected after the customer cancels the payment.
blikobjectInformation needed to pay using BLIK.
BLIK is a mobile payment system, created by Polish Payment Standard in order to allow millions of users to pay in shops, payout cash in ATMs and make online purchases and payments. More Details.
namerequiredobject^[\S\s]*$The full name representation like Mr J Smith.
The name of the account holder associated with this payment method.
country_coderequiredobject^([A-Z]{2}|C2)$The two-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.
The two-character ISO 3166-1 country code.
emailobject^(?:[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 internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
The email address of the account holder associated with this payment method.
experience_contextobjectCustomizes the payer experience during the approval process for the BLIK payment.
Customizes the payer experience during the approval process for the payment.
level_0objectInformation used to pay using BLIK level_0 flow.
The level_0 integration flow object.
auth_coderequiredstring^[0-9]{6}$The 6-digit code used to authenticate a consumer within BLIK.
one_clickobjectInformation used to pay using BLIK one-click flow.
The one-click integration flow object.
auth_codestring^[0-9]{6}$The 6-digit code used to authenticate a consumer within BLIK.
consumer_referencerequiredstring^[ -~]{3,64}$The merchant generated, unique reference serving as a primary identifier for accounts connected between Blik and a merchant.
alias_labelstring^[ -~]{8,35}$A bank defined identifier used as a display name to allow the payer to differentiate between multiple registered bank accounts.
alias_keystring^[0-9]+$A Blik-defined identifier for a specific Blik-enabled bank account that is associated with a given merchant. Used only in conjunction with a Consumer Reference.
epsobjectInformation needed to pay using eps.
The eps transfer is an online payment method developed by many Austrian banks. More Details.
namerequiredobject^[\S\s]*$The full name representation like Mr J Smith.
The name of the account holder associated with this payment method.
country_coderequiredobject^([A-Z]{2}|C2)$The two-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.
The two-character ISO 3166-1 country code.
experience_contextobjectCustomizes the payer experience during the approval process for the payment.
Customizes the payer experience during the approval process for the payment.
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.
localeobject^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.
The BCP 47-formatted locale of pages that the PayPal payment 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.
shipping_preferencestring"GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS""GET_FROM_FILE"The location from which the shipping address is derived.
return_urlobjecturiDescribes the URL.
The URL where the customer is redirected after the customer approves the payment.
cancel_urlobjecturiDescribes the URL.
The URL where the customer is redirected after the customer cancels the payment.
giropayobjectInformation needed to pay using giropay.
Giropay is an Internet payment System in Germany, based on online banking. More Details.
namerequiredobject^[\S\s]*$The full name representation like Mr J Smith.
The name of the account holder associated with this payment method.
country_coderequiredobject^([A-Z]{2}|C2)$The two-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.
The two-character ISO 3166-1 country code.
experience_contextobjectCustomizes the payer experience during the approval process for the payment.
Customizes the payer experience during the approval process for the payment.
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.
localeobject^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.
The BCP 47-formatted locale of pages that the PayPal payment 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.
shipping_preferencestring"GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS""GET_FROM_FILE"The location from which the shipping address is derived.
return_urlobjecturiDescribes the URL.
The URL where the customer is redirected after the customer approves the payment.
cancel_urlobjecturiDescribes the URL.
The URL where the customer is redirected after the customer cancels the payment.
idealobjectInformation needed to pay using iDEAL.
The Dutch payment method iDEAL is an online payment method that enables consumers to pay online through their own bank. More Details.
namerequiredobject^[\S\s]*$The full name representation like Mr J Smith.
The name of the account holder associated with this payment method.
country_coderequiredobject^([A-Z]{2}|C2)$The two-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.
The two-character ISO 3166-1 country code.
bicobject^[A-Z-a-z0-9]{4}[A-Z-a-z]{2}[A-Z-a-z0-9]{2}([A-Z-a-z0-9]{3})?$The business identification code (BIC). In payments systems, a BIC is used to identify a specific business, most commonly a bank.
The bank identification code (BIC).
experience_contextobjectCustomizes the payer experience during the approval process for the payment.
Customizes the payer experience during the approval process for the payment.
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.
localeobject^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.
The BCP 47-formatted locale of pages that the PayPal payment 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.
shipping_preferencestring"GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS""GET_FROM_FILE"The location from which the shipping address is derived.
return_urlobjecturiDescribes the URL.
The URL where the customer is redirected after the customer approves the payment.
cancel_urlobjecturiDescribes the URL.
The URL where the customer is redirected after the customer cancels the payment.
mybankobjectInformation needed to pay using MyBank.
MyBank is an e-authorisation solution which enables safe digital payments and identity authentication through a consumer’s own online banking portal or mobile application. More Details.
namerequiredobject^[\S\s]*$The full name representation like Mr J Smith.
The name of the account holder associated with this payment method.
country_coderequiredobject^([A-Z]{2}|C2)$The two-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.
The two-character ISO 3166-1 country code.
experience_contextobjectCustomizes the payer experience during the approval process for the payment.
Customizes the payer experience during the approval process for the payment.
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.
localeobject^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.
The BCP 47-formatted locale of pages that the PayPal payment 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.
shipping_preferencestring"GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS""GET_FROM_FILE"The location from which the shipping address is derived.
return_urlobjecturiDescribes the URL.
The URL where the customer is redirected after the customer approves the payment.
cancel_urlobjecturiDescribes the URL.
The URL where the customer is redirected after the customer cancels the payment.
p24objectInformation needed to pay using P24 (Przelewy24).
P24 (Przelewy24) is a secure and fast online bank transfer service linked to all the major banks in Poland. More Details.
namerequiredobject^[\S\s]*$The full name representation like Mr J Smith.
The name of the account holder associated with this payment method.
emailrequiredobject^(?:[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 internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
The email address of the account holder associated with this payment method.
country_coderequiredobject^([A-Z]{2}|C2)$The two-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.
The two-character ISO 3166-1 country code.
experience_contextobjectCustomizes the payer experience during the approval process for the payment.
Customizes the payer experience during the approval process for the payment.
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.
localeobject^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.
The BCP 47-formatted locale of pages that the PayPal payment 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.
shipping_preferencestring"GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS""GET_FROM_FILE"The location from which the shipping address is derived.
return_urlobjecturiDescribes the URL.
The URL where the customer is redirected after the customer approves the payment.
cancel_urlobjecturiDescribes the URL.
The URL where the customer is redirected after the customer cancels the payment.
sofortobjectInformation needed to pay using Sofort.
SOFORT Banking is a real-time bank transfer payment method that buyers use to transfer funds directly to merchants from their bank accounts. More Details.
namerequiredobject^[\S\s]*$The full name representation like Mr J Smith.
The name of the account holder associated with this payment method.
country_coderequiredobject^([A-Z]{2}|C2)$The two-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.
The two-character ISO 3166-1 country code.
experience_contextobjectCustomizes the payer experience during the approval process for the payment.
Customizes the payer experience during the approval process for the payment.
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.
localeobject^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.
The BCP 47-formatted locale of pages that the PayPal payment 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.
shipping_preferencestring"GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS""GET_FROM_FILE"The location from which the shipping address is derived.
return_urlobjecturiDescribes the URL.
The URL where the customer is redirected after the customer approves the payment.
cancel_urlobjecturiDescribes the URL.
The URL where the customer is redirected after the customer cancels the payment.
trustlyobjectInformation needed to pay using Trustly.
Trustly is a payment method that allows customers to shop and pay from their bank account. More Details.
namerequiredobject^[\S\s]*$The full name representation like Mr J Smith.
The name of the account holder associated with this payment method.
country_coderequiredobject^([A-Z]{2}|C2)$The two-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.
The two-character ISO 3166-1 country code.
emailrequiredobject^(?:[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 internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
The email address of the account holder associated with this payment method.
experience_contextobjectCustomizes the payer experience during the approval process for the payment.
Customizes the payer experience during the approval process for the payment.
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.
localeobject^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.
The BCP 47-formatted locale of pages that the PayPal payment 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.
shipping_preferencestring"GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS""GET_FROM_FILE"The location from which the shipping address is derived.
return_urlobjecturiDescribes the URL.
The URL where the customer is redirected after the customer approves the payment.
cancel_urlobjecturiDescribes the URL.
The URL where the customer is redirected after the customer cancels the payment.
apple_payobjectInformation needed to pay using ApplePay.
ApplePay payment source, allows buyer to pay using ApplePay, both on Web as well as on Native.
idstring^.*$ApplePay transaction identifier, this will be the unique identifier for this transaction provided by Apple. The pattern is defined by an external party and supports Unicode.
nameobject^[\S\s]*$The full name representation like Mr J Smith.
Name on the account holder associated with apple pay.
email_addressobject^(?:[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 internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
The email address of the account holder associated with apple pay.
phone_numberobjectA structured representation of a phone number conforming to the international E.164 numbering plan format,requiring only the national_number field.
The phone number, in its canonical international E.164 numbering plan format. Supports only the national_number property.
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).
decrypted_tokenobjectInformation about the Payment data obtained by decrypting Apple Pay token.
The decrypted payload details for the apple pay token.
transaction_amountobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The transaction amount for the payment that the payer has approved on apple platform.
currency_coderequiredstring^[\S\s]*$The 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.tokenized_cardrequiredobjectThe payment card to use to fund a payment. Can be a credit or debit card.
Apple Pay tokenized credit card used to pay.
idobject^[A-Za-z0-9-_.+=]+$The identifier of the instrument.
The PayPal-generated ID for the card.
namestring^.{1,300}$The card holder's name as it appears on the card.
numberstring^[0-9]{13,19}$The primary account number (PAN) for the payment card.
expiryobject^[0-9]{4}-(0[1-9]|1[0-2])$The year and month, in ISO-8601 YYYY-MM date format. See Internet date and time format.
The card expiration year and month, in Internet date format For example: 2028-04
security_codestring^[0-9]{3,4}$The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID. This parameter cannot be present in the request when payment_initiator=MERCHANT.
last_digitsstring^[0-9]{2,4}$The last digits of the payment card.
card_typeobject"VISA", "MASTERCARD", "DISCOVER", "AMEX", "SOLO", "JCB", "STAR", "DELTA", "SWITCH", "MAESTRO", "CB_NATIONALE", "CONFIGOGA", "CONFIDIS", "ELECTRON", "CETELEM", "CHINA_UNION_PAY", "DINERS", "ELO", "HIPER", "HIPERCARD", "RUPAY", "GE", "SYNCHRONY", "EFTPOS", "CARTE_BANCAIRE", "STAR_ACCESS", "PULSE", "NYCE", "ACCEL", "UNKNOWN"The card network or brand. Applies to credit, debit, gift, and payment cards.
The card brand or network. Typically used in the response. DEPRECATED
| See |
|---|
| type |
typeobject"CREDIT", "DEBIT", "PREPAID", "STORE", "UNKNOWN"Type of card. i.e Credit, Debit and so on.
The payment card type.
brandobject"VISA", "MASTERCARD", "DISCOVER", "AMEX", "SOLO", "JCB", "STAR", "DELTA", "SWITCH", "MAESTRO", "CB_NATIONALE", "CONFIGOGA", "CONFIDIS", "ELECTRON", "CETELEM", "CHINA_UNION_PAY", "DINERS", "ELO", "HIPER", "HIPERCARD", "RUPAY", "GE", "SYNCHRONY", "EFTPOS", "CARTE_BANCAIRE", "STAR_ACCESS", "PULSE", "NYCE", "ACCEL", "UNKNOWN"The card network or brand. Applies to credit, debit, gift, and payment cards.
The card brand or network. Typically used in the response.
billing_addressobjectThe portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.
The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.
address_line_1string^[\S\s]*$The 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_2string^[\S\s]*$The second line of the address, for example, a suite or apartment number.
address_line_3string^[\S\s]*$The third line of the address, if needed. Examples include a street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.
admin_area_4string^[\S\s]*$The neighborhood, ward, or district. This is smaller than admin_area_level_3 or sub_locality. Value is:
admin_area_3string^[\S\s]*$The sub-locality, suburb, neighborhood, or district. This is smaller than admin_area_level_2. Value is:
admin_area_2string^[\S\s]*$A city, town, or village. Smaller than admin_area_level_1.
admin_area_1string^[\S\s]*$The 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_codestring^[\S\s]*$The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
country_coderequiredstring^([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.
address_detailsobjectThe non-portable additional address details include fine-grain address information for Compliance, Risk, and other scenarios. This isn't portable with common third-party and open source applications. This can include data that is redundant with core fields. For example, address_portable.address_line_1 is usually a combination of address_details.street_number, street_name, and street_type.
street_numberstring^[\S\s]*$The street number.
street_namestring^[\S\s]*$The street name. Just Drury in Drury Lane.
street_typestring^[\S\s]*$The street type. For example, avenue, boulevard, road, or expressway.
delivery_servicestring^[\S\s]*$The delivery service. Post office box, bag number, or post office name.
building_namestring^[\S\s]*$A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, Craven House.
sub_buildingstring^[\S\s]*$The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.
attributesobjectAdditional attributes associated with the use of this card.
Additional attributes associated with the use of this card.
customerobjectThe details about a customer in PayPal's system of record.
idstring^[0-9a-zA-Z_-]+$The unique ID for a customer generated by PayPal.
email_addressobject^.*(?:[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])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-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 internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
Email address of the customer as provided to the merchant or on file with the merchant. Email Address is required if you are processing the transaction using PayPal Guest Processing which is offered to select partners and merchants.
phoneobjectThe phone information.
The phone number of the customer as provided to the merchant or on file with the merchant. The phone.phone_number supports only national_number.
phone_typestring"FAX", "HOME", "MOBILE", "OTHER", "PAGER"The phone type.
phone_numberrequiredobjectA structured representation of a phone number conforming to the international E.164 numbering plan format,requiring only the national_number field.
The phone number, in its canonical international E.164 numbering plan format. Supports only the national_number property.
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).
nameobjectThe name of the party.
The full name of the customer as provided to the merchant or on file with the merchant.
prefixstring^[\S\s]*$The prefix, or title, to the party's name.
given_namestring^[\S\s]*$When the party is a person, the party's given, or first, name.
surnamestring^[\S\s]*$When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
middle_namestring^[\S\s]*$When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
suffixstring^[\S\s]*$The suffix for the party's name.
full_namestring^[\S\s]*$When the party is a person, the party's full name.
merchant_customer_idstring^[0-9a-zA-Z-_.^*$@#]+$Merchants and partners may already have a data-store where their customer information is persisted. Use merchant_customer_id to associate the PayPal-generated customer.id to your representation of a customer.
vaultobjectBasic vault instruction specification that can be extended by specific payment sources that supports vaulting.
Instruction to vault the card based on the specified strategy.
store_in_vaultstring"ON_SUCCESS"Defines how and when the payment source gets vaulted.
verificationobjectThe API caller can opt in to verify the card through PayPal offered verification services (e.g. Smart Dollar Auth, 3DS).
Instruction to optionally verify the card based on the specified strategy.
methodstring"SCA_ALWAYS", "SCA_WHEN_REQUIRED", "3D_SECURE", "AVS_CVV""SCA_WHEN_REQUIRED"The method used for card verification.
device_manufacturer_idstring^.*$Apple Pay Hex-encoded device manufacturer identifier. The pattern is defined by an external party and supports Unicode.
payment_data_typestring"3DSECURE", "EMV"Indicates the type of payment data passed, in case of Non China the payment data is 3DSECURE and for China it is EMV.
payment_dataobjectInformation about the decrypted apple pay payment data for the token like cryptogram, eci indicator.
Apple Pay payment data object which contains the cryptogram, eci_indicator and other data.
cryptogramstring^.*$Online payment cryptogram, as defined by 3D Secure. The pattern is defined by an external party and supports Unicode.
eci_indicatorstring^.*$ECI indicator, as defined by 3- Secure. The pattern is defined by an external party and supports Unicode.
emv_datastring^.*$Encoded Apple Pay EMV Payment Structure used for payments in China. The pattern is defined by an external party and supports Unicode.
pinstring^.*$Bank Key encrypted Apple Pay PIN. The pattern is defined by an external party and supports Unicode.
stored_credentialobjectProvides additional details to process a payment using a card that has been stored or is intended to be stored (also referred to as stored_credential or card-on-file).
Parameter compatibility:
payment_type=ONE_TIME is compatible only with payment_initiator=CUSTOMER.usage=FIRST is compatible only with payment_initiator=CUSTOMER.previous_transaction_reference or previous_network_transaction_reference is compatible only with payment_initiator=MERCHANT.previous_transaction_reference and previous_network_transaction_reference - can be present in the request.payment_initiatorrequiredstring"CUSTOMER", "MERCHANT"The person or party who initiated or triggered the payment.
payment_typerequiredstring"ONE_TIME", "RECURRING", "UNSCHEDULED"Indicates the type of the stored payment_source payment.
usagestring"FIRST", "SUBSEQUENT", "DERIVED""DERIVED"Indicates if this is a first or subsequent payment using a stored payment source (also referred to as stored credential or card on file).
previous_network_transaction_referenceobjectReference values used by the card network to identify a transaction.
idrequiredstring^[a-zA-Z0-9-_@.:&+=*^'~#!$%()]+$Transaction reference id returned by the scheme. For Visa and Amex, this is the "Tran id" field in response. For MasterCard, this is the "BankNet reference id" field in response. For Discover, this is the "NRID" field in response. The pattern we expect for this field from Visa/Amex/CB/Discover is numeric, Mastercard/BNPP is alphanumeric and Paysecure is alphanumeric with special character -.
datestring^[0-9]+$The date that the transaction was authorized by the scheme. This field may not be returned for all networks. MasterCard refers to this field as "BankNet reference date". For some specific networks, such as MasterCard and Discover, this date field is mandatory when the previous_network_transaction_reference_id is passed.
networkobject"VISA", "MASTERCARD", "DISCOVER", "AMEX", "SOLO", "JCB", "STAR", "DELTA", "SWITCH", "MAESTRO", "CB_NATIONALE", "CONFIGOGA", "CONFIDIS", "ELECTRON", "CETELEM", "CHINA_UNION_PAY", "DINERS", "ELO", "HIPER", "HIPERCARD", "RUPAY", "GE", "SYNCHRONY", "EFTPOS", "CARTE_BANCAIRE", "STAR_ACCESS", "PULSE", "NYCE", "ACCEL", "UNKNOWN"The card network or brand. Applies to credit, debit, gift, and payment cards.
Name of the card network through which the transaction was routed.
acquirer_reference_numberstring^[a-zA-Z0-9]+$Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks.
vault_idobject^[0-9a-zA-Z_-]+$The PayPal-generated ID for the vaulted payment source. This ID should be stored on the merchant's server so the saved payment source can be used for future transactions.
The PayPal-generated ID for the saved apple pay payment_source. This ID should be stored on the merchant's server so the saved payment source can be used for future transactions.
attributesobjectAdditional attributes associated with apple pay.
customerobjectThis object represents a merchant’s customer, allowing them to store contact details, and track all payments associated with the same customer.
idstring^[0-9a-zA-Z_-]+$The unique ID for a customer generated by PayPal.
email_addressobject^.*(?:[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])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-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 internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
Email address of the customer as provided to the merchant or on file with the merchant. Email Address is required if you are processing the transaction using PayPal Guest Processing which is offered to select partners and merchants.
phoneobjectThe phone information.
The phone number of the customer as provided to the merchant or on file with the merchant. The phone.phone_number supports only national_number.
phone_typestring"FAX", "HOME", "MOBILE", "OTHER", "PAGER"The phone type.
phone_numberrequiredobjectA structured representation of a phone number conforming to the international E.164 numbering plan format,requiring only the national_number field.
The phone number, in its canonical international E.164 numbering plan format. Supports only the national_number property.
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).
nameobjectThe name of the party.
The full name of the customer as provided to the merchant or on file with the merchant.
prefixstring^[\S\s]*$The prefix, or title, to the party's name.
given_namestring^[\S\s]*$When the party is a person, the party's given, or first, name.
surnamestring^[\S\s]*$When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
middle_namestring^[\S\s]*$When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
suffixstring^[\S\s]*$The suffix for the party's name.
full_namestring^[\S\s]*$When the party is a person, the party's full name.
vaultobjectBase vaulting specification. The object can be extended for specific use cases within each payment_source that supports vaulting.
store_in_vaultrequiredstring"ON_SUCCESS"Defines how and when the payment source gets vaulted.
experience_contextobjectCustomizes the payer experience during the approval process for the payment.
return_urlrequiredobjecturiDescribes the URL.
The URL where the customer is redirected after the customer approves the payment.
cancel_urlrequiredobjecturiDescribes the URL.
The URL where the customer is redirected after the customer cancels the payment.
google_payobjectInformation needed to pay using Google Pay.
Google Pay payment source, allows buyer to pay using Google Pay.
nameobject^[\S\s]*$The full name representation like Mr J Smith.
Name on the account holder associated with Google Pay.
email_addressobject^(?:[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 internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
The email address of the account holder associated with Google Pay.
phone_numberobjectA structured representation of a phone number conforming to the international E.164 numbering plan format,requiring the national_number field and optionally supporting the country_code.
The phone number of account holder, in its canonical international E.164 numbering plan format. Supports only the national_number property.
country_codestring^[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).
cardobjectThe payment card used to fund a Google Pay payment. Can be a credit or debit card.
The payment card information.
namestring^.{1,300}$The card holder's name as it appears on the card.
numberstring^[0-9]{13,19}$The primary account number (PAN) for the payment card.
expiryobject^[0-9]{4}-(0[1-9]|1[0-2])$The year and month, in ISO-8601 YYYY-MM date format. See Internet date and time format.
The card expiration year and month, in Internet date format.
last_digitsstring^[0-9]{2,4}$The last digits of the payment card.
typeobject"CREDIT", "DEBIT", "PREPAID", "STORE", "UNKNOWN"Type of card. i.e Credit, Debit and so on.
The payment card type.
brandobject"VISA", "MASTERCARD", "DISCOVER", "AMEX", "SOLO", "JCB", "STAR", "DELTA", "SWITCH", "MAESTRO", "CB_NATIONALE", "CONFIGOGA", "CONFIDIS", "ELECTRON", "CETELEM", "CHINA_UNION_PAY", "DINERS", "ELO", "HIPER", "HIPERCARD", "RUPAY", "GE", "SYNCHRONY", "EFTPOS", "CARTE_BANCAIRE", "STAR_ACCESS", "PULSE", "NYCE", "ACCEL", "UNKNOWN"The card network or brand. Applies to credit, debit, gift, and payment cards.
The card brand or network. Typically used in the response.
billing_addressobjectThe portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.
The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.
address_line_1string^[\S\s]*$The 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_2string^[\S\s]*$The second line of the address, for example, a suite or apartment number.
address_line_3string^[\S\s]*$The third line of the address, if needed. Examples include a street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.
admin_area_4string^[\S\s]*$The neighborhood, ward, or district. This is smaller than admin_area_level_3 or sub_locality. Value is:
admin_area_3string^[\S\s]*$The sub-locality, suburb, neighborhood, or district. This is smaller than admin_area_level_2. Value is:
admin_area_2string^[\S\s]*$A city, town, or village. Smaller than admin_area_level_1.
admin_area_1string^[\S\s]*$The 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_codestring^[\S\s]*$The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
country_coderequiredstring^([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.
address_detailsobjectThe non-portable additional address details include fine-grain address information for Compliance, Risk, and other scenarios. This isn't portable with common third-party and open source applications. This can include data that is redundant with core fields. For example, address_portable.address_line_1 is usually a combination of address_details.street_number, street_name, and street_type.
street_numberstring^[\S\s]*$The street number.
street_namestring^[\S\s]*$The street name. Just Drury in Drury Lane.
street_typestring^[\S\s]*$The street type. For example, avenue, boulevard, road, or expressway.
delivery_servicestring^[\S\s]*$The delivery service. Post office box, bag number, or post office name.
building_namestring^[\S\s]*$A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, Craven House.
sub_buildingstring^[\S\s]*$The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.
decrypted_tokenobjectDetails shared by Google for the merchant to be shared with PayPal. This is required to process the transaction using the Google Pay payment method.
The decrypted payload details for the Google Pay token.
message_idstring^.*$A unique ID that identifies the message in case it needs to be revoked or located at a later time.
message_expirationstring^\d{13}$Date and time at which the message expires as UTC milliseconds since epoch. Integrators should reject any message that's expired.
payment_methodrequiredstring"CARD"The type of the payment credential. Currently, only CARD is supported.
cardrequiredobjectGoogle Pay tokenized credit card used to pay.
namestring^.{1,300}$The card holder's name as it appears on the card.
numberrequiredstring^[0-9]{13,19}$The primary account number (PAN) for the payment card.
expiryrequiredobject^[0-9]{4}-(0[1-9]|1[0-2])$The year and month, in ISO-8601 YYYY-MM date format. See Internet date and time format.
The card expiration year and month, in Internet date format.
last_digitsstring^[0-9]{2,4}$The last digits of the payment card.
typeobject"CREDIT", "DEBIT", "PREPAID", "STORE", "UNKNOWN"Type of card. i.e Credit, Debit and so on.
The payment card type.
brandobject"VISA", "MASTERCARD", "DISCOVER", "AMEX", "SOLO", "JCB", "STAR", "DELTA", "SWITCH", "MAESTRO", "CB_NATIONALE", "CONFIGOGA", "CONFIDIS", "ELECTRON", "CETELEM", "CHINA_UNION_PAY", "DINERS", "ELO", "HIPER", "HIPERCARD", "RUPAY", "GE", "SYNCHRONY", "EFTPOS", "CARTE_BANCAIRE", "STAR_ACCESS", "PULSE", "NYCE", "ACCEL", "UNKNOWN"The card network or brand. Applies to credit, debit, gift, and payment cards.
The card brand or network. Typically used in the response.
billing_addressobjectThe portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.
The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.
address_line_1string^[\S\s]*$The 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_2string^[\S\s]*$The second line of the address, for example, a suite or apartment number.
address_line_3string^[\S\s]*$The third line of the address, if needed. Examples include a street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.
admin_area_4string^[\S\s]*$The neighborhood, ward, or district. This is smaller than admin_area_level_3 or sub_locality. Value is:
admin_area_3string^[\S\s]*$The sub-locality, suburb, neighborhood, or district. This is smaller than admin_area_level_2. Value is:
admin_area_2string^[\S\s]*$A city, town, or village. Smaller than admin_area_level_1.
admin_area_1string^[\S\s]*$The 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_codestring^[\S\s]*$The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
country_coderequiredstring^([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.
address_detailsobjectThe non-portable additional address details include fine-grain address information for Compliance, Risk, and other scenarios. This isn't portable with common third-party and open source applications. This can include data that is redundant with core fields. For example, address_portable.address_line_1 is usually a combination of address_details.street_number, street_name, and street_type.
street_numberstring^[\S\s]*$The street number.
street_namestring^[\S\s]*$The street name. Just Drury in Drury Lane.
street_typestring^[\S\s]*$The street type. For example, avenue, boulevard, road, or expressway.
delivery_servicestring^[\S\s]*$The delivery service. Post office box, bag number, or post office name.
building_namestring^[\S\s]*$A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, Craven House.
sub_buildingstring^[\S\s]*$The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.
authentication_methodrequiredstring"PAN_ONLY", "CRYPTOGRAM_3DS"Authentication Method which is used for the card transaction.
cryptogramstring^[\S\s]*$Base-64 cryptographic identifier used by card schemes to validate the token verification result. This is a conditionally required field if authentication_method is CRYPTOGRAM_3DS.
eci_indicatorstring^.*$Electronic Commerce Indicator may not always be present. It is only returned for tokens on the Visa card network. This value is passed through in the payment authorization request.
assurance_detailsobjectInformation about cardholder possession validation and cardholder identification and verifications (ID&V).
Information about what validation has been performed on the returned payment credentials.
account_verifiedbooleanfalseIf true, indicates that Cardholder possession validation has been performed on returned payment credential.
card_holder_authenticatedbooleanfalseIf true, indicates that identification and verifications (ID&V) was performed on the returned payment credential.If false, the same risk-based authentication can be performed as you would for card transactions. This risk-based authentication can include, but not limited to, step-up with 3D Secure protocol if applicable.
experience_contextobjectCustomizes the payer experience during the approval process for the payment.
return_urlrequiredobjecturiDescribes the URL.
The URL where the customer is redirected after the customer approves the payment.
cancel_urlrequiredobjecturiDescribes the URL.
The URL where the customer is redirected after the customer cancels the payment.
venmoobjectInformation needed to pay using Venmo.
Information needed to indicate that Venmo is being used to fund the payment.
vault_idobject^[0-9a-zA-Z_-]+$The PayPal-generated ID for the vaulted payment source. This ID should be stored on the merchant's server so the saved payment source can be used for future transactions.
The PayPal-generated ID for the saved Venmo wallet payment_source. This ID should be stored on the merchant's server so the saved payment source can be used for future transactions.
email_addressobject^.*(?:[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])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-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 internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
The email address of the payer.
experience_contextobjectCustomizes the buyer experience during the approval process for payment with Venmo.
Note: Partners and Marketplaces might configure shipping_preference during partner account setup, which overrides the request values.brand_namestring^.*$The business name of the merchant. The pattern is defined by an external party and supports Unicode.
shipping_preferencestring"GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS""GET_FROM_FILE"The location from which the shipping address is derived.
order_update_callback_configobjectCallBack Configuration that the merchant can provide to PayPal/Venmo.
Merchant provided Order Update callback configuration for Venmo Wallet.Venmo will call back merchant when the specified event occurs.we recommend merchants to pass both the shipping_options and shipping_address callback events. Not supported when shipping.type is specified or when 'application_context.shipping_preference' is set as 'NO_SHIPPING' or 'SET_PROVIDED_ADDRESS'.
callback_eventsrequiredarrayAn array of callback events merchant can subscribe to for the corresponding callback url.
itemsstring"SHIPPING_ADDRESS", "SHIPPING_OPTIONS"CallBack event.
callback_urlrequiredstringuriMerchant provided CallBack url.PayPal/Venmo will use this url to call the merchant back when the events occur .PayPal/Venmo expects a secured url usually in the https format.merchant can append the cart id or other params part of the url as query or path params.
user_actionstring"CONTINUE", "PAY_NOW""CONTINUE"Configures a Continue or Pay Now checkout flow.
attributesobjectAdditional attributes associated with the use of this Venmo Wallet.
Additional attributes associated with the use of this wallet.
customerobjectThis object represents a merchant’s customer, allowing them to store contact details, and track all payments associated with the same customer.
idstring^[0-9a-zA-Z_-]+$The unique ID for a customer generated by PayPal.
email_addressobject^.*(?:[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])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-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 internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
Email address of the customer as provided to the merchant or on file with the merchant. Email Address is required if you are processing the transaction using PayPal Guest Processing which is offered to select partners and merchants.
phoneobjectThe phone information.
The phone number of the customer as provided to the merchant or on file with the merchant. The phone.phone_number supports only national_number.
phone_typestring"FAX", "HOME", "MOBILE", "OTHER", "PAGER"The phone type.
phone_numberrequiredobjectA structured representation of a phone number conforming to the international E.164 numbering plan format,requiring only the national_number field.
The phone number, in its canonical international E.164 numbering plan format. Supports only the national_number property.
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).
nameobjectThe name of the party.
The full name of the customer as provided to the merchant or on file with the merchant.
prefixstring^[\S\s]*$The prefix, or title, to the party's name.
given_namestring^[\S\s]*$When the party is a person, the party's given, or first, name.
surnamestring^[\S\s]*$When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
middle_namestring^[\S\s]*$When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
suffixstring^[\S\s]*$The suffix for the party's name.
full_namestring^[\S\s]*$When the party is a person, the party's full name.
vaultobjectResource consolidating common request and response attirbutes for vaulting Venmo Wallet.
Attributes used to provide the instructions during vaulting of the Venmo Wallet.
cryptoobjectCrypto payment used to fund the transaction.
Indicates that Crypto Wallet is the payment source.
country_coderequiredobject^([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.
The two-character ISO 3166-1 purchase country code.
namerequiredobjectCrypto account holder name.
The name of the account holder associated with Crypto wallet.
prefixstring^[\S\s]*$The prefix, or title, to the account holder's name.
given_namerequiredstring^[\S\s]*$When the account holder is a person, the account holder's given, or first, name.
surnamerequiredstring^[\S\s]*$When the account holder is a person, the account holder's surname or family name. Also known as the last name. Required when the account holder is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
middle_namestring^[\S\s]*$When the account holder is a person, the account holder's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
experience_contextrequiredobjectCustomizes the payer experience during the approval process for the payment.
Customizes the payer experience during the approval process for the payment.
localeobject^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.
The BCP 47-formatted locale of pages that the PayPal payment 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_urlrequiredobjecturiDescribes the URL.
The URL where the customer is redirected after the customer approves the payment.
cancel_urlrequiredobjecturiDescribes the URL.
The URL where the customer is redirected after the customer cancels the payment.
application_contextobjectCustomizes the payer experience during the approval process for the payment with PayPal.
Note: Partners and Marketplaces might configurebrand_nameandshipping_preferenceduring partner account setup, which overrides the request values.
Customize the payer experience during the approval process for the payment with PayPal.
brand_namestring^[\S\s]*$DEPRECATED. The label that overrides the business name in the PayPal account on the PayPal site. The fields in application_context are now available in the experience_context object under the payment_source which supports them (eg. payment_source.paypal.experience_context.brand_name). Please specify this field in the experience_context object instead of the application_context object.
localeobject^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.
DEPRECATED. The BCP 47-formatted locale of pages that the PayPal payment 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. The fields in application_context are now available in the experience_context object under the payment_source which supports them (eg. payment_source.paypal.experience_context.locale). Please specify this field in the experience_context object instead of the application_context object.
landing_pagestring"LOGIN", "BILLING", "NO_PREFERENCE""NO_PREFERENCE"DEPRECATED. DEPRECATED. The type of landing page to show on the PayPal site for customer checkout. The fields in application_context are now available in the experience_context object under the payment_source which supports them (eg. payment_source.paypal.experience_context.landing_page). Please specify this field in the experience_context object instead of the application_context object. DEPRECATED
| See | Since Version |
|---|---|
| payment_source.paypal.experience_context.landing_page | 2.9 |
shipping_preferencestring"GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS""GET_FROM_FILE"DEPRECATED. DEPRECATED. The shipping preference:
application_context are now available in the experience_context object under the payment_source which supports them (eg. payment_source.paypal.experience_context.shipping_preference). Please specify this field in the experience_context object instead of the application_context object. DEPRECATED| See | Since Version |
|---|---|
| payment_source.paypal.experience_context.shipping_preference | 2.9 |
user_actionstring"CONTINUE", "PAY_NOW""CONTINUE"DEPRECATED. Configures a Continue or Pay Now checkout flow. The fields in application_context are now available in the experience_context object under the payment_source which supports them (eg. payment_source.paypal.experience_context.user_action). Please specify this field in the experience_context object instead of the application_context object.
payment_methodobjectThe customer and merchant payment preferences.
DEPRECATED. The customer and merchant payment preferences. The fields in application_context are now available in the experience_context object under the payment_source which supports them (eg. payment_source.paypal.experience_context.payment_method_selected). Please specify this field in the experience_context object instead of the application_context object..
payee_preferredstring"UNRESTRICTED", "IMMEDIATE_PAYMENT_REQUIRED""UNRESTRICTED"The merchant-preferred payment methods.
standard_entry_class_codestring"TEL", "WEB", "CCD", "PPD""WEB"NACHA (the regulatory body governing the ACH network) requires that API callers (merchants, partners) obtain the consumer’s explicit authorization before initiating a transaction. To stay compliant, you’ll need to make sure that you retain a compliant authorization for each transaction that you originate to the ACH Network using this API. ACH transactions are categorized (using SEC codes) by how you capture authorization from the Receiver (the person whose bank account is being debited or credited). PayPal supports the following SEC codes.
return_urlstringuriDEPRECATED. The URL where the customer is redirected after the customer approves the payment. The fields in application_context are now available in the experience_context object under the payment_source which supports them (eg. payment_source.paypal.experience_context.return_url). Please specify this field in the experience_context object instead of the application_context object.
cancel_urlstringuriDEPRECATED. The URL where the customer is redirected after the customer cancels the payment. The fields in application_context are now available in the experience_context object under the payment_source which supports them (eg. payment_source.paypal.experience_context.cancel_url). Please specify this field in the experience_context object instead of the application_context object.
stored_payment_sourceobjectProvides additional details to process a payment using a payment_source that has been stored or is intended to be stored (also referred to as stored_credential or card-on-file).
Parameter compatibility:
payment_type=ONE_TIME is compatible only with payment_initiator=CUSTOMER.usage=FIRST is compatible only with payment_initiator=CUSTOMER.previous_transaction_reference or previous_network_transaction_reference is compatible only with payment_initiator=MERCHANT.previous_transaction_reference and previous_network_transaction_reference - can be present in the request.DEPRECATED. Provides additional details to process a payment using a payment_source that has been stored or is intended to be stored (also referred to as stored_credential or card-on-file).
Parameter compatibility:
payment_type=ONE_TIME is compatible only with payment_initiator=CUSTOMER.usage=FIRST is compatible only with payment_initiator=CUSTOMER.previous_transaction_reference or previous_network_transaction_reference is compatible only with payment_initiator=MERCHANT.previous_transaction_reference and previous_network_transaction_reference - can be present in the request.stored_payment_source are now available in the stored_credential object under the payment_source which supports them (eg. payment_source.card.stored_credential.payment_initiator). Please specify this field in the payment_source object instead of the application_context object. DEPRECATED| See | Since Version |
|---|---|
| payment_source.card.stored_credential | 2.9 |
payment_initiatorrequiredstring"CUSTOMER", "MERCHANT"The person or party who initiated or triggered the payment.
payment_typerequiredstring"ONE_TIME", "RECURRING", "UNSCHEDULED"Indicates the type of the stored payment_source payment.
usagestring"FIRST", "SUBSEQUENT", "DERIVED""DERIVED"Indicates if this is a first or subsequent payment using a stored payment source (also referred to as stored credential or card on file).
previous_network_transaction_referenceobjectReference values used by the card network to identify a transaction.
idrequiredstring^[a-zA-Z0-9-_@.:&+=*^'~#!$%()]+$Transaction reference id returned by the scheme. For Visa and Amex, this is the "Tran id" field in response. For MasterCard, this is the "BankNet reference id" field in response. For Discover, this is the "NRID" field in response. The pattern we expect for this field from Visa/Amex/CB/Discover is numeric, Mastercard/BNPP is alphanumeric and Paysecure is alphanumeric with special character -.
datestring^[0-9]+$The date that the transaction was authorized by the scheme. This field may not be returned for all networks. MasterCard refers to this field as "BankNet reference date". For some specific networks, such as MasterCard and Discover, this date field is mandatory when the previous_network_transaction_reference_id is passed.
networkobject"VISA", "MASTERCARD", "DISCOVER", "AMEX", "SOLO", "JCB", "STAR", "DELTA", "SWITCH", "MAESTRO", "CB_NATIONALE", "CONFIGOGA", "CONFIDIS", "ELECTRON", "CETELEM", "CHINA_UNION_PAY", "DINERS", "ELO", "HIPER", "HIPERCARD", "RUPAY", "GE", "SYNCHRONY", "EFTPOS", "CARTE_BANCAIRE", "STAR_ACCESS", "PULSE", "NYCE", "ACCEL", "UNKNOWN"The card network or brand. Applies to credit, debit, gift, and payment cards.
Name of the card network through which the transaction was routed.
acquirer_reference_numberstring^[a-zA-Z0-9]+$Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks.