NVP API Method and Field Reference

General Characteristics of Requests and Parameters

Parameters

The request parameter string follows the query component syntax defined in Uniform Resource Identifier (URI): Generic Syntax. Parameter names and their values can be upper- or lowercase. We show parameter names in uppercase for clarity. All values must be URL-encoded.

Multi-Value Fields

Fields that accept multiple values have names like this:

L_FIELDNAMEn

where L_ is literal, FIELDNAME is the name of the parameter, and n is an index number, starting at 0 and incremented by one for each value of the field. Index numbers must be sequential.

For example, if an order contains multiple items, you can add an item cost for each item using the L_AMTn parameter:

L_AMT0=4.95&L_AMT1=6.72&L_AMT2=7.95

PayPal-Supported Transactional Currencies

The following currencies are supported by PayPal for use in transactions.

Table A.1

PayPal-Supported Currencies and Currency Codes for Transactions

ISO-4217 Code	Currency
AUD	Australian Dollar
CAD	Canadian Dollar
CHF	Swiss Franc
CZK	Czech Koruna
DKK	Danish Krone
EUR	Euro
GBP	Pound Sterling
HKD	Hong Kong Dollar
HUF	Hungarian Forint
JPY	Japanese Yen
NOK	Norwegian Krone
NZD	New Zealand Dollar
PLN	Polish Zloty
SEK	Swedish Krona
SGD	Singapore Dollar
USD	U.S. Dollar

DoDirectPayment

DoDirectPayment Request

 

Table A.2

DoDirectPayment Parameters

Parameter	Description	Required?
METHOD	Name of the API: DoDirectPayment	Yes
PAYMENTACTION	How you want to obtain payment: l Authorization indicates that this payment is a basic authorization subject to settlement with PayPal Authorization & Capture. l Sale indicates that this is a final sale for which you are requesting payment. Character length and limit: Up to 13 single-byte alphabetic characters	Yes
IPADDRESS	IP address of the payer’s browser. Important: PayPal records this IP addresses as a means to detect possible fraud. Character length and limitations: 15 single-byte characters, including periods, for example: 255.255.255.255. Allowable values: any valid Internet Protocol address.	Yes
AMT	Total of order, including shipping, handling, and tax. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).	Yes
CREDITCARDTYPE	Type of credit card. Character length and limitations: Up to ten single-byte alphabetic characters. Allowable values: l Visa l MasterCard l Discover l Amex l Switch l Solo Important: If the credit card type is Switch or Solo, the value of PAYMENTACTION must be Authorization and the CURRENCYCODE must be GBP. In addition, either STARTDATE or ISSUENUMBER must be specified.	Yes
ACCT	Credit card number Character length and limitations: numeric characters only. No spaces or punctutation. Must conform with modulo and length required by each credit card type.	Yes
EXPDATE	Credit card expiration date. Format: MMYYYY Character length and limitations: Six single-byte numeric characters, including leading zero.	Yes
FIRSTNAME	Payer’s first name. Character length and limitations: 25 single-byte characters	Yes
LASTNAME	Payer’s last name. Character length and limitations: 25 single-byte characters	Yes
STREET	First street address. Character length and limitations: 100 single-byte characters	No
CITY	Name of city. Character length and limitations: 40 single-byte characters	No
STATE	State or province. Character length and limitations: 40 single-byte characters For state or province abbreviations, see “State and Province Abbreviations”.”	No
COUNTRYCODE	Country code. Character length and limitations: Two single-byte characters. For the list of country codes, see Appendix F, “Country Codes.”	No
ZIP	U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters	No
NOTIFYURL	Your URL for receiving Instant Payment Notification (IPN) about this transaction. Note: If you do not specify this URL in the request, the notification URL from your Merchant Profile is used, if one exists. Character length and limitations: 2,048 single-byte alphanumeric characters	No
CURRENCYCODE	A three-character currency code. Default: USD. This parameter accepts only the following currencies: l AUD – Australian Dollar l CAD – Canadian Dollar l EUR – Euro l GBP – Pound Sterling l JPY – Japanese Yen l USD – U.S. Dollar	No
ITEMAMT	Sum of cost of all items in this order. Limitations: The value must be a positive number and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Note: ITEMAMT is required if you specify L_AMTn.	No
SHIPPINGAMT	Total shipping costs for this order. Limitations: The value must be zero or greater and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Note: If you specify a value for SHIPPINGAMT, you must also specify a value for ITEMAMT.	No
HANDLINGAMT	Total handling costs for this order. Limitations: The value must be zero or greater and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Note: If you specify a value for HANDLINGAMT, you must specify a value for ITEMAMT.	No
TAXAMT	Sum of tax for all items in this order. Limitations: The value must be zero or greater and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Note: TAXAMT is required if you specify L_TAXAMTn.	No
DESC	Description of items the customer is purchasing. Character length and limitations: 127 single-byte alphanumeric characters	No
CUSTOM	A free-form field for your own use. Character length and limitations: 256 single-byte alphanumeric characters	No
INVNUM	Your own invoice or tracking number. Character length and limitations: 127 single-byte alphanumeric characters	No
BUTTONSOURCE	An identification code for use by third-party applications to identify transactions. Character length and limitations: 32 single-byte alphanumeric characters	No
L_NAMEn	Item name. Character length and limitations: 127 single-byte characters These parameters must be ordered sequentially beginning with 0 (for example L_NAME0, L_NAME1).	No
L_NUMBERn	Item number. Character length and limitations: 127 single-byte characters These parameters must be ordered sequentially beginning with 0 (for example L_NUMBER0, L_NUMBER1).	No
L_QTYn	Item quantity. Character length and limitations: Any positive integer These parameters must be ordered sequentially beginning with 0 (for example L_QTY0, L_QTY1).	No
L_TAXAMTn	Item sales tax. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). These parameters must be ordered sequentially beginning with 0 (for example L_TAXAMT0, L_TAXAMT1).	No
L_AMTn	Cost of item Limitations: Value can be positive, negative or zero and must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). These parameters must be ordered sequentially beginning with 0 (for example L_AMT0, L_AMT1). Note: If you specify a value for L_AMTn, you must specify a value for ITEMAMT.	No
CVV2	Card Verification Value, version 2. Note: Your Merchant Account settings determine whether this field is required. Character length for Visa, MasterCard, and Discover: exactly three digits. Character length for American Express: exactly four digits. Important: To comply with credit card processing regulations, once a transaction has been completed, you must not store the value of CVV2.	See description.
STARTDATE	Month and year that Switch or Solo card was issued. Format: MMYYYY Character length and limitations: Six single-byte numeric characters, including leading zero.	No
ISSUENUMBER	Issue number of Switch or Solo card. Character length: two numeric digits maximum.	No
EMAIL	Email address of payer. Character length and limitations: 127 single-byte characters	No
STREET2	Second street address. Character length and limitations: 100 single-byte characters	No
PHONENUM	Phone number. Character length and limit: 20 single-byte characters	No
RETURNFMFDETAILS	Flag to indicate whether you want the results returned by Fraud Management Filters. By default, you do not receive this information. l 0 - do not receive FMF details (default) l 1 - receive FMF details	No
Ship to Address	Optional shipping address. The parameters for the optional Ship to Address are described in Table A.3, “Ship to Address (Optional).” Important: Ship to Address is optional, but if you include it, certain fields are required.	No

Table A.3

Ship to Address (Optional)

Parameter	Description	Required?
SHIPTONAME	Person’s name associated with this address. Character length and limitations: 32 single-byte characters	Yes
SHIPTOSTREET	First street address. Character length and limitations: 100 single-byte characters	Yes
SHIPTOCITY	Name of city. Character length and limitations: 40 single-byte characters	Yes
SHIPTOSTATE	State or province. Character length and limitations: 40 single-byte characters For state or province abbreviations, see “State and Province Abbreviations”.” Required for US addresses only.	No
SHIPTOZIP	U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters	Yes
SHIPTOCOUNTRYCODE	Country code. Character limit: Two single-byte characters For the list of country codes, see Appendix F, “Country Codes.”	Yes
SHIPTOSTREET2	Second street address. Character length and limitations: 100 single-byte characters	No
SHIPTOPHONENUM	Phone number. Character length and limit: 20 single-byte characters	No

State and Province Abbreviations

The following table contains abbreviations for Canadian provinces and U.S. states. Enter these values in STATE or SHIPTOSTATE parameter.

 

Table A.4

Abbreviations for Canadian Provinces and U.S. States

Canadian Province or U.S. State	Abbreviation
Alberta	AB
British Columbia	BC
Manitoba	MB
New Brunswick	NB
Newfoundland and Labrador	NL
Northwest Territories	NT
Nova Scotia	NS
Nunavut	NU
Ontario	ON
Prince Edward Island	PE
Quebec	QC
Saskatchewan	SK
Yukon	YT
Alabama	AL
Alaska	AK
American Samoa	AS
Arizona	AZ
Arkansas	AR
California	CA
Colorado	CO
Connecticut	CT
Delaware	DE
District of Columbia	DC
Federated States of Micronesia	FM
Florida	FL
Georgia	GA
Guam	GU
Hawaii	HI
Idaho	ID
Illinois	IL
Indiana	IN
Iowa	IA
Kansas	KS
Kentucky	KY
Louisiana	LA
Maine	ME
Marshall Islands	MH
Maryland	MD
Massachusetts	MA
Michigan	MI
Minnesota	MN
Mississippi	MS
Missouri	MO
Montana	MT
Nebraska	NE
Nevada	NV
New Hampshire	NH
New Jersey	NJ
New Mexico	NM
New York	NY
North Carolina	NC
North Dakota	ND
Northern Mariana Islands	MP
Ohio	OH
Oklahoma	OK
Oregon	OR
Palau	PW
Pennsylvania	PA
Puerto Rico	PR
Rhode Island	RI
South Carolina	SC
South Dakota	SD
Tennessee	TN
Texas	TX
Utah	UT
Vermont	VT
Virgin Islands	VI
Virginia	VA
Washington	WA
West Virginia	WV
Wisconsin	WI
Wyoming	WY
Armed Forces Americas	AA
Armed Forces	AE
Armed Forces Pacific	AP

DoDirectPayment Response

 

Table A.5

DoDirectPayment Response Fields

Field	Description
AMT	This value is the amount of the payment as specified by you on DoDirectPaymentRequest.
AVSCODE	Address Verification System response code. Character limit: One single-byte alphanumeric character See “AVS Response Codes”.”
CVV2MATCH	Result of the CVV2 check by PayPal. See “CVV2 Response Codes”.”
TRANSACTIONID	Unique transaction ID of the payment. Note: If the PaymentAction of the request was Authorization, the value of TransactionID is your AuthorizationID for use with the Authorization & Capture APIs. Character length and limitations: 19 single-byte characters
L_FMFfilterIDn	Filter ID, including the filter type, which is either ACCEPT or DENY, and the entry number, starting from 0.
L_FMFfilterNAMEn	Filter name, including the filter type, which is either ACCEPT or DENY, and the entry number, starting from 0.

AVS Response Codes

The following tables list the AVS response codes.

 

Table A.6

AVS Response Codes for Visa, MasterCard, Discover, and American Express

AVS Code	Meaning	Matched Details
A	Address	Address only (no ZIP)
B	International “A”	Address only (no ZIP)
C	International “N”	None Note: The transaction is declined.
D	International “X”	Address and Postal Code
E	Not allowed for MOTO (Internet/Phone) transactions	Not applicable Note: The transaction is declined.
F	UK-specific “X”	Address and Postal Code
G	Global Unavailable	Not applicable
I	International Unavailable	Not applicable
N	No	None Note: The transaction is declined.
P	Postal (International “Z”)	Postal Code only (no Address)
R	Retry	Not applicable
S	Service not Supported	Not applicable
U	Unavailable	Not applicable
W	Whole ZIP	Nine-digit ZIP code (no Address)
X	Exact match	Address and nine-digit ZIP code
Y	Yes	Address and five-digit ZIP
Z	ZIP	Five-digit ZIP code (no Address)
All others	Error	Not applicable

 

Table A.7

AVS Response Codes for Switch and Solo

0	All the address information matched.	All information matched
1	None of the address information matched.	None Note: The transaction is declined.
2	Part of the address information matched.	Partial
3	The merchant did not provide AVS information. Not processed.	Not applicable
4	Address not checked, or acquirer had no response. Service not available.	Not applicable
Null	No AVS response was obtained. Default value of field.	Not applicable

CVV2 Response Codes

The following tables list the CVV2 response codes.

 

Table A.8

CVV2 Response Codes for Visa, MasterCard, Discover, and American Express

CVV2 Code	Meaning	Matched Details
M	Match	CVV2
N	No match	None
P	Not processed	Not applicable
S	Service not supported	Not applicable
U	Service not available	Not applicable
X	No response	Not applicable

 

Table A.9

CVV2 Response Codes for Switch and Solo

0	Matched	CVV2
1	No match	None
2	The merchant has not implemented CVV2 code handling	Not applicable
3	Merchant has indicated that CVV2 is not present on card	Not applicable
4	Service not available	Not applicable
All others	Error	Not applicable

Express Checkout

