PayPal Payment Resource

The following is a detailed overview of the API specification.

Request

Main Fields

Field	Type	Description
amount	decimal	Use this field to update the amount of the PayPal payment resource.
amount_breakdown	object	The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
custom_field	string	Variable passed directly to PayPal via the API for your own tracking purposes. Customers do not see this value, but you can see it in reports from your PayPal console. Maximum 255 characters.
currency_iso_code	string	The currency for the PayPal payment resource. The three-letter alphabetic codes for the PayPal payment resource’s currency (e.g. `USD` for US dollars). Required if `amount` is provided.
description	string	Description of the PayPal order. Maximum 127 characters.
order_id	string	Use this field to include an order ID on the PayPal order. This field maps to the PayPal invoice number. PayPal invoice numbers must be unique in your PayPal business account. Maximum 127 characters.
payee_email	string	The PayPal account email for the business account into which funds will be deposited (if different from the PayPal account linked in your Braintree Control Panel).
payment_method_nonce	string	One-time-use reference to payment information provided by your customer, such as a PayPal account. Required.
line_items	array	The line items for this payment resource. It can include up to 249 line items.
shipping	object	Shipping address information associated with this PayPal payment method for this customer.
shipping_options	array	An array of shipping options that the merchant offers to the customer to ship or pick up their items.

Breakdown Amount Subfields

Field	Type	Description
discount	string	Total discount, cannot be negative.
handling	string	Handling fee, non-negative.
insurance	string	Insurance fee, non-negative.
item_total	string	Subtotal of items. Required if `unit_amount` is set.
shipping	string	Shipping fee, non-negative.
shipping_discount	string	Shipping discount, non-negative.
tax_total	string	Tax total. Required if `unit_tax_amount` is set.

Line Item Fields

Field	Type	Description
quantity	decimal	Item quantity. Only integer is allowed and it must be > 0. Required.
unit_amount	decimal	Price per unit. Max 2 decimals, ≥ 0. Required.
unit_tax_amount	decimal	Per-unit tax. Max 2 decimals.
name	string	Item name. Max 127 characters. Required.
description	string	Item description. Max 127 characters.
kind	string	`debit`Required.
product_code	string	Max 127 characters.
total_amount	decimal	Quantity × unit amount. Required.
url	string	Product information URL.
item_type	string	Optional: physical, digital, etc.
upc_code	string	UPC code, max 17 characters.
upc_type	string	UPC type, e.g., `UPC-A`, `UPC-E`, etc.

Shipping Fields

Field	Type	Description
first_name	string	The first name. The combined full name value must be less than or equal to 300 characters.
last_name	string	The last name. The combined full name value must be less than or equal to 300 characters.
street_address	string	Required. The street address. The street address value must be less than or equal to 300 characters.
extended_address	string	The extended address information—such as apartment or suite number. The extended address value must be less than or equal to 300 characters.
locality	string	Required. The locality/city. The locality value must be less than or equal to 120 characters.
postal_code	string	The postal code. Postal code must be less than 60 characters.
region	string	The state or province. The region value must be less than or equal to 300 characters.
country_code_alpha2	string	One of country_code_alpha2, country_code_alpha3, country_code_numeric, or country_name is required.
country_code_alpha3	string	One of country_code_alpha2, country_code_alpha3, country_code_numeric, or country_name is required.
country_code_numeric	string	One of country_code_alpha2, country_code_alpha3, country_code_numeric, or country_name is required.
country_name	string	One of country_code_alpha2, country_code_alpha3, country_code_numeric, or country_name is required.
international_phone	map	The phone number that belongs to the address that is structured with country code and national number.

Shipping Options Fields

Field	Type	Description
amount	string	Cost of the shipping option. Required.
id	string	Unique ID (≤ 127 chars). Required.
selected	boolean	Set to true for selected shipping option. Only one allowed. Required.
label	string	Description visible to customer. ≤ 127 chars. Required.
type	string	`SHIPPING`, `PICKUP_IN_STORE`, or `PICKUP_FROM_PERSON`

Response