IMPORTANT:

To use SetExpressCheckout for recurring payments, you must set the VERSION parameter to 50.0 in your NVP API calls.

SetExpressCheckout Request

 

Table A.10

SetExpressCheckout Request Parameters

Parameter	Description	Required
METHOD	Name of the API: SetExpressCheckout	Yes
RETURNURL	URL to which the customer’s browser is returned after choosing to pay with PayPal. Note: PayPal recommends that the value be the final review page on which the customer confirms the order and payment or billing agreement. Character length and limitations: no limit.	Yes
CANCELURL	URL to which the customer is returned if he does not approve the use of PayPal to pay you. Note: PayPal recommends that the value be the original page on which the customer chose to pay with PayPal or establish a billing agreement. Character length and limitations: no limit	Yes
AMT	The total cost of the transaction to the customer. If shipping cost and tax charges are known, include them in this value; if not, this value should be the current sub-total of the order. If the transaction includes one or more one-time purchases, this field must be equal to the sum of the purchases. If the transaction does not include a one-time purchase, this field can be set to 0. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).	Yes
CURRENCYCODE	A three-character currency code for one of the currencies listed in PayPal-Supported Transactional Currencies. Default: USD.	No
MAXAMT	The expected maximum total amount of the complete order, including shipping cost and tax charges. If the transaction does not include a one-time purchase, this field is ignored. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).	No
PAYMENTACTION	How you want to obtain payment: l Sale indicates that this is a final sale for which you are requesting payment. l Authorization indicates that this payment is a basic authorization subject to settlement with PayPal Authorization & Capture. l Order indicates that this payment is an order authorization subject to settlement with PayPal Authorization & Capture. If the transaction does not include a one-time purchase, this field is ignored. Note: You cannot set this value to Sale in SetExpressCheckout request and then change this value to Authorization or Order on the final API DoExpressCheckoutPayment request. If the value is set to Authorization or Order in SetExpressCheckout, the value may be set to Sale or the same value (either Authorization or Order) in DoExpressCheckoutPayment. Character length and limit: Up to 13 single-byte alphabetic characters Default value: Sale	No
EMAIL	Email address of the buyer as entered during checkout. PayPal uses this value to pre-fill the PayPal membership sign-up portion of the PayPal login page. Character length and limit: 127 single-byte alphanumeric characters	No
DESC	Description of items the customer is purchasing. Character length and limitations: 127 single-byte alphanumeric characters	No
CUSTOM	A free-form field for your own use, such as a tracking number or other value you want PayPal to return on GetExpressCheckoutDetails response and DoExpressCheckoutPayment response. Character length and limitations: 256 single-byte alphanumeric characters	No
INVNUM	Your own unique invoice or tracking number. PayPal returns this value to you on DoExpressCheckoutPayment response. If the transaction does not include a one-time purchase, this field is ignored. Character length and limitations: 127 single-byte alphanumeric characters	No
REQCONFIRMSHIPPING	The value 1 indicates that you require that the customer’s shipping address on file with PayPal be a confirmed address. Note: Setting this field overrides the setting you have specified in your Merchant Account Profile. Character length and limitations: One single-byte numeric character. Allowable values: 0, 1 Default: 0	No
NOSHIPPING	The value 1 indicates that on the PayPal pages, no shipping address fields should be displayed whatsoever. Character length and limitations: One single-byte numeric character. Allowable values: 0, 1 Default: 0	No
ADDROVERRIDE	The value 1 indicates that the PayPal pages should display the shipping address set by you in this SetExpressCheckout request, not the shipping address on file with PayPal for this customer. Displaying the PayPal street address on file does not allow the customer to edit that address. Character length and limitations: One single-byte numeric character. Allowable values: 0, 1 Default: 0	No
TOKEN	A timestamped token by which you identify to PayPal that you are processing this payment with Express Checkout. Note: The token expires after three hours. If you set the token in the SetExpressCheckout request, the value of the token in the response is identical to the value in the request. Character length and limitations: 20 single-byte characters Allowable values: See the description of TOKEN in Table A.12, “SetExpressCheckout Response Fields.”	No
LOCALECODE	Locale of pages displayed by PayPal during Express Checkout. Character length and limitations: Any two-character country code. The following two-character country codes are supported by PayPal: l AT l AU l BE l CA l CH l CN l DE l ES l FR l GB l IT l NL l PL l US Any other value will default to US. Note: For the list of country codes, see Appendix F, “Country Codes.”	No
PAGESTYLE	Sets the Custom Payment Page Style for payment pages associated with this button/link. This value corresponds to the HTML variable page_style for customizing payment pages. The value is the same as the Page Style Name you chose when adding or editing the page style from the Profile subtab of the My Account tab of your PayPal account. Character length and limitations: 30 single-byte alphabetic characters.	No
HDRIMG	URL for the image you want to appear at the top left of the payment page. The image has a maximum size of 750 pixels wide by 90 pixels high. PayPal recommends that you provide an image that is stored on a secure (https) server. If you do not specify an image, the business name is displayed. Character length and limit: 127 single-byte alphanumeric characters	No
HDRBORDERCOLOR	Sets the border color around the header of the payment page. The border is a 2-pixel perimeter around the header space, which is 750 pixels wide by 90 pixels high. By default, the color is black. Character length and limitations: Six character HTML hexadecimal color code in ASCII	No
HDRBACKCOLOR	Sets the background color for the header of the payment page. By default, the color is white. Character length and limitation: Six character HTML hexadecimal color code in ASCII	No
PAYFLOWCOLOR	Sets the background color for the payment page. By default, the color is white. Character length and limitation: Six character HTML hexadecimal color code in ASCII	No
CHANNELTYPE	Type of channel: l Merchant: non-auction seller l eBayItem: eBay auction If the transaction does not include a one-time purchase, this field is ignored.	No
SOLUTIONTYPE	Type of checkout flow: l Sole: Express Checkout for auctions l Mark: normal Express Checkout If the transaction does not include a one-time purchase, this field is ignored.	No
GIROPAYSUCCESS URL	The URL on the merchant site to redirect to after a successful giropay payment. . Use this field only if you are using giropay or bank transfer payment methods in Germany.	No
GIROPAYCANCELURL	The URL on the merchant site to redirect to after a giropay or bank transfer payment is cancelled or fails. Use this field only if you are using giropay or bank transfer payment methods in Germany.	No
BANKTXNPENDING URL	The URL on the merchant site to transfer to after a bank transfer payment. Use this field only if you are using giropay or bank transfer payment methods in Germany.	No
L_BILLINGTYPEn	Type of billing agreement. For recurring payments, this field is required and must be set to RecurringPayments.	See description
L_BILLING AGREEMENT DESCRIPTIONn	Description of goods or services associated with the billing agreement. PayPal recommends that you provide a brief summary of the terms & conditions of the billing agreement.	No
L_CUSTOMn	Custom annotation field for your own use. Note: This field is ignored for recurring payments.	No
L_PAYMENTTYPEn	Specifies type of PayPal payment you require for the billing agreement, which is one of the following values. l Any l InstantOnly Note: This field is ignored for recurring payments.	No
See Table A.11	Optional shipping address. The parameters for the optional Ship to Address are described in Table A.11, “Ship to Address (Optional).” Important: Ship to Address is optional, but if you include it, certain fields are required.	No

Table A.11

Ship to Address (Optional)

Parameter	Description	Required
SHIPTONAME	Person’s name associated with this shipping address. Character length and limitations: 32 single-byte characters	Yes
SHIPTOSTREET	First street address. Character length and limitations: 100 single-byte characters	Yes
SHIPTOCITY	Name of city. Character length and limitations: 40 single-byte characters	Yes
SHIPTOSTATE	State or province. Character length and limitations: 40 single-byte characters Required for US addresses only.	No
SHIPTOCOUNTRYCODE	Country code. Character limit: Two single-byte characters. For the list of country codes, see Appendix F, “Country Codes.”	Yes
SHIPTOZIP	U.S. Zip code or other country-specific postal code. Character length and limitations: 20 single-byte characters	Yes
SHIPTOSTREET2	Second street address. Character length and limitations: 100 single-byte characters	No
PHONENUM	Phone number. Character length and limit: 20 single-byte characters	No

SetExpressCheckout Response

 

Table A.12

SetExpressCheckout Response Fields

Parameter	Description
TOKEN	A timestamped token by which you identify to PayPal that you are processing this payment with Express Checkout. Note: The token expires after three hours. If you set the token in the SetExpressCheckout request, the value of the token in the response is identical to the value in the request. Character length and limitations: 20 single-byte characters

Redirecting the Customer’s Browser to PayPal Login Page

After you receive a successful response from SetExpressCheckout, add the TOKEN from SetExpressCheckout response as a name/value pair to the following URL, and redirect your customer’s browser to it:

https://www.paypal.com/cgi-bin/webscr?cmd=_express‑checkout&
token=value_from_SetExpressCheckoutResponse

For redirecting the customer’s browser to the PayPal login page, PayPal recommends that you use the HTTPS response 302 “Object Moved” with the URL above as the value of the Location header in the HTTPS response. Ensure that you use an SSL-enabled server to prevent browser warnings about a mix of secure and insecure graphics.

GetExpressCheckoutDetails Request

 

Table A.13

GetExpressCheckoutDetails Parameters

Parameter	Description	Required?
METHOD	Name of the API: GetExpressCheckoutDetails	Yes
TOKEN	A timestamped token, the value of which was returned by SetExpressCheckout response. Character length and limitations: 20 single-byte characters Allowable values: An unexpired token	Yes

GetExpressCheckoutDetails Response

 

Table A.14

GetExpressCheckoutDetails Response Fields

Field	Description
TOKEN	The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request. Character length and limitations: 20 single-byte characters Possible values: See the description of TOKEN in Table A.12, “SetExpressCheckout Response Fields.”
EMAIL	Email address of payer. Character length and limitations: 127 single-byte characters
PAYERID	Unique PayPal customer account identification number. Character length and limitations:13 single-byte alphanumeric characters.
PAYERSTATUS	Status of payer. Valid values are: l verified l unverified Character length and limitations: 10 single-byte alphabetic characters. Possible values: verified, unverified
SALUTATION	Payer’s salutation. Character length and limitations: 20 single-byte characters
FIRSTNAME	Payer’s first name. Character length and limitations: 25 single-byte characters
MIDDLENAME	Payer’s middle name. Character length and limitations: 25 single-byte characters
LASTNAME	Payer’s last name. Character length and limitations: 25 single-byte characters
SUFFIX	Payer’s suffix. Character length and limitations: 12 single-byte characters
COUNTRYCODE	Payer’s country of residence in the form of ISO standard 3166 two-character country codes. Character length and limitations: Two single-byte characters For the list of country codes, see Appendix F, “Country Codes.”
BUSINESS	Payer’s business name. Character length and limitations: 127 single-byte characters
SHIPTONAME	Person’s name associated with this address. Character length and limitations: 32 single-byte characters
SHIPTOSTREET	First street address. Character length and limitations: 100 single-byte characters
SHIPTOSTREET2	Second street address. Character length and limitations: 100 single-byte characters
SHIPTOCITY	Name of city. Character length and limitations: 40 single-byte characters
SHIPTOSTATE	State or province Character length and limitations: 40 single-byte characters
SHIPTOCOUNTRYCODE	Country code. Character limit: Two single-byte characters. For the list of country codes, see Appendix F, “Country Codes.”
SHIPTOZIP	U.S. Zip code or other country-specific postal code. Character length and limitations: 20 single-byte characters
ADDRESSSTATUS	Status of street address on file with PayPal
CUSTOM	A free-form field for your own use, as set by you in the Custom element of SetExpressCheckout request. Character length and limitations: 256 single-byte alphanumeric characters
INVNUM	Your own invoice or tracking number, as set by you in the element of the same name in SetExpressCheckout request . Character length and limitations: 127 single-byte alphanumeric characters
PHONENUM	Payer’s contact telephone number. Note: PayPal returns a contact telephone number only if your Merchant account profile settings require that the buyer enter one. Character length and limitations: Field mask is XXX-XXX-XXXX (for US numbers) or +XXX XXXXXXXX (for international numbers)
REDIRECTREQUIRED	Flag to indicate whether you need to redirect the customer to back to PayPal after completing the transaction. Note: Use this field only if you are using giropay or bank transfer payment methods in Germany.
BILLINGAGREEMENTACCEPTEDSTATUS	Whether or not the customer accepted the billing agreement. This value always returns Yes.

DoExpressCheckoutPayment Request

Request to obtain payment with PayPal Express Checkout.

IMPORTANT:

PayPal requires that a merchant using Express Checkout display to the customer the same amount that the merchant sends to PayPal in the AMT parameter with the DoExpressCheckoutPayment request API.

 

Table A.15

DoExpressCheckoutPayment Parameters

Parameter	Description	Req?
METHOD	Name of the API: DoExpressCheckoutPayment	Yes
TOKEN	The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request. Character length and limitations: 20 single-byte characters	Yes
PAYMENTACTION	How you want to obtain payment: l Sale indicates that this is a final sale for which you are requesting payment. l Authorization indicates that this payment is a basic authorization subject to settlement with PayPal Authorization & Capture. l Order indicates that this payment is an order authorization subject to settlement with PayPal Authorization & Capture. If the transaction does not include a one-time purchase, this field is ignored. Note: You cannot set this value to Sale in SetExpressCheckout request and then change this value to Authorization or Order on the final API DoExpressCheckoutPayment request. If the value is set to Authorization or Order in SetExpressCheckout, the value may be set to Sale or the same value (either Authorization or Order) in DoExpressCheckoutPayment. Character length and limit: Up to 13 single-byte alphabetic characters Default value: Sale Allowable Values: l Authorization l Order l Sale Default: The transaction resulting from DoExpressCheckoutPayment request will be a final sale..	Yes
PAYERID	Unique PayPal customer account identification number as returned by GetExpressCheckoutDetails response. Character length and limitations: 13 single-byte alphanumeric characters.	Yes
AMT	Total of order, including shipping, handling, and tax. Note: Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).	Yes
DESC	Description of items the customer is purchasing. Character length and limitations: 127 single-byte alphanumeric characters	No
CUSTOM	A free-form field for your own use. Character length and limitations: 256 single-byte alphanumeric characters	No
INVNUM	Your own invoice or tracking number. Character length and limitations: 127 single-byte alphanumeric characters	No
BUTTONSOURCE	An identification code for use by third-party applications to identify transactions. Character length and limitations: 32 single-byte alphanumeric characters	No
NOTIFYURL	Your URL for receiving Instant Payment Notification (IPN) about this transaction. IMPORTANT: If you do not specify this value in the request, the notification URL from your Merchant Profile is used, if one exists. Character length and limitations: 2,048 single-byte alphanumeric characters	No
ITEMAMT	Sum of cost of all items in this order. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Note: ITEMAMT is required if you specify a value for L_AMTn.	No
SHIPPINGAMT	Total shipping costs for this order. Note: Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD.	No
HANDLINGAMT	Total handling costs for this order. Note: Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD.	No
TAXAMT	Sum of tax for all items in this order. Note: Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. Note: TAXAMT is required if you specify a value for L_TAXAMTn.	No
CURRENCYCODE	A three-character currency code for one of the currencies listed in PayPal-Supported Transactional Currencies. Default: USD.	No
L_NAMEn	Item name. Character length and limitations: 127 single-byte characters These parameters must be ordered sequentially beginning with 0 (for example L_NAME0, L_NAME1).	No
L_NUMBERn	Item number. Character length and limitations: 127 single-byte characters These parameters must be ordered sequentially beginning with 0 (for example L_NUMBER0, L_NUMBER1).	No
L_QTYn	Item quantity. Character length and limitations: Any positive integer These parameters must be ordered sequentially beginning with 0 (for example L_QTY0, L_QTY1).	No
L_TAXAMTn	Item sales tax. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). These parameters must be ordered sequentially beginning with 0 (for example L_TAXAMT0, L_TAXAMT1).	No
L_AMTn	Cost of item Limitations: Value can be positive, negative or zero and must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). These parameters must be ordered sequentially beginning with 0 (for example L_AMT0, L_AMT1). Note: If you specify a value for L_AMTn, you must specify a value for ITEMAMT.	No
L_EBAYITEMNUMBERn	Auction item number Character length: 765 single-byte characters	No
L_EBAYITEMAUCTION TXNIDn	Auction transaction identification number Character length: 255 single-byte characters	No
L_EBAYITEMORDERIDn	Auction order identification number Character length: 64 single-byte characters	No
RETURNFMFDETAILS	Flag to indicate whether you want the results returned by Fraud Management Filters. By default, you do not receive this information. l 0 - do not receive FMF details (default) l 1 - receive FMF details	No

Table A.16

Optional Ship to Address

Parameter	Description	Required?
SHIPTONAME	Person’s name associated with this address. Character length and limitations: 32 single-byte characters	Yes
SHIPTOSTREET	First street address. Character length and limitations: 100 single-byte characters	Yes
SHIPTOCITY	Name of city. Character length and limitations: 40 single-byte characters	Yes
SHIPTOSTATE	State or province. Character length and limitations: 40 single-byte characters Required for US addresses only.	No
SHIPTOCOUNTRYCODE	Country code. Character limit: Two single-byte characters For the list of country codes, see Appendix F, “Country Codes.”	Yes
SHIPTOZIP	U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters	Yes
SHIPTOSTREET2	Second street address. Character length and limitations: 100 single-byte characters	No
SHIPTOPHONENUM	Phone number. Character length and limit: 20 single-byte characters	No

DoExpressCheckoutPayment Response

 

Table A.17

DoExpressCheckout Payment Response Fields

Field	Description
TOKEN	The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request. Character length and limitations:20 single-byte characters Allowable values: See the description of TOKEN in Table A.12, “SetExpressCheckout Response Fields.”
TRANSACTIONID	Unique transaction ID of the payment. Note: If the PaymentAction of the request was Authorization or Order, this value is your AuthorizationID for use with the Authorization & Capture APIs. Character length and limitations:19 single-byte characters Possible values: Transaction specific
TRANSACTIONTYPE	The type of transaction Character length and limitations:15 single-byte characters Possible values: l cart l express-checkout
PAYMENTTYPE	Indicates whether the payment is instant or delayed. Character length and limitations: Seven single-byte characters Possible values: l none l echeck l instant
ORDERTIME	Time/date stamp of payment Possible values: Transaction specific
AMT	The final amount charged, including any shipping and taxes from your Merchant Profile. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD. Possible Values: Transaction specific
CURRENCYCODE	A three-character currency code for one of the currencies listed in PayPay-Supported Transactional Currencies. Default: USD.
FEEAMT	PayPal fee amount charged for the transaction Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD. Possible values: Transaction specific
SETTLEAMT	Amount deposited in your PayPal account after a currency conversion. Possible values: Transaction specific
TAXAMT	Tax charged on the transaction. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD. Possible values: Transaction specific
EXCHANGERATE	Exchange rate if a currency conversion occurred. Relevant only if your are billing in their non-primary currency. If the customer chooses to pay with a currency other than the non-primary currency, the conversion occurs in the customer’s account. Character length and limitations: a decimal that does not exceed 17 characters, including decimal point Possible values: Transaction specific
PAYMENTSTATUS	Status of the payment: Completed: The payment has been completed, and the funds have been added successfully to your account balance. Pending: The payment is pending. See the PendingReason element for more information.
PENDINGREASON	The reason the payment is pending: l none: No pending reason l address: The payment is pending because your customer did not include a confirmed shipping address and your Payment Receiving Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile. l echeck: The payment is pending because it was made by an eCheck that has not yet cleared. l intl: The payment is pending because you hold a non-U.S. account and do not have a withdrawal mechanism. You must manually accept or deny this payment from your Account Overview. l multi-currency: You do not have a balance in the currency sent, and you do not have your Payment Receiving Preferences set to automatically convert and accept this payment. You must manually accept or deny this payment. l verify: The payment is pending because you are not yet verified. You must verify your account before you can accept this payment. l other: The payment is pending for a reason other than those listed above. For more information, contact PayPal customer service.
REASONCODE	The reason for a reversal if TransactionType is reversal: l none: No reason code l chargeback: A reversal has occurred on this transaction due to a chargeback by your customer. l guarantee: A reversal has occurred on this transaction due to your customer triggering a money-back guarantee. l buyer-complaint: A reversal has occurred on this transaction due to a complaint about the transaction from your customer. l refund: A reversal has occurred on this transaction because you have given the customer a refund. l other: A reversal has occurred on this transaction due to a reason not listed above.
REDIRECTREQUIRED	Flag to indicate whether you need to redirect the customer to back to PayPal after completing the transaction. Note: Use this field only if you are using giropay or bank transfer payment methods in Germany.
L_FMFfilterIDn	Filter ID, including the filter type, which is either ACCEPT or DENY, and the entry number, starting from 0.
L_FMFfilterNAMEn	Filter name, including the filter type, which is either ACCEPT or DENY, and the entry number, starting from 0.

Authorization & Capture

DoAuthorization

 

Table A.18

DoAuthorization Parameters

Parameter	Description	Required?
METHOD	Name of the API: DoAuthorization	Yes
TRANSACTIONID	The value of the order’s transaction identification number returned by PayPal. Character length and limits: 19 single-byte characters maximum	Yes
AMT	Amount to authorize. Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
TRANSACTIONENTITY	Type of transaction to authorize. The only allowable value is Order, which means that the transaction represents a customer order that can be fulfilled over 29 days.	No
CURRENCYCODE	A three-character currency code for one of the currencies listed in PayPal-Supported Transactional Currencies. Default: USD.	No

Table A.19

DoAuthorization Response Fields

Field	Description
TRANSACTIONID	An authorization identification number.
AMT	The amount you specified in the request.

DoCapture

 

Table A.20

DoCapture Parameters

Parameter	Description	Required?
METHOD	Name of API: DoCapture	Yes
AUTHORIZATIONID	The authorization identification number of the payment you want to capture. This is the transaction id returned from DoExpressCheckoutPayment or DoDirectPayment. Character length and limits: 19 single-byte characters maximum.	Yes
AMT	Amount to capture. Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).	Yes
CURRENCYCODE	A three-character currency code for one of the currencies listed in PayPal-Supported Transactional Currencies. Default: USD.	No
COMPLETETYPE	The value Complete indicates that this the last capture you intend to make. The value NotComplete indicates that you intend to make additional captures. Note: If Complete, any remaining amount of the original authorized transaction is automatically voided and all remaining open authorizations are voided. Character length and limits: 12 single-byte alphanumeric characters	Yes
INVNUM	Your invoice number or other identification number that is displayed to the merchant and customer in his transaction history. Note: This value on DoCapture will overwrite a value previously set on DoAuthorization. Note: The value is recorded only if the authorization you are capturing is an order authorization, not a basic authorization. Character length and limits: 127 single-byte alphanumeric characters	No
NOTE	An informational note about this settlement that is displayed to the payer in email and in his transaction history. Character length and limits: 255 single-byte characters	No
SOFTDESCRIPTOR	The soft descriptor is a per transaction description of the payment that is passed to the consumer’s credit card statement. If a value for the soft descriptor field is provided, the full descriptor displayed on the customer’s statement has the following format: <PP * | PAYPAL *><Merchant descriptor as set in the Payment Receiving Preferences><1 space><soft descriptor> The soft descriptor can contain only the following characters: l Alphanumeric characters l - (dash) l * (asterisk) l . (period) l {space} If you use any other characters (such as “,”), an error code is returned. The soft descriptor does not include the phone number, which can be toggled between the merchant’s customer service number and PayPal’s customer service number. The maximum length of the total soft descriptor is 22 characters. Of this, either 4 or 8 characters are used by the PayPal prefix shown in the data format. Thus, the maximum length of the soft descriptor passed in the API request is: 22 - len(<PP * | PAYPAL *>) - len(<Descriptor set in Payment Receiving Preferences> + 1) For example, assume the following conditions: l The PayPal prefix toggle is set to PAYPAL * in PayPal’s admin tools l The merchant descriptor set in the Payment Receiving Preferences is set to EBAY. l The soft descriptor is passed in as JanesFlowerGifts LLC The resulting descriptor string on the credit card would be: PAYPAL *EBAY JanesFlow	No

Table A.21

DoCapture Response Fields

Field	Description
AUTHORIZATIONID	The authorization identification number you specified in the request. Character length and limits: 19 single-byte characters maximum
TRANSACTIONID	Unique transaction ID of the payment. Character length and limitations: 17 single-byte characters
PARENTTRANSACTIONID	Parent or related transaction identification number. This field is populated for the following transaction types: l Reversal. Capture of an authorized transaction. l Reversal. Reauthorization of a transaction. l Capture of an order. The value of ParentTransactionID is the original OrderID. l Authorization of an order. The value of ParentTransactionID is the original OrderID. l Capture of an order authorization. l Void of an order. The value of ParentTransactionID is the original OrderID. Character length and limits: 16 digits in xxxx-xxxx-xxxx-xxxx format
RECEIPTID	Receipt identification number Character length and limits: 16 digits in xxxx-xxxx-xxxx-xxxx format
TRANSACTIONTYPE	The type of transaction l cart l express-checkout Character length and limitations: 15 single-byte characters
PAYMENTTYPE	Indicates whether the payment is instant or delayed. Character length and limitations: Seven single-byte characters
ORDERTIME	Time/date stamp of payment. For example: 2006-08-15T17:23:15Z.
AMT	The final amount charged, including any shipping and taxes from your Merchant Profile.
FEEAMT	PayPal fee amount charged for the transaction
SETTLEAMT	Amount deposited in your PayPal account if there is a currency conversion.
TAXAMT	Tax charged on the transaction, if any
EXCHANGERATE	Exchange rate if a currency conversion occurred. Relevant only if you are billing in the customer’s non-primary currency. If the customer chooses to pay with a currency other than the non-primary currency, the conversion occurs in the customer’s account. Character length and limitations: a decimal multiplier
PAYMENTSTATUS	Status of the payment. The status of the payment: l None: No status l Canceled-Reversal: This means a reversal has been canceled. For example, you won a dispute with the customer, and the funds for the transaction that was reversed have been returned to you. l Completed: The payment has been completed, and the funds have been added successfully to your account balance. l Denied: You denied the payment. This happens only if the payment was previously pending because of possible reasons described for the PendingReason element. l Expired: the authorization period for this payment has been reached. l Failed: The payment has failed. This happens only if the payment was made from your customer’s bank account. l Pending: The payment is pending. See the PendingReason field for more information. l Refunded: You refunded the payment. l Reversed: A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer. The reason for the reversal is specified in the ReasonCode element. l Processed: A payment has been accepted. l Voided: An authorization for this transaction has been voided.