Field	Type	Description
nonce	string	One-time-use token that references a payment method.
type	string	`PayPalAccount` is always returned for this response.
consumed	string	`false` is always returned, indicating that the nonce has been newly created.
description	string	`PayPal` is always returned for this response.

Validation Errors

The following is a list of validation errors that can be returned when attempting to update a PayPal payment resource. Each error includes an error code, error text, and description.

Code	Error Text	Description
97301	The provided payment method nonce is expired or consumed.	The payment method nonce has either expired or consumed. Nonces are deleted upon expiration (3 hours after generation).
97302	PayPal payment resource id is not supported.	The PayPal payment resource id stored in payment method nonce is not supported for the patch operations.
97303	Payment method nonce is required.	The payment method nonce is required for patch operations.
97304	Payee email is an invalid format.	Email must be a well-formed email address.
97305	Payee email is too long.	Maximum 254 characters.
97306	Expected a collection of line items but different format provided.	Expected a collection of line items but unrecognized data provided.
97307	Expected a hash object of line item but different format provided.	Expected a hash object of line item but unrecognized data provided.
97308	Expected a debit type for each line item.	Line item type must be 'debit'.
97309	Unit amount is an invalid format.	Unit amount must be formatted like '10', '10.00', or '10.0000'.
97310	Unit tax Amount is an invalid format.	Unit tax amount must be formatted like '10' or '10.00'. If the currency does not use decimal places, the unit tax amount can’t include decimal places.
97311	currency_iso_code is required with amount provided.	currency_iso_code is required when amount provided.
97312	currency_iso_code is not supported.	currency_iso_code is not supported by PayPal.
97313	Some of required fields are missing from shipping address.	Some of required fields are missing from shipping address.
97314	Amount breakdown is an invalid format.	Some of the fields in amount breakdown object are provided with invalid format.
97315	Expected a collection of shipping options but a different format was provided.	Expected a collection of shipping options but unrecognized data provided.
97316	Expected a collection of shipping options but none provided.	Expected a collection of shipping options but none provided.
97317	Expected id, label, and selected shipping option fields to be provided.	Expected a list of required fields to be provided including id, label, and selected.
97318	Shipping option type can only be SHIPPING, PICKUP_IN_STORE, or PICKUP_FROM_PERSON.	Shipping option type can only be SHIPPING, PICKUP_IN_STORE, or PICKUP_FROM_PERSON.
97319	Expected a unique id for each shipping option.	A unique id is required for each shipping option.
97320	Shipping option should have only one been selected.	The shipping options should have only been selected.
97321	Selected Shipping option amount should match shipping in amount breakdown object.	Selected Shipping option amount should match shipping in amount breakdown object.
97322	The accumulated item amount from line_items should match item_total in amount breakdown object.	The accumulated item amount from line_items should match item_total in amount breakdown object.
97323	The accumulated tax amount from line_items should match tax_total in amount breakdown object.	The accumulated tax amount from line_items should match tax_total in amount breakdown object.
97324	The PayPal patch payment resource call failed.	The PayPal patch payment resource call failed.
97325	The specified amount has an invalid format.	The specified amount has an invalid format.
97326	The shipping option id is too long.	The shipping option id is too long.
97327	The shipping option label is too long.	The shipping option label is too long.
97328	The combined shipping full name from first name and last name is too long.	The combined shipping full name from first name and last name is too long.
97329	The shipping street address is too long.	The shipping street address is too long.
97330	The shipping extended address is too long.	The shipping extended address is too long.
97331	The shipping locality is too long.	The shipping locality is too long.
97332	The shipping region is too long.	The Shipping region is too long.
97333	The country code value in shipping international phone object is too long.	The country code value in shipping international phone object is too long.
97334	The national number value in shipping international phone object is too long.	The national number value in shipping international phone object is too long.
97335	The shipping postal code is too long.	The shipping postal code is too long.
97336	The description is too long.	The description is too long.
97337	The custom field is too long.	The custom field is too long.
97338	The order id is too long.	The order id is too long.
97339	Contact preference value is invalid.	Valid values are "NO_CONTACT_INFO", "RETAIN_CONTACT_INFO" and "UPDATE_CONTACT_INFO".