DoReauthorization

 

Table A.22

DoReauthorization Request Parameters

Parameter	Description	Required?
METHOD	Name of API: DoReauthorization	Yes
AUTHORIZATIONID	The value of a previously authorized transaction identification number returned by PayPal. Character length and limits: 19 single-byte characters maximum	Yes
AMT	Amount to reauthorize. Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).	Yes
CURRENCYCODE	A three-character currency code for one of the currencies listed in PayPal-Supported Transactional Currencies. Default: USD.	No

Table A.23

DoReauthorization Response Fields

Field	Description
AUTHORIZATIONID	A new authorization identification number. Character length and limits:19 single-byte characters

DoVoid

 

Table A.24

DoVoid Request Parameters

Parameter	Description	Required?
METHOD	Name of API: DoVoid	Yes
AUTHORIZATIONID	The value of the original authorization identification number returned by a PayPal product. Important: If you are voiding a transaction that has been reauthorized, use the ID from the original authorization, and not the reauthorization. Character length and limits: 19 single-byte characters	Yes
NOTE	An informational note about this void that is displayed to the payer in email and in his transaction history. Character length and limits: 255 single-byte characters	No

Table A.25

DoVoid Response Fields

Field	Description
AUTHORIZATIONID	The authorization identification number you specified in the request. Character length and limits: 19 single-byte characters

RefundTransaction

 

Table A.26

RefundTransaction Request Parameters

Parameter	Description	Required?
METHOD	Name of API call: RefundTransaction	Yes
TRANSACTIONID	Unique identifier of a transaction Character length and limitations: 17 single-byte alphanumeric characters	Yes
REFUNDTYPE	Type of refund you are making l Other l Full l Partial	Yes
AMT	Refund amount. Amount is required if RefundType is Partial. Note: If RefundType is Full, do not set Amount.	No
NOTE	Custom memo about the refund. Character length and limitations: 255 single-byte alphanumeric characters	No

Table A.27

DoRefund Response Fields

Field	Description
REFUNDTRANSACTIONID	Unique transaction ID of the refund. Character length and limitations:17 single-byte characters
NETREFUNDAMT	Amount subtracted from PayPal balance of original recipient of payment to make this refund
FEEREFUNDAMT	Transaction fee refunded to original recipient of payment
GROSSREFUNDAMT	Amount of money refunded to original payer

TransactionSearch

With TransactionSearch you must always set the StartDate field. Some other behavior:

l	Setting TransactionID overrides all other fields (even the required StartDate field).

l	The effect of setting other elements is additive or can alter the search criteria.

TransactionSearch returns up to 100 matches. Partial matches are displayed. For example, setting the TransactionSearchRequest FirstName to “Jess” returns results such as “Jessica” and “Jesse”.

The most important returned element is TransactionID, which you can pass to GetTransactionDetails in order to retrieve all available information about a specific transaction.

Table A.28

TransactionSearch Request Parameters

Parameter	Description	Required
METHOD	Name of API call: TransactionSearch	Yes
STARTDATE	The earliest transaction date at which to start the search. No wildcards are allowed. The value must be in UTC/GMT format.	Yes
ENDDATE	The latest transaction date to be included in the search	No
EMAIL	Search by the buyer’s email address Character length and limitations: 127 single-byte alphanumeric characters	No
RECEIVER	Search by the receiver’s email address. If the merchant account has only one email, this is the primary email. Can also be a non-primary email.	No
RECEIPTID	Search by the PayPal Account Optional receipt ID	No
TRANSACTIONID	Search by the transaction ID. The returned results are from the merchant’s transaction records. Character length and limitations: 19 single-byte characters maximum	No
INVNUM	Search by invoice identification key, as set by you for the original transaction. This field searches the records for items sold by the merchant, not the items purchased. IMPORTANT: No wildcards are allowed. Character length and limitations: 127 single-byte characters maximum	No
ACCT	Search by credit card number, as set by you for the original transaction. This field searches the records for items sold by the merchant, not the items purchased. IMPORTANT: No wildcards are allowed. Character length and limitations: Must be at least 11 and no more than 25 single-byte numeric characters maximum. Special punctuation, such as dashes or spaces, is ignored.	No
SALUTATION	Buyer’s salutation Character length and limitations: 20 single-byte characters	No
FIRSTNAME	Buyer’s first name Character length and limitations: 25 single-byte characters	No
MIDDLENAME	Buyer’s middle name Character length and limitations: 25 single-byte characters	No
LASTNAME	Buyer’s last name Character length and limitations: 25 single-byte characters	No
SUFFIX	Payer’s suffix Character length and limitations: 12 single-byte characters	No
AUCTIONITEMNUMBER	Search by auction item number of the purchased goods	No
TRANSACTIONCLASS	Search by classification of transaction. Note: Some kinds of possible classes of transactions are not searchable with this field. You cannot search for bank transfer withdrawals, for example. l All: all transaction classifications l Sent: only payments sent l Received: only payments received l MassPay: only mass payments l MoneyRequest: only money requests l FundsAdded: only funds added to balance l FundsWithdrawn: only funds withdrawn from balance l Referral: only transactions involving referrals l Fee: only transactions involving fees l Subscription: only transactions involving subscriptions l Dividend: only transactions involving dividends l Billpay: only transactions involving BillPay Transactions l Refund: only transactions involving funds l CurrencyConversions: only transactions involving currency conversions l BalanceTransfer: only transactions involving balance transfers l Reversal: only transactions involving BillPay reversals l Shipping: only transactions involving UPS shipping fees l BalanceAffecting: only transactions that affect the account balance l ECheck: only transactions involving eCheck	No
AMT	Search by transaction amount	No
STATUS	Search by transaction status: l Pending: The payment is pending. The specific reason the payment is pending is returned by the GetTransactionDetails API PendingReason field. l Processing: The payment is being processed. l Success: The payment has been completed and the funds have been added successfully to your account balance. l Denied: You denied the payment. This happens only if the payment was previously pending. l Reversed: A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer.	No

Table A.29

TransactionSearch Response Fields

Field	Description
L_TIMESTAMPn	The date and time (in UTC/GMT format) the transaction occurred These parameters must be ordered sequentially beginning with 0 (for example, L_TIMESTAMP0, L_TIMESTAMP1).
L_TIMEZONEn	The time zone of the transaction These parameters must be ordered sequentially beginning with 0 (for example, L_TIMEZONE0, L_TIMEZONE1).
L_TYPEn	The type of the transaction These parameters must be ordered sequentially beginning with 0 (for example, L_TYPE0, L_TYPE1).
L_EMAILn	The email address of either the payer or the payment recipient (the “payee”). If the payment amount is positive, this field is the recipient of the funds. If the payment is negative, this field is the paying customer. These parameters must be ordered sequentially beginning with 0 (for example, L_EMAIL0, L_EMAIL1).
L_NAMEn	Display name of the payer These parameters must be ordered sequentially beginning with 0 (for example, L_NAME0, L_NAME1).
L_TRANSACTIONIDn	Seller’s transaction ID These parameters must be ordered sequentially beginning with 0 (for example, L_TRANSACTIONID0, L_TRANSACTIONID1.
L_STATUSn	The status of the transaction. These parameters must be ordered sequentially beginning with 0 (for example, L_STATUS0, L_STATUS1).
L_AMTn	The total gross amount charged, including any profile shipping cost and taxes These parameters must be ordered sequentially beginning with 0 (for example, L_AMT0, L_AMT1).
L_FEEAMTn	The fee that PayPal charged for the transaction These parameters must be ordered sequentially beginning with 0 (for example, L_FEEAMT0, L_FEEAMT1).
L_NETAMTn	The net amount of the transaction These parameters must be ordered sequentially beginning with 0 (for example, L_NETAMT0, L_NETAMT1).

GetTransactionDetails

 

Table A.30

GetTransactionDetails Request Parameters

Parameter	Description	Required?
METHOD	Name of the API: GetTransactionDetails	Yes
TRANSACTIONID	Unique identifier of a transaction. Note: The details for some kinds of transactions cannot be retrieved with GetTransactionDetails. You cannot obtain details of bank transfer withdrawals, for example. Character length and limitations: 17 single-byte alphanumeric characters	Yes

Table A.31

GetTransactionDetails Response Fields

Parameter	Description
RECEIVERBUSINESS	Email address or account ID of the payment recipient (the seller). Equivalent to Receiver if payment is sent to primary account. Character length and limitations: 127 single-byte alphanumeric characters
RECEIVEREMAIL	Primary email address of the payment recipient (the seller). If you are the recipient of the payment and the payment is sent to your non-primary email address, the value of Receiver is still your primary email address. Character length and limitations: 127 single-byte alphanumeric characters
RECEIVERID	Unique account ID of the payment recipient (the seller). This value is the same as the value of the recipient's referral ID.
EMAIL	Email address of payer Character length and limitations: 127 single-byte characters
PAYERID	Unique customer ID. Character length and limitations: 13 single-byte alphanumeric characters.
PAYERSTATUS	Status of payer’s email address: Verified Unverified
FIRSTNAME	Payer’s first name Character length and limitations: 25 single-byte characters
LASTNAME	Payer’s last name Character length and limitations: 25 single-byte characters
MIDDLENAME	Payer’s middle name Character length and limitations: 25 single-byte characters
PAYERBUSINESS	Payer’s business name. Character length and limitations: 127 single-byte characters
SHIPTOCOUNTRYCODE	Payment sender’s country of residence using standard two-character ISO 3166 country codes. Character length and limitations: Two single-byte characters For the list of country codes, see Appendix F, “Country Codes.”
SALUTATION	Payer’s salutation Character length and limitations: 20 single-byte characters
SUFFIX	Payer’s suffix Character length and limitations: 12 single-byte characters
ADDRESSOWNER	eBay company that maintains this address
ADDRESSSTATUS	Status of the address on file with PayPal: None Confirmed Unconfirmed
SHIPTOCITY	Name of city. Character length and limitations: 120 single-byte alphanumeric characters
SHIPTONAME	Person’s name associated with this address. Character length and limitations: 32 single-byte alphanumeric characters
SHIPTOPHONENUM	Phone number associated with this address
SHIPTOZIP	Postal code
SHIPTOSTATE	State or province. Character length and limitations: 120 single-byte alphanumeric characters Required for US addresses only.
SHIPTOSTREET	First street address. Character length and limitations: 300 single-byte alphanumeric characters
SHIPTOSTREET2	Second street address. Character length and limitations: 300 single-byte alphanumeric characters
PARENTTRANSACTIONID	Original transaction to which this transaction is related. This field is populated for the following transaction types: l Reversal l Capture of an authorized transaction. l Reauthorization of a transaction. l Capture of an order. The value of ParentTransactionID is the original OrderID. l Authorization of an order. The value of ParentTransactionID is the original OrderID. l Capture of an order authorization. l Void of an order. The value of ParentTransactionID is the original OrderID. Character length and limitations: 19 single-byte characters
TRANSACTIONID	PayPal transaction identification number Character length and limitations: 19 single-byte characters
RECEIPTID	Receipt ID Character length and limitations: 16 digits in xxxx-xxxx-xxxx-xxxx format
TRANSACTIONTYPE	The type of transaction cart: Transaction created by customer via the PayPal Shopping Cart feature. send-money: Transaction created by customer from the Send Money tab on the PayPal website. web-accept: Transaction created by customer via Buy Now, Donation, or Auction Smart Logos. subscr-*: Transaction created by customer via Subscription. eot means “end of subscription term.” merch-pmt: preapproved payment. mass-pay: Transaction created via MassPay. virtual-terminal: Transaction created via merchant virtual terminal.
PAYMENTTYPE	Indicates whether the payment is instant or delayed. Character length and limitations: Seven single-byte characters
ORDERTIME	Date and time of payment
AMT	Full amount of the customer’s payment, before transaction fee is subtracted
CURRENCYCODE	The currency for the transaction.
FEEAMT	Transaction fee associated with the payment
SETTLEAMT	Amount deposited into the account’s primary balance after a currency conversion from automatic conversion through your Payment Receiving Preferences or manual conversion through manually accepting a payment. This amount is calculated after fees and taxes have been assessed.
TAXAMT	Amount of tax for transaction
EXCHANGERATE	Exchange rate for transaction
PAYMENTSTATUS	Status of the payment. The status of the payment: l None: No status l Canceled-Reversal: This means a reversal has been canceled. For example, you won a dispute with the customer, and the funds for the transaction that was reversed have been returned to you. l Completed: The payment has been completed, and the funds have been added successfully to your account balance. l Denied: You denied the payment. This happens only if the payment was previously pending because of possible reasons described for the PendingReason element. l Expired: the authorization period for this payment has been reached. l Failed: The payment has failed. This happens only if the payment was made from your customer’s bank account. l Pending: The payment is pending. See the PendingReason field for more information. l Refunded: You refunded the payment. l Reversed: A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer. The reason for the reversal is specified in the ReasonCode element. l Processed: A payment has been accepted. l Voided: An authorization for this transaction has been voided.
PENDINGREASON	Note: PendingReason is returned in the response only if PaymentStatus is Pending. The reason the payment is pending: l none: No pending reason l address: The payment is pending because your customer did not include a confirmed shipping address and your Payment Receiving Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile. l echeck: The payment is pending because it was made by an eCheck that has not yet cleared. l intl: The payment is pending because you hold a non-U.S. account and do not have a withdrawal mechanism. You must manually accept or deny this payment from your Account Overview. l multi-currency: You do not have a balance in the currency sent, and you do not have your Payment Receiving Preferences set to automatically convert and accept this payment. You must manually accept or deny this payment. l verify: The payment is pending because you are not yet verified. You must verify your account before you can accept this payment. l other: The payment is pending for a reason other than those listed above. For more information, contact PayPal Customer Service.
REASONCODE	The reason for a reversal if TransactionType is reversal: l none: No reason code l chargeback: A reversal has occurred on this transaction due to a chargeback by your customer. l guarantee: A reversal has occurred on this transaction due to your customer triggering a money-back guarantee. l buyer-complaint: A reversal has occurred on this transaction due to a complaint about the transaction from your customer. l refund: A reversal has occurred on this transaction because you have given the customer a refund. l other: A reversal has occurred on this transaction due to a reason not listed above.
INVNUM	Invoice number you set in the original transaction. Character length and limitations: 127 single-byte alphanumeric characters
CUSTOM	Custom field you set in the original transaction. Character length and limitations: 127 single-byte alphanumeric characters
NOTE	Memo entered by your customer in PayPal Website Payments note field. Character length and limitations: 255 single-byte alphanumeric characters
SALESTAX	Amount of tax charged on payment
L_DESCn	Item name set by you or entered by the customer. If this was a shopping cart transaction, PayPal appends the number of the item to the HTML item_name variable. For example, item_name1, item_name2, and so forth. Character length and limitations: 127 single-byte alphanumeric characters These parameters are ordered sequentially beginning with 0 (for example, L_DESC0, L_DESC1).
L_NUMBERn	Item number set by you. If this was a shopping cart transaction, PayPal appends the number of the item to the HTML item_number variable. For example, item_number1, item_number2, and so forth. Character length and limitations: 127 single-byte alphanumeric characters These parameters are ordered sequentially beginning with 0 (for example, L_NUMBER0, L_NUMBER1).
L_QTYn	Quantity set by you or entered by the customer. Character length and limitations: no limit These parameters are ordered sequentially beginning with 0 (for example, L_QTY0, L_QTY1).
L_AMTn	Cost of item These parameters are ordered sequentially beginning with 0 (for example, L_AMT0, L_AMT1).
L_OPTIONSNAMEn	PayPal option names for an item in the shopping cart; each name corresponds to an option value. There can be multiple option names per item. The option names are ordered sequentially beginning with 0 (for example, L_OPTIONSNAMES0, L_OPTIONSNAME1).
L_OPTIONSVALUEn	PayPal option values corresponding to option names of an item in the shopping cart. The option names are ordered sequentially beginning with 0 (for example, L_OPTIONSVALUE0, L_OPTIONSVALUE1).
SUBSCRIPTIONID	ID generated by PayPal for the subscriber. Character length and limitations: no limit
SUBSCRIPTIONDATE	Subscription start date
EFFECTIVEDATE	Date when the subscription modification will be effective
RETRYTIME	Date PayPal will retry a failed subscription payment.
USERNAME	Username generated by PayPal and given to subscriber to access the subscription. Character length and limitations: 64 alphanumeric single-byte characters
PASSWORD	Password generated by PayPal and given to subscriber to access the subscription. For security, the value of the password is hashed. Character length and limitations: 128 alphanumeric single-byte characters
RECURRENCES	The number of payment installments that will occur at the regular rate. Character length and limitations: no limit
REATTEMPT	Indicates whether reattempts should occur upon payment failures
RECURRING	Indicates whether regular rate recurs. 1 = Yes
PERIOD	The period of time that the subscriber will be charged. Character length and limitations: no limit
BUYERID	Customer’s auction ID
CLOSINGDATE	Auction’s close date
MULTIITEM	Counter used for multi-item auction payments

Mass Payment

MassPay Request

 

Table A.32

MassPay Parameters

Parameter	Description	Required?
METHOD	Name of the API: MassPay	Yes
RECEIVERTYPE	Indicates how you identify the recipients of payments in all the individual mass payment items: l EmailAddress (L_EMAILn in the individual item) l UserID (L_RECEIVERID_n in the individual item).	Yes
L_AMTn	Payment amount.	Yes
CURRENCYCODE	A three-character currency code for one of the currencies listed in PayPal-Supported Transactional Currencies. Default: USD.	Yes
L_EMAILn	Email address of recipient. This field is required if RECEIVERTYPE is EmailAddress. Note: You must specify either L_EMAILn or L_RECEIVERIDn, but you can not mix them. Use only one or the other, but not both, in a single request. Character length and limitations: 127 single-byte characters maximum. These parameters must be ordered sequentially beginning with 0 (for example L_EMAIL0, L_EMAIL1).	See description
L_RECEIVERIDn	Unique PayPal customer account number. This value corresponds to the value of PAYERID returned by GetTransactionDetails. This field is required if RECEIVERTYPE is UserID. These parameters must be ordered sequentially beginning with 0 (for example L_RECEIVERID0, L_RECEIVER1).	See description
L_UNIQUEIDn	Transaction-specific identification number for tracking in an accounting system. Character length and limitations: 30 single-byte characters. No whitespace allowed. These parameters must be ordered sequentially beginning with 0 (for example L_UNIQUEID0, L_UNIQUEID1).	No
L_NOTEn	Custom note for each recipient. Character length and limitations: 4,000 single-byte alphanumeric characters These parameters must be ordered sequentially beginning with 0 (for example L_NOTE0, L_NOTE1).	No
EMAILSUBJECT	The subject line of the email that PayPal sends when the transaction is completed. The subject line is the same for all recipients. Character length and limitations: 255 single-byte alphanumeric characters	No

MassPay Response

The fields in the response are the standard response header fields. See “Response Format”.

Recurring Payments and Reference Transactions

IMPORTANT:

To use recurring payments, you must set the VERSION parameter to 50.0 or higher in your NVP API calls.

CreateRecurringPaymentsProfile

CreateRecurringPaymentsProfile Request

The CreateRecurringPaymentsProfileRequest message consists of the fields identified in Table A.33.

Table A.33

CreateRecurringPaymentsProfile Request

Name	Description/Data Type	Required
METHOD	Name of API: CreateRecurringPaymentsProfile	Yes
TOKEN	A timestamped token, the value of which was returned in the response to the first call to SetExpressCheckout. You can also use the token returned in the SetCustomerBillingAgreement response. l Only one recurring payment profile is allowed for each CreateRecurringPaymentsProfile request. l The same token may be used by multiple CreateRecurringPaymentsProfile calls to set up multiple recurring payment profiles. The maximum number of recurring payments profiles must not exceed the number of billing agreement details passed as part of the SetExpressCheckout request. This field is required if you are using recurring payments with Express Checkout. Note: The CreateRecurringPaymentsProfile request must include either TOKEN or the required credit card information listed in . Note: Tokens expire after approximately 3 hours.	See description
Credit Card Details (See Table A.34, “Credit Card Fields for Recurring Payments with Direct Payments”)	Credit card details for recurring payments with direct payments. Credit card details are required for using recurring payments with direct payments. See Table A.34, “Credit Card Fields for Recurring Payments with Direct Payments”. Note: The CreateRecurringPaymentsProfile request must include either TOKEN or the required credit card information listed in Table A.34, “Credit Card Fields for Recurring Payments with Direct Payments”.	See description
SUBSCRIBERNAME	Full name of the person receiving the product or service paid for by the recurring payment. If not present, the name in the buyer’s PayPal account is used. Character length and limitations: 32 single-byte characters	No
Ship To Address (See Table A.11, “Ship to Address (Optional)”)	The subscriber’s shipping address associated with this profile, if applicable. If not specified, the ship to address from buyer’s PayPal account is used. See Table A.11, “Ship to Address (Optional)” for address details. Note: Shipping Address is optional, but if you include it, certain fields are required.	No
PROFILESTARTDATE	The date when billing for this profile begins. Must be a valid date, in UTC/GMT format. Note: The profile may take up to 24 hours for activation.	Yes
PROFILEREFERENCE	The merchant’s own unique reference or invoice number. Character length and limitations: 127 single-byte alphanumeric characters	No
DESC	Description of the recurring payment. Note: This field must match the corresponding billing agreement description included in the SetExpressCheckout request. Character length and limitations: 127 single-byte alphanumeric characters	No
TRIALBILLINGPERIOD	Unit for billing during the trial period. One of the following values: l Day l Week l SemiMonth l Month l Year If you create a trial period, TRIALBILLINGPERIOD is required. Otherwise, it is optional. You can create only one trial period per profile. Note: The combination of TRIALBILLINGPERIOD and TRIALBILLINGFREQUENCY cannot exceed one year.	See description
TRIALBILLING FREQUENCY	Number of billing periods that make up one billing cycle. Note: The combination of billing period and billing frequency cannot exceed one year. Note: If the billing period is SemiMonth. the billing frequency must be 1.	See description
TRIALTOTALBILLING CYCLES	The total number of billing cycles in this trial period, which must be greater than 0. The trial period will start on the BILLINGSTARTDATE and continue at the TRIALBILLINGFREQUENCY for TRIALTOTALBILLINGCYCLES cycles. If you create a trial period, TRIALTOTALBILLINGCYCLES is required. Otherwise, it is optional.	See description
TRIALAMT	Billing amount for each billing cycle during the trial period, not including shipping and tax amounts. If you create a trial period, TRIALAMT is required. Otherwise, it is optional. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.	See description
TRIALSHIPPINGAMT	Shipping amount for each billing cycle during the trial period. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.	No
TRIALTAXAMT	Tax amount for each billing cycle during the trial period. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.	No
BILLINGPERIOD	The unit of measure for the billing cycle. Must be one of: l Day l Week l SemiMonth l Month l Year For SemiMonth, billing is done on the 1st and 15th of each month.	Yes
BILLINGFREQUENCY	Number of billing periods that make up one billing cycle. The combination of billing frequency and billing period must be less than or equal to one year. For example, if the billing cycle is Month, the maximum value for billing frequency is 12. Similarly, if the billing cycle is Week, the maximum value for billing frequency is 52. Note: If the billing period is SemiMonth., the billing frequency must be 1.	Yes
TOTALBILLINGCYCLES	The number of billing cycles in the regular payment period. l If no value is specified or the value is 0, the regular payment period continues until the profile is cancelled or suspended. l If the value is greater than 0, the regular payment period starts after the trial period is finished and continues at the billing frequency for the specified number of cycles.	No
AMT	Billing amount for each billing cycle during the regular payment period, not including shipping and tax amounts. Note: All amounts in the CreateRecurringPaymentsProfile request must have the same currency. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.	Yes
CURRENCYCODE	A three-character currency code for one of the currencies listed in PayPal-Supported Transactional Currencies. Default: USD.	No
SHIPPINGAMT	Shipping amount for each billing cycle during the regular payment period. Note: All amounts in the request must have the same currency. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.	No
TAXAMT	Tax amount for each billing cycle during the regular payment period. Note: All amounts in the request must have the same currency. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.	No
MAXFAILEDPAYMENTS	The number of scheduled payments that can fail before the profile is automatically suspended. An IPN message is sent to the merchant when the specified number of failed payments is reached. Character length and limitations: Number string representing an integer	No
AUTOBILLOUTAMT	This field indicates whether you would like PayPal to automatically bill the outstanding balance amount in the next billing cycle. The outstanding balance is the total amount of any previously failed payments. Valid values: Must be NoAutoBill or AddToNextBilling	No
INITAMT	Initial non-recurring payment amount due immediately upon profile creation. Use an initial amount for enrolment or set-up fees. Note: All amounts in the CreateRecurringPaymentsProfile request must have the same currency. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.	No
FAILEDINITAMTACTION	By default, PayPal will suspend the pending profile in the event that the initial payment amount fails. You can override this default behavior by setting this field to ContinueOnFailure, which indicates that if the initial payment amount fails, PayPal should add the failed payment amount to the outstanding balance for this recurring payment profile. When this flag is set to ContinueOnFailure, a success code will be returned to the merchant in the CreateRecurringPaymentsProfile response and the recurring payments profile will be activated for scheduled billing immediately. You should check your IPN messages or PayPal account for updates of the payment status. If this field is not set or is set to CancelOnFailure, PayPal will create the recurring payment profile, but will place it into a pending status until the initial payment is completed. If the initial payment clears, PayPal will notify you by IPN that the pending profile has been activated. If the payment fails, PayPal will notify you by IPN that the pending profile has been cancelled. Character length and limitations: ContinueOnFailure or CancelOnFailure	No

The following fields are used only for recurring payments with direct payments.

Table A.34

Credit Card Fields for Recurring Payments with Direct Payments

Name	Description / Data Type	Required?
CREDITCARDTYPE	Type of credit card. Character length and limitations: Up to ten single-byte alphabetic characters. This field is required if you are using recurring payments with direct payments. Allowable values: l Visa l MasterCard l Discover l Amex l Switch l Solo	See description
ACCT	Credit card number Character length and limitations: numeric characters only. No spaces or punctutation. Must conform with modulo and length required by each credit card type. This field is required if you are using recurring payments with direct payments. Note: You must include either the TOKEN or ACCT fields with the CreateRecurringPaymentsProfile request. If you specify both, an error is returned.	See description
EXPDATE	Credit card expiration date. This field is required if you are using recurring payments with direct payments. Format: MMYYYY Character length and limitations: Six single-byte numeric characters, including leading zero.	See description
CARDVERIFICATION VALUE	Card Verification Value, version 2. Note: Your Merchant Account settings determine whether this field is required. Character length for Visa, MasterCard, and Discover: exactly three digits. Character length for American Express: exactly four digits. Important: To comply with credit card processing regulations, once a transaction has been completed, you must not store the value of CVV2.	See description
ISSUEDATE	Month and year that Switch or Solo card was issued. This field is required if the credit card type is Switch or Solo. Format: MMYYYY Character length and limitations: Six single-byte numeric characters, including leading zero.	See description
ISSUENUMBER	Issue number of Switch or Solo card. Character length: two numeric digits maximum.	No
FIRSTNAME	Payer’s first name. This field is required if you are using recurring payments with direct payments. Character length and limitations: 25 single-byte characters	See description
LASTNAME	This field is required if you are using recurring payments with direct payments. Payer’s last name. Character length and limitations: 25 single-byte characters	See description
STREET1	First street address. Character length and limitations: 100 single-byte characters	No
STREET2	Second street address. Character length and limitations: 100 single-byte characters	No
CITY	Name of city. Character length and limitations: 40 single-byte characters	No
STATE	State or province. Character length and limitations: 40 single-byte characters For state or province abbreviations, see “State and Province Abbreviations”.”	No
COUNTRY	Country code. Character length and limitations: Two single-byte characters. For the list of country codes, see Appendix F, “Country Codes.”	No
ZIP	U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters	No

CreateRecurringPaymentsProfile Response

 

Table A.35

CreateRecurringPaymentsProfile Response

Field	Description
PROFILEID	A unique identifier for future reference to the details of this recurring payment. Character length and limitations: Up to 14 single-byte alphanumeric characters
STATUS	Status of the recurring payment profile. l ActiveProfile - The recurring payment profile has been successfully created and activated for scheduled payments according the billing instructions from the recurring payments profile. l PendingProfile - The system is in the process of creating the recurring payment profile. Please check your IPN messages for an update. For more information on status and initial amounts, see the FailedInitialAmountAction field on page 97.

GetRecurringPaymentsProfileDetails

GetRecurringPaymentsProfileDetails Request

 

Table A.36

GetRecurringPaymentsProfileDetails Request

Field	Description	Required?
PROFILEID	Recurring payments profile ID returned in the CreateRecurringPaymentsProfile response. Character length and limitations: 14 single-byte alphanumeric characters. 19 character profile IDs are supported for compatability with previous versions of the PayPal API.	Yes

GetRecurringPaymentsProfileDetails Response

 

Table A.37

GetRecurringPaymentsProfileDetails Response

Field	Description
PROFILEID	Recurring payments profile ID returned in the CreateRecurringPaymentsProfile response.
STATUS	Status of the recurring payment profile. l ActiveProfile l PendingProfile l CancelledProfile l SuspendedProfile l ExpiredProfile
DESC	Description of the recurring payment. Character length and limitations: 127 single-byte alphanumeric characters
AUTOBILLOUTAMT	This field indicates whether you would like PayPal to automatically bill the outstanding balance amount in the next billing cycle. Valid values: NoAutoBill or AddToNextBilling
MAXFAILEDPAYMENTS	The number of scheduled payments that can fail before the profile is automatically suspended. An IPN message is sent to the merchant when the specified number of failed payments is reached. Character length and limitations: Number string representing an integer
SUBSCRIBERNAME	Full name of the person receiving the product or service paid for by the recurring payment. If not present, the name in the buyer’s PayPal account is used. Character length and limitations: 32 single-byte characters
Ship To Address (See Table A.11, “Ship to Address (Optional)”)	The buyer’s shipping address. See Table A.11, “Ship to Address (Optional)” for address details.
PROFILESTARTDATE	The date when billing for this profile began, in YYYY-MM-DD format.
PROFILEREFERENCE	The merchant’s own unique reference or invoice number. Character length and limitations: 127 single-byte alphanumeric characters
BILLINGPERIOD	The unit of measure for the billing cycle. Must be one of: l Day l Week l SemiMonth l Month l Year Note: This field is not returned if the profile is cancelled or expired.
BILLINGFREQUENCY	Number of billing periods that make up one billing cycle. Note: This field is not returned if the profile is cancelled or expired.
TOTALBILLINGCYCLES	The number of billing cycles in the regular payment period. Note: This field is not returned if the profile is cancelled or expired.
AMT	Billing amount for each billing cycle during the regular payment period, not including shipping and tax amounts. Note: All amounts in the CreateRecurringPaymentsProfile request must have the same currency. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD. Note: This field is not returned if the profile is cancelled or expired.
SHIPPINGAMT	Shipping amount for each billing cycle during the regular payment period. Note: All amounts in the request must have the same currency. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD. Note: This field is not returned if the profile is cancelled or expired.
TAXAMT	Tax amount for each billing cycle during the regular payment period. Note: All amounts in the request must have the same currency. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD. Note: This field is not returned if the profile is cancelled or expired.
NEXTBILLINGDATE	The next scheduled billing date, in YYYY-MM-DD format.
NUMCYCLESCOMPLETED	The number of billing cycles completed in the current active subscription period. A billing cycle is considered completed when payment is collected or after retry attempts to collect payment for the current billing cycle have failed.
NUMCYCLESREMAINING	The number of billing cycles remaining in the current active subscription period.
OUTSTANDINGBALANCE	The current past due or outstanding balance for this profile. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.
FAILEDPAYMENTCOUNT	The total number of failed billing cycles for this profile.
LASTPAYMENTDATE	The date of the last successful payment received for this profile, in YYYY-MM-DD format.
LASTPAYMENTAMT	The amount of the last successful payment received for this profile. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.
AGGREGATEAMT	Total amount collected thus far for scheduled payments. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.
AGGREGATEOPTIONALAMT	Total amount collected thus far for optional payments. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.
FINALPAYMENTDUEDATE	The final scheduled payment date before the profile expires.
Credit Card Details (see Table A.38, “Credit Card Details for GetRecurringPaymentsProfileDetails”)	Credit card details for this recurring payments profile. Note: Credit card details are returned only for recurring payments with direct payment. See Table A.38, “Credit Card Details for GetRecurringPaymentsProfileDetails.”

Table A.38

Credit Card Details for GetRecurringPaymentsProfileDetails

Field	Description
CREDITCARDTYPE	Type of credit card. Character length and limitations: Up to ten single-byte alphabetic characters. Allowable values: l Visa l MasterCard l Discover l Amex l Switch l Solo
ACCT	The last four digits of the credit card account number. Character length and limitations: numeric characters only. No spaces or punctutation.
EXPDATE	Credit card expiration date. Format: MMYYYY Character length and limitations: Six single-byte numeric characters, including leading zero.
ISSUEDATE	Month and year that Switch or Solo card was issued. Format: MMYYYY Character length and limitations: Six single-byte numeric characters, including leading zero.
ISSUENUMBER	Issue number of Switch or Solo card. Character length: two numeric digits maximum.
FIRSTNAME	Payer’s first name. Character length and limitations: 25 single-byte characters
LASTNAME	Payer’s last name. Character length and limitations: 25 single-byte characters
STREET1	First street address. Character length and limitations: 100 single-byte characters
STREET2	Second street address. Character length and limitations: 100 single-byte characters
CITY	Name of city. Character length and limitations: 40 single-byte characters
STATE	State or province. Character length and limitations: 40 single-byte characters For state or province abbreviations, see “State and Province Abbreviations”.”
COUNTRY	Country code. Character length and limitations: Two single-byte characters. For the list of country codes, see Appendix F, “Country Codes.”
ZIP	U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters

ManageRecurringPaymentsProfileStatus

ManageRecurringPaymentsProfileStatus Request

 

Table A.39

ManageRecurringPaymentsProfileStatus Request

Field	Description	Required?
PROFILEID	Recurring payments profile ID returned in the CreateRecurringPaymentsProfile response. Character length and limitations: 14 single-byte alphanumeric characters. 19 character profile IDs are supported for compatability with previous versions of the PayPal API.	Yes
ACTION	The action to be performed to the recurring payments profile. Must be one of the following: l Cancel - Only profiles in Active or Suspended state can be cancelled. l Suspend - Only profiles in Active state can be suspended. l Reactivate - Only profiles in Suspended state can be reactivated.	Yes
NOTE	The reason for the change in status. For profiles created using Express Checkout, this message will be included in the email notification to the buyer when the status of the profile is successfully changed, and can also be seen by both you and the buyer on the Status History page of the PayPal account.	No

ManageRecurringPaymentsProfileStatus Response

 

Table A.40

ManageRecurringPaymentsProfileStatus Response

Field	Description
PROFILEID	Recurring payments profile ID returned in the CreateRecurringPaymentsProfile response. For each action, an error is returned if the recurring payments profile has a status that is not compatible with the action. Errors are returned in the following cases: l Cancel - Profile status is not Active or Suspended l Suspend - Profile status is not Active l Reactivate - Profile status is not Suspended

BillOutstandingAmount

Note:

If you call BillOutstandingAmount within 24 hours of a regularly scheduled payment, an error is returned.

BillOutstandingAmount Request

 

Table A.41

BillOutstandingAmount Request

Field	Description	Required?
PROFILEID	Recurring payments profile ID returned in the CreateRecurringPaymentsProfile response. Note: The profile must have a status of either Active or Suspended. Character length and limitations: 14 single-byte alphanumeric characters. 19 character profile IDs are supported for compatability with previous versions of the PayPal API.	Yes
AMT	The amount to bill. The amount must be less than or equal to the current outstanding balance of the profile. If no value is specified, PayPal will attempt to bill the entire outstanding balance amount. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.	No
NOTE	The reason for the non-scheduled payment. For profiles created using Express Checkout, this message will be included in the email notification to the buyer for the non-scheduled payment transaction, and can also be seen by both you and the buyer on the Status History page of the PayPal account.	No

BillOutstandingAmount Response

 

Table A.42

BillOutstandingAmount Response

Field	Description
PROFILEID	Recurring payments profile ID returned in the CreateRecurringPaymentsProfile response. An error is returned if the profile specified in the BillOutstandingAmount request has a status of cancelled or expired.

UpdateRecurringPaymentsProfile

Note:

For recurring payments profiles created using Express Checkout, an error may be returned if you call UpdateRecurringPaymentsProfile within 72 hours of a regularly scheduled payment.

UpdateRecurringPaymentsProfile Request

 

Table A.43

UpdateRecurringPaymentsProfile Request

Field	Description	Required?
PROFILEID	Recurring payments profile ID returned in the CreateRecurringPaymentsProfile response. Character length and limitations: 14 single-byte alphanumeric characters. 19 character profile IDs are supported for compatability with previous versions of the PayPal API.	Yes
NOTE	The reason for the update to the recurring payments profile. This message will be included in the email notification to the buyer for the recurring payments profile update. This note can be seen by you on the Status History page of the PayPal account. For recurring payments profiles created using Express Checkout, the buyer can also see the note from their PayPal account.	No
DESC	Description of the recurring payment. Character length and limitations: 127 single-byte alphanumeric characters	No
SUBSCRIBERNAME	Full name of the person receiving the product or service paid for by the recurring payment. If not present, the name in the buyer’s PayPal account is used. Character length and limitations: 32 single-byte characters	No
Ship To Address (See Table A.11, “Ship to Address (Optional)”)	The subscriber’s shipping address associated with this profile, if applicable. If not specified, the ship to address from buyer’s PayPal account is used. See Table A.11, “Ship to Address (Optional)” for address details. Important: Shipping Address is optional, but if you update any of the address fields, you must enter all of them. For example, if you want to update the subsriber’s street address, you must specify all of the fields listed in Table A.11, “Ship to Address (Optional)”, not just the field for the street address.	No
PROFILEREFERENCE	The merchant’s own unique reference or invoice number. Character length and limitations: 127 single-byte alphanumeric characters	No
ADDITIONALBILLING CYCLES	The number of additional billing cycles to add to this profile.	No
AMT	Billing amount for each cycle in the subscription period, not including shipping and tax amounts. Note: For recurring payments with Express Checkout, the payment amount can be increased by no more than 20% every 180 days (starting when the profile is created). Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.	No
SHIPPINGAMT	Shipping amount for each billing cycle during the regular payment period. Note: All amounts in the request must have the same currency. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.	No
TAXAMT	Tax amount for each billing cycle during the regular payment period. Note: All amounts in the request must have the same currency. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.	No
OUTSTANDINGAMT	The current past due or outstanding amount for this profile. You can only decrease the outstanding amount—it cannot be increased. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.	No
AUTOBILLOUTAMT	This field indicates whether you would like PayPal to automatically bill the outstanding balance amount in the next billing cycle. Valid values: Must be NoAutoBill or AddToNextBilling	No
MAXFAILEDPAYMENTS	The number of failed payments allowed before the profile is automatically suspended. The specified value cannot be less than the current number of failed payments for this profile. An IPN message is sent to the merchant when the specified number of failed payments is reached. Character length and limitations:Number string representing an integer	No
Credit card details (see Table A.44, “Credit Card Details for UpdateRecurringPaymentsProfile request”)	Credit card details to be updated. Important: Credit card billing address is optional, but if you update any of the address fields, you must enter all of them. For example, if you want to update the street address, you must specify all of the fields listed in Table A.44, “Credit Card Details for UpdateRecurringPaymentsProfile request”, not just the field for the street address. See Table A.44, “Credit Card Details for UpdateRecurringPaymentsProfile request.”	See description

Table A.44

Credit Card Details for UpdateRecurringPaymentsProfile request

Field	Description	Required?
CREDITCARDTYPE	Type of credit card. Character length and limitations: Up to ten single-byte alphabetic characters. If you are updating credit card information, this field is required. Allowable values: l Visa l MasterCard l Discover l Amex l Switch l Solo	See description
ACCT	Credit card number Character length and limitations: numeric characters only. No spaces or punctutation. Must conform with modulo and length required by each credit card type.	See description
EXPDATE	Credit card expiration date. If you are updating credit card information, this field is required. Format: MMYYYY Character length and limitations: Six single-byte numeric characters, including leading zero.	See description
CARDVERIFICATION VALUE	Card Verification Value, version 2. Note: Your Merchant Account settings determine whether this field is required. Character length for Visa, MasterCard, and Discover: exactly three digits. Character length for American Express: exactly four digits. Important: To comply with credit card processing regulations, once a transaction has been completed, you must not store the value of CVV2.	See description
ISSUEDATE	Month and year that Switch or Solo card was issued. This field is required if credit card type is Switch or Solo and is included in the UpdateRecurringPaymentsProfile request. Format: MMYYYY Character length and limitations: Six single-byte numeric characters, including leading zero.	See description
ISSUENUMBER	Issue number of Switch or Solo card. Character length: two numeric digits maximum.	No
FIRSTNAME	Payer’s first name. If you are updating credit card information, this field is required. Character length and limitations: 25 single-byte characters	See description
LASTNAME	If you are updating credit card information, this field is required. Payer’s last name. Character length and limitations: 25 single-byte characters	See description
STREET1	First street address. Character length and limitations: 100 single-byte characters Important: Credit card billing address is optional, but if you update any of the address fields, you must enter all of them.	See description
STREET2	Second street address. Character length and limitations: 100 single-byte characters Important: Credit card billing address is optional, but if you update any of the address fields, you must enter all of them.	See description
CITY	Name of city. Character length and limitations: 40 single-byte characters Important: Credit card billing address is optional, but if you update any of the address fields, you must enter all of them.	See description
STATE	State or province. Character length and limitations: 40 single-byte characters For state or province abbreviations, see “State and Province Abbreviations”.” Important: Credit card billing address is optional, but if you update any of the address fields, you must enter all of them.	See description
COUNTRY	Country code. Character length and limitations: Two single-byte characters. For the list of country codes, see Appendix F, “Country Codes.” Important: Credit card billing address is optional, but if you update any of the address fields, you must enter all of them.	See description
ZIP	U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters Important: Credit card billing address is optional, but if you update any of the address fields, you must enter all of them.	See description

UpdateRecurringPaymentsProfile Response

 

Table A.45

UpdateRecurringPaymentsProfile Response

Field	Description
PROFILEID	Recurring payments profile ID returned in the CreateRecurringPaymentsProfile response. An error is returned if the profile specified in the BillOutstandingAmount request has a status of cancelled or expired.

SetCustomerBillingAgreement

SetCustomerBillingAgreementRequest

The SetCustomerBillingAgreementRequest message consists of the fields identified in Table A.46.

Table A.46

SetCustomerBillingAgreementRequest Fields

Name	Description/Data Type	Required
METHOD	Name of API: SetCustomerBillingAgreement	Yes
BILLINGTYPE	Type of billing agreement. For reference transactions, this field must be MerchantInitiatedBilling, which requests PayPal to prompt the buyer to set up a billing agreement for recurring payments. For recurring payments, the value must be RecurringPayments Note: Other defined values are not valid.	Yes
BILLINGAGREEMENT DESCRIPTION	Description of goods or services associated with the billing agreement.	No
BILLINGAGREEMENT CUSTOM	Custom annotation field for your own use.	No
PAYMENTTYPE	Specifies type of PayPal payment you require for the billing agreement.	No
RETURNURL	URL to which the customer’s browser is returned after choosing to pay with PayPal. Note: PayPal recommends that the value be the final review page on which the customer confirms the billing agreement. Character length and limitations: no limit.	Yes
CANCELURL	URL to which the customer is returned if he does not approve the use of PayPal to pay you. Note: PayPal recommends that the value be the original page on which the customer chose to pay with PayPal or establish a billing agreement. Character length and limitations: no limit	Yes
LOCALECODE	Locale of pages displayed by PayPal during checkout. Character length and limitations: Any two-character country code. The following two-character country codes are supported by PayPal: l AT l AU l BE l CA l CH l CN l DE l ES l FR l GB l IT l NL l PL l US Any other value will default to US. Note: For recurring payments, the locale must be US. Note: For the list of country codes, see Appendix F, “Country Codes.”	No
PAGESTYLE	Sets the Custom Payment Page Style for payment pages associated with this button/link. This value corresponds to the HTML variable page_style for customizing payment pages. The value is the same as the Page Style Name you chose when adding or editing the page style from the Profile subtab of the My Account tab of your PayPal account. Character length and limitations: 30 single-byte alphabetic characters.	No
HDRIMG	A URL for the image you want to appear at the top left of the payment page. The image has a maximum size of 750 pixels wide by 90 pixels high. PayPal recommends that you provide an image that is stored on a secure (https) server. Character length and limitations: 127 single-byte alphanumeric characters	No
HDRBORDERCOLOR	Sets the border color around the header of the payment page. The border is a 2-pixel perimeter around the header space, which is 750 pixels wide by 90 pixels high. Character length and limitations: Six character HTML hexadecimal color code in ASCII	No
HDRBACKCOLOR	Sets the background color for the header of the payment page. By default, the color is white. Character length and limitation: Six character HTML hexadecimal color code in ASCII	No
PAYFLOWCOLOR	Sets the background color for the payment page. Character length and limitation: Six character HTML hexadecimal color code in ASCII	No
EMAIL	Email address of the buyer as entered during checkout. PayPal uses this value to pre-fill the PayPal membership sign-up portion of the PayPal login page. Character length and limit: 127 single-byte alphanumeric characters	No

SetCustomerBillingAgreementResponse

The SetCustomerBillingAgreementResponse message consists of the fields identified in Table A.47

Table A.47

SetCustomerBillingAgreementResponse Fields

Element	Description/Data Type
TOKEN	A unique time-stamped token, which uniquely identifies this transaction for subsequent API calls. Note: The token expires after three hours. Character length and limitations: 20 single-byte characters

GetBillingAgreementCustomerDetails

GetBillingAgreementCustomerDetails Request

The GetBillingAgreementCustomerDetailsRequest message consists of the fields identified in Table A.48.

Table A.48

GetBillingAgreementCustomerDetailsRequest Fields

Element	Description/Data Type	Required
METHOD	Name of API: GetBillingAgreementCustomerDetails	Yes
TOKEN	The time-stamped token returned in the SetCustomerBillingAgreement response. Note: The token expires after three hours. Character length and limitations: 20 single-byte characters	Yes

GetBillingAgreementCustomerDetails Response

The GetBillingAgreementCustomerDetailsResponse message consists of the fields identified in Table A.49

Table A.49

GetBillingAgreementCustomerDetailsResponse Fields

Element	Description/Data Type
EMAIL	Email address of payer Character length and limitations: 127 single-byte characters
PAYERID	Unique customer ID. Character length and limitations: 13 single-byte alphanumeric characters.
PAYERSTATUS	Status of payer’s email address: Verified Unverified
SALUTATION	Payer’s salutation Character length and limitations: 20 single-byte characters
FIRSTNAME	Payer’s first name Character length and limitations: 25 single-byte characters
MIDDLENAME	Payer’s middle name Character length and limitations: 25 single-byte characters
LASTNAME	Payer’s last name Character length and limitations: 25 single-byte characters
SUFFIX	Payer’s suffix Character length and limitations: 12 single-byte characters
SHIPTOCOUNTRYCODE	Payment sender’s country of residence using standard two-character ISO 3166 country codes. Character length and limitations: Two single-byte characters For the list of country codes, see Appendix F, “Country Codes.”
PAYERBUSINESS	Payer’s business name. Character length and limitations: 127 single-byte characters
PHONENUM	Payer’s contact telephone number. Note: PayPal returns a contact telephone number only if your Merchant account profile settings require that the buyer enter one. Character length and limitations: Field mask is XXX-XXX-XXXX (for US numbers) or +XXX XXXXXXXX (for international numbers)
Ship To Address	See Table A.11, “Ship to Address (Optional)”.

DoReferenceTransaction

DoReferenceTransaction Request

 

Table A.50

DoReferenceTransactionRequest Fields

NVP Name	Data Type/Description	Required
METHOD	Name of API: DoReferenceTransaction	Yes
REFERENCEID	Create a new transaction based on: l Billing agreement ID l Transaction ID l Preapproved payments ID l Reference ID	Yes
PAYMENTACTION	How you want to obtain payment: l Authorization indicates that this payment is a basic authorization subject to settlement with PayPal Authorization & Capture. l Sale indicates that this is a final sale for which you are requesting payment.	Yes
AMT	Total of order, including shipping, handling, and tax. Note: Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Note: You must set the currencyID attribute to one of the three-character currency codes for any of the supported PayPal currencies.	Yes
ITEMAMT	Sum of cost of all items in this order. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).	No
SHIPPINGAMT	Total shipping costs for this order. Note: Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. Note: You must set the currencyID attribute to one of the three-character currency codes for any of the supported PayPal currencies.	No
HANDLINGAMT	Total handling costs for this order. Note: Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. Note: You must set the currencyID attribute to one of the three-character currency codes for any of the supported PayPal currencies.	No
TAXAMT	Sum of tax for all items in this order. Note: Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. Note: You must set the currencyID attribute to one of the three-character currency codes for any of the supported PayPal currencies. Currency code must be set the same as for AMT.	No
DESC	Description of items the customer is purchasing. Character length and limitations: 127 single-byte alphanumeric characters	No
CUSTOM	A free-form field for your own use. Character length and limitations: 256 single-byte alphanumeric characters	No
INVNUM	Your own invoice or tracking number. Character length and limitations: 127 single-byte alphanumeric characters	No
BUTTON SOURCE	An identification code for use by third-party applications to identify transactions. Character length and limitations: 32 single-byte alphanumeric characters	No
NOTIFYURL	Your URL for receiving Instant Payment Notification (IPN) about this transaction. IMPORTANT: If you do not specify this value in the request, the notification URL from your Merchant Profile is used, if one exists. Character length and limitations: 2,048 single-byte alphanumeric characters	No
SHIPTONAME	Person’s name associated with this address. Character length and limitations: 32 single-byte characters	Yes
SHIPTOSTREET	First street address. Character length and limitations: 100 single-byte characters	Yes
SHIPTOCITY	Name of city. Character length and limitations: 40 single-byte characters	Yes
SHIPTOSTATE	State or province. Character length and limitations: 40 single-byte characters For state or province abbreviations, see “State and Province Abbreviations”.” Required for US addresses only.	No
SHIPTOZIP	U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters	Yes
SHIPTOCOUNTRYCODE	Country code. Character limit: Two single-byte characters For the list of country codes, see Appendix F, “Country Codes.”	Yes
SHIPTOSTREET2	Second street address. Character length and limitations: 100 single-byte characters	No
SHIPTOPHONENUM	Phone number. Character length and limit: 20 single-byte characters	No
L_DESCn	Item name. Character length and limitations: 127 single-byte characters	No
L_AMTn	Cost of item Note: Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. Note: You must set the currencyID attribute to one of the three-character currency codes for any of the supported PayPal currencies.	No
L_NUMBERn	Item number. Character length and limitations: 127 single-byte characters	No
L_QTYn	Item quantity. Character length and limitations: Any positive integer	No
L_TAXAMTn	Item sales tax. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Currency code is set the same as for OrderTotal.	No
SOFTDESCRIPTOR	The soft descriptor is a per transaction description of the payment that is passed to the consumer’s credit card statement. If a value for the soft descriptor field is provided, the full descriptor displayed on the customer’s statement has the following format: <PP * | PAYPAL *><Merchant descriptor as set in the Payment Receiving Preferences><1 space><soft descriptor> The soft descriptor can contain only the following characters: l Alphanumeric characters l - (dash) l * (asterisk) l . (period) l {space} If you use any other characters (such as “,”), an error code is returned. The soft descriptor does not include the phone number, which can be toggled between the merchant’s customer service number and PayPal’s customer service number. The maximum length of the total soft descriptor is 22 characters. Of this, either 4 or 8 characters are used by the PayPal prefix shown in the data format. Thus, the maximum length of the soft descriptor passed in the API request is: 22 - len(<PP * | PAYPAL *>) - len(<Descriptor set in Payment Receiving Preferences> + 1) For example, assume the following conditions: l The PayPal prefix toggle is set to PAYPAL * in PayPal’s admin tools l The merchant descriptor set in the Payment Receiving Preferences is set to EBAY. l The soft descriptor is passed in as JanesFlowerGifts LLC The resulting descriptor string on the credit card would be: PAYPAL *EBAY JanesFlow	No
RETURNFMFDETAILS	Flag to indicate whether you want the results returned by Fraud Management Filters. By default, you do not receive this information. l 0 - do not receive FMF details (default) l 1 - receive FMF details	No

The following fields are valid only for direct credit card reference transactions.

Table A.51

Additional Fields for Direct Credit Card Reference Transactions

NVP Name	Data Type/Description	Required
IPADDRESS	IP address of the payer’s browser. Important: PayPal records this IP addresses as a means to detect possible fraud. Character length and limitations: 15 single-byte characters, including periods, for example: 255.255.255.255.	No
CREDITCARDTYPE	Type of credit card. Character length and limitations: Up to ten single-byte alphabetic characters. The credit card can be one of the following values: l Visa l MasterCard l Discover l Amex l Switch l Solo	Yes
ACCT	Credit card number Character length and limitations: numeric characters only. No spaces or punctutation. Must conform with modulo and length required by each credit card type.	Yes
EXPDATE	Credit card expiration date. Format: MMYYYY Character length and limitations: Six single-byte numeric characters, including leading zero.	Yes
CVV2	Card Verification Value, version 2. Note: Your Merchant Account settings determine whether this field is required. Character length for Visa, MasterCard, and Discover: exactly three digits. Character length for American Express: exactly four digits. Important: To comply with credit card processing regulations, once a transaction has been completed, you must not store the value of CVV2.	See description
EMAIL	Email address of payer. Character length and limitations: 127 single-byte characters	No
PAYERID	Unique PayPal customer account identification number. Character length and limitations:13 single-byte alphanumeric characters.	No
FIRSTNAME	Payer’s first name. Character length and limitations: 25 single-byte characters	Yes
LASTNAME	Payer’s last name. Character length and limitations: 25 single-byte characters	Yes
STREET	First street address. Character length and limitations: 100 single-byte characters	No
CITY	Name of city. Character length and limitations: 40 single-byte characters	No
STATE	State or province. Character length and limitations: 40 single-byte characters For state or province abbreviations, see “State and Province Abbreviations”.	No
COUNTRYCODE	Country code. Character length and limitations: Two single-byte characters. For the list of country codes, see Appendix F, “Country Codes.”	No
ZIP	U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters	No

DoReferenceTransactionResponse

 

Table A.52

DoReferenceTransactionResponse Fields

NVP Name	Data Type/Description
TRANSACTIONID	Unique transaction ID of the payment. Note: If the PaymentAction of the request was Authorization, the value of TransactionID is your AuthorizationID for use with the Authorization & Capture APIs. Character length and limitations: 19 single-byte characters
AMT	The final amount charged, including any shipping and taxes from your Merchant Profile. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD. This value is the amount of the payment as specified by you on DoDirectPaymentRequest.
FEEAMT	Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD. PayPal fee amount charged for the transaction Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.
SETTLEAMT	Amount deposited in your PayPal account after a currency conversion.
TAXAMT	Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD. Tax charged on the transaction. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.
EXCHANGERATE	Exchange rate if a currency conversion occurred. Relevant only if your are billing in their non-primary currency. If the customer chooses to pay with a currency other than the non-primary currency, the conversion occurs in the customer’s account. Character length and limitations: a decimal that does not exceed 17 characters, including decimal point
PAYMENTSTATUS	Status of the payment: Completed: The payment has been completed, and the funds have been added successfully to your account balance. Pending: The payment is pending. See the PendingReason element for more information.
PENDINGREASON	The reason the payment is pending: l none: No pending reason l address: The payment is pending because your customer did not include a confirmed shipping address and your Payment Receiving Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile. l echeck: The payment is pending because it was made by an eCheck that has not yet cleared. l intl: The payment is pending because you hold a non-U.S. account and do not have a withdrawal mechanism. You must manually accept or deny this payment from your Account Overview. l multi-currency: You do not have a balance in the currency sent, and you do not have your Payment Receiving Preferences set to automatically convert and accept this payment. You must manually accept or deny this payment. l verify: The payment is pending because you are not yet verified. You must verify your account before you can accept this payment. l other: The payment is pending for a reason other than those listed above. For more information, contact PayPal customer service.
REASONCODE	The reason for a reversal if TransactionType is reversal: l none: No reason code l chargeback: A reversal has occurred on this transaction due to a chargeback by your customer. l guarantee: A reversal has occurred on this transaction due to your customer triggering a money-back guarantee. l buyer-complaint: A reversal has occurred on this transaction due to a complaint about the transaction from your customer. l refund: A reversal has occurred on this transaction because you have given the customer a refund. l other: A reversal has occurred on this transaction due to a reason not listed above.
BILLING AGREEMENTID	The Billing agreement associated with this transaction. This field is returned only for express checkout reference transaction.
L_FMFfilterIDn	Filter ID, including the filter type, which is either ACCEPT or DENY, and the entry number, starting from 0.
L_FMFfilterNAMEn	Filter name, including the filter type, which is either ACCEPT or DENY, and the entry number, starting from 0.

Table A.53

Additional Response Fields for Direct Credit Card Reference Transactions

NVP Name	Data Type/Description
AVSCODE	Address Verification System response code. Character limit: One single-byte alphanumeric character See Table A.2, “AVS Response Codes for Visa, MasterCard, Discover, and American Express,” on page 55.
CVV2MATCH	Result of the CVV2 check by PayPal. See Table A.3, “CVV2 Response Codes for Visa, MasterCard, Discover, and American Express,” on page 56.

Non-Referenced Credits

DoNonReferencedCredit

DoNonReferencedCreditRequest

The DoNonReferencedCredit request comprises the fields in Table A.54.

Table A.54

DoNonReferencedCredit Request Fields

Field	Data Type/Description	Required?
METHOD	Name of the API: DoNonReferencedCredit	Yes
AMT	Total of order, including shipping, handling, and tax. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). AMT = NETAMT + SHIPPINGAMT + TAXAMT	Yes
NETAMT	Total amount of all items in this transaction. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD	No
SHIPPINGAMT	Total shipping costs in this transaction. Limitations: Value must be zero or greater and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.	No
TAXAMT	Sum of tax for all items in this order. Limitations: The value must be zero or greater and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.	No
CURRENCYCODE	Currency code. Default: USD. Limitations: The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.	Yes
NOTE	An information note used by merchant to record why this credit was issued to a buyer. Character length and limitations: String field, up 255 single-byte alphanumeric characters	No
CREDITCARDTYPE	Type of credit card. Character length and limitations: Up to ten single-byte alphabetic characters. Allowable values: l Visa l MasterCard l Discover l Amex l Switch l Solo Note: If CREDITCARDTYPE is Switch or Solo, CURRENCYCODE must be GBP. Also, either STARTDATE or ISSUENUMBER must be specified.	Yes
ACCT	Credit card number Character length and limitations: numeric characters only. No spaces or punctutation. Must conform with modulo and length required by each credit card type.	Yes
EXPDATE	Credit-card expiration date. Format: MMYYYY Character length and limitations: 6 single-byte numeric characters, including leading zero if needed.	Yes
CVV2	Card Verification Value, version 2. Note: Your Merchant Account settings determine whether this field is required. Character length for Visa, MasterCard, and Discover: exactly three digits. Character length for American Express: exactly four digits. Important: To comply with credit card processing regulations, once a transaction has been completed, you must not store the value of CVV2.	See description
SALUTATION	Prefix of buyer’s name. Character format: String	No
FIRSTNAME	Payer’s first name. Character length and limitations: 25 single-byte characters	No
MIDDLENAME	Payer's (buyer's) middle name. Character length and limitations: 25 single-byte characters	No
LASTNAME	Payer’s last name. Character length and limitations: 25 single-byte characters	No
SUFFIX	Payer’s (buyer’s) name suffix. Character format: String	No
STREET	First street address. Character length and limitations: 100 single-byte characters Note: All address-related fields are for the billing address.	No
STREET2	Second street address. Character length and limitations: 100 single-byte characters	No
CITY	Name of city. Character length and limitations: 40 single-byte characters	No
STATE	State or province. Character length and limitations: 40 single-byte characters For state or province abbreviations, see “State and Province Abbreviations”.”	No
COUNTRYCODE	Country code. Character length and limitations: Two single-byte characters. For the list of country codes, see Appendix F, “Country Codes.”	No
COUNTRY	Country name. Character length and limitations: 2 single-byte characters	No
ZIP	U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters	No
PHONENUM	Phone number. Character length and limit: 20 single-byte characters	No
STARTDATE	Month that Switch or Solo card was issued. Format: MMYYYY Character length and limitations: 6 single-byte numeric characters, including leading zero if needed.	Yes if card type is Switch or Solo; otherwise, No
ISSUENUMBER	Issue number of Switch or Solo card. Character length: two numeric digits maximum.	No

DoNonReferencedCredit Response

The DoNonReferencedCredit response comprises the fields in Table A.55.

Table A.55

DoNonReferencedCredit Response Fields

Field	Description/Data Type
TRANSACTIONID	Unique identifier of a transaction Character length and limitations: 17 single-byte alphanumeric characters
CURRENCYCODE	Currency code. Default: USD. Limitations: The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.

GetBalance

 

Table A.56

GetBalance Request Parameters

Parameter	Description	Required?
METHOD	Name of API call: GetBalance	Yes
RETURNALLCURRENCIES	Whether to return all currencies, which is one of the following values: l 0 - Return only the balance for the primary currency holding l 1 - Return the balance for each currency holding Note: You can only use this option with API VERSION 51.0 and later.	No

Table A.57

GetBalance Response Fields

Field	Description
L_AMTn	The available balance for a currency holding. L_AMT0 always contains the available balance of the primary currency holding.
L_CURRENCYCODEn	The currency code associated with the holding, such as USD.

AddressVerify

 

Table A.58

AddressVerifyRequest

Parameter	Description	Required?
METHOD	Name of API call: AddressVerify	Yes
EMAIL	Email address of a PayPal member to verify. Maximum string length: 255 single-byte characters Input mask: ?@?.??	Yes
STREET	First line of the billing or shipping postal address to verify. To pass verification, the value of Street must match the first three single-byte characters of a postal address on file for the PayPal member. Street Maximum string length: 35 single-byte characters Alphanumeric plus - , . ‘ # \ Whitespace and case of input value are ignored.	Yes
ZIP	Postal code to verify. To pass verification, the value of Zip must match the first five single-byte characters of the postal code of the verified postal address for the verified PayPal member. Maximum string length: 16 single-byte characters Whitespace and case of input value are ignored.	Yes

Table A.59

AddressVerifyResponse

Element	Description
CONFIRMATIONCODE	None: The request value of the Email element does not match any email address on file at PayPal. Confirmed: If the response value of the StreetMatch element is Matched, the entire postal address is confirmed. Unconfirmed: PayPal responds that the postal address is unconfirmed. Note: The values Confirmed and Unconfirmed both indicate that the member email address passed verification.
STREETMATCH	None: The request value of the Email element does not match any email address on file at PayPal. No comparison of other request values was made. Matched: The request value of the Street element matches the first three single-byte characters of a postal address on file for the PayPal member. Unmatched: The request value of the Street element does not match any postal address on file for the PayPal member.
ZIPMATCH	None: The request value of the Street element was unmatched. No comparison of the Zip element was made. Matched: The request value of the Zip element matches the zip code of the postal address on file for the PayPal member. Unmatched: The request value of the Zip element does not match the zip code of the postal address on file for the PayPal member.
COUNTRYCODE	Two-character country code (ISO 3166) on file for the PayPal email address.
TOKEN	The token contains encrypted information about the member’s email address and postal address. If you pass the value of the token in the HTML variable address_api_token of Buy Now buttons, PayPal prevents the buyer from using an email address or postal address other than those that PayPal verified with this API call. The token is valid for 24 hours. Character length and limitations: 94 single-byte characters