SetExpressCheckout API Operation (NVP)

APILegacyLast updated: September 8th 2022, @ 6:04:23 pm


Important: NVP/SOAP is a legacy integration method. We accept new integrations and support existing integrations, but there are newer solutions. If you're starting an integration, we recommend our latest solutions.

Initiates an Express Checkout transaction.

SetExpressCheckout Request Message

SetExpressCheckout Request Fields

FieldDescription
METHOD

(Required) Must be SetExpressCheckout.

TOKEN

(Optional) A timestamped token that indicates Express Checkout processing for the current payment. This token is typically returned in the SetExpressCheckout response, but if you are calling SetExpressCheckout a second time, using the Express Checkout second redirect flow, you can pass the same token back to SetExpressCheckout as a request parameter. PayPal also appends this token as a GET parameter named token to your RETURN URL when redirecting the buyer back to your website from paypal.com. By default, the token expires after three hours. To extend the lifetime of a token to 72 hours, contact PayPal customer service.

Character length and limitations: 20 single-byte characters.

PAYMENTREQUEST_n_AMT

(Required) Total cost of the transaction to the buyer. 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. Set this field to 0 if the transaction does not include a one-time purchase such as when you set up a billing agreement for a recurring payment that is not immediately charged. When the field is set to 0, purchase-specific fields are ignored.

You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive; except for digital goods, which supports only single payments (set n to 0).

Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC`

MAXAMT

(Optional) The expected maximum total amount of the complete order, including shipping cost and tax charges. If the transaction includes one or more one-time purchases, this field is ignored.

For recurring payments, you should pass the expected average transaction amount (default 25.00). PayPal uses this value to validate the buyer's funding source.

Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC`

Note: This field is required when you implement the Instant Update API callback. PayPal recommends that the maximum total amount be slightly greater than the sum of the line-item order details, tax, and the shipping options of greatest value.
RETURNURL

(Required) URL to which the buyer's browser is returned after choosing to pay with PayPal. For digital goods, you must add JavaScript to this page to close the in-context experience.

Note: PayPal recommends that the value be the final review page on which the buyer confirms the order and payment or billing agreement.

Character length and limitations: 2048 single-byte characters.

CANCELURL

(Required) URL to which the buyer is returned if the buyer does not approve the use of PayPal to pay you. For digital goods, you must add JavaScript to this page to close the in-context experience.

Note: PayPal recommends that the value be the original page on which the buyer chose to pay with PayPal or establish a billing agreement.

Character length and limitations: 2048 single-byte characters.

CALLBACK

(Optional) The URL to which the callback request from PayPal is sent. It must start with HTTPS for production integration. It can start with HTTPS or HTTP for sandbox testing.

Character length and limitations: 1024 single-byte characters.

This field is available since version 53.0.

CALLBACKTIMEOUT

(Optional) An override for you to request more or less time to be able to process the callback request and respond. The acceptable range for the override is 1 to 6 seconds. If you specify a value greater than 6, PayPal uses the default value of 3 seconds.

Character length and limitations: An integer between 1 and 6.

NOSHIPPING

Determines whether PayPal displays shipping address fields on the PayPal pages. For digital goods, this field is required, and you must set it to 1. Value is:

  • 0 — PayPal displays the shipping address on the PayPal pages.
  • 1 — PayPal does not display shipping address fields and removes shipping information from the transaction.
  • 2 — If you do not pass the shipping address, PayPal obtains it from the buyer's account profile.

Character length and limitations: 1 single-byte numeric characters.

ADDROVERRIDE

(Optional) Determines whether or not 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 buyer. Displaying the PayPal street address on file does not allow the buyer to edit that address. Value is:

  • 0 — The PayPal pages should not display the shipping address.
  • 1 — The PayPal pages should display the shipping address.

Character length and limitations: 1 single-byte numeric character.

CALLBACKVERSION

Version of the callback API. This field is required when implementing the Instant Update Callback API. It must be set to 61.0 or a later version.

This field is available since version 61.0.

LOCALECODE

(Optional) Locale of the pages displayed by PayPal during Express Checkout. It is either a two-letter country code or five-character locale code supported by PayPal.

Note: If the locale code is not supplied or the supplied value is not one of the listed values, it is defaulted by PayPal. The default is determined using information about the current merchant, user, and other information for the session.

Character length and limitations: A two-letter country code or five-character locale code supported by PayPal.

LOGOIMG

(Optional) A URL to your logo image. Use a valid graphics format, such as .gif, .jpg, or .png. Limit the image to 190 pixels wide by 60 pixels high. PayPal crops images that are larger. PayPal places your logo image at the top of the cart review area.

Note: PayPal requires that you store the image on a secure (https) server.

Character length and limit: 127 single-byte alphanumeric characters.
This field is available since version 63.0.

EMAIL

(Optional) Email address of the buyer as entered during checkout. PayPal uses this value to pre-fill the PayPal membership signup portion on the PayPal pages.

Character length and limitations: 127 single-byte alphanumeric characters.

SOLUTIONTYPE

(Required in the US. By default, turns off guest checkout in the US. Optional in other countries.)

Type of checkout flow.
Value is:

  • Sole — Buyer can check out without creating a PayPal account. This is referred to as PayPal Account Optional.
  • Mark — Buyer must have a PayPal account to check out.
Note: You can pass Mark to selectively override the PayPal Account Optional setting if PayPal Account Optional is turned on in your merchant account. Passing Sole has no effect if PayPal Account Optional is turned off in your account.
LANDINGPAGE

(Optional) Type of PayPal page to display. Value is:

  • Billing — Non-PayPal account
  • Login — PayPal account login
CHANNELTYPE

(Optional) Type of channel. Value is:

  • Merchant — Non-auction seller
  • eBayItem — eBay auction

TOTALTYPE

(Optional) Type declaration for the label to be displayed in MiniCart for UX. Value is:

  • Total

  • EstimatedTotal

GIROPAYSUCCESSURL

(Optional) The URL on the merchant site to redirect to after a successful giropay payment.

Note: Use this field only if you are using giropay or bank transfer payment methods in Germany.
GIROPAYCANCELURL

(Optional) The URL on the merchant site to redirect to after a successful giropay payment.

Note: Use this field only if you are using giropay or bank transfer payment methods in Germany.
BANKTXNPENDINGURL

(Optional) The URL on the merchant site to transfer to after a bank transfer payment.

Note: Use this field only if you are using giropay or bank transfer payment methods in Germany.
BRANDNAME

(Optional) A label that overrides the business name in the PayPal account on the PayPal hosted checkout pages.

Character length and limitations: 127 single-byte alphanumeric characters.
This field is available since version 60.0.

PAYMENTREQUEST_n_PAYMENTREASON

Indicates the type of transaction. Value is:

  • None — Transaction is not identified as a particular type.
  • Refund — Identifies the transaction as a refund.

AddressType Fields

FieldDescription
PAYMENTREQUEST_n_SHIPTONAME

xs:string
Person's name associated with this shipping address. It is required if using a shipping address.

Character length and limitations: 128 double-byte characters.

PAYMENTREQUEST_n_SHIPTOSTREETFirst street address. It is required if using a shipping address.

Character length and limitations: 100 single-byte characters.

PAYMENTREQUEST_n_SHIPTOSTREET2

(Optional) Second street address.

Character length and limitations: 100 single-byte characters.

PAYMENTREQUEST_n_SHIPTOCITY

Name of city. It is required if using a shipping address.

Character length and limitations: 40 single-byte characters.

PAYMENTREQUEST_n_SHIPTOSTATEState or province.
`partial:partials/docs/shared/cl_shiptostate.en-XC`

Character length and limitations: 40 single-byte characters.

PAYMENTREQUEST_n_SHIPTOZIPU.S. ZIP code or other country-specific postal code. It is required if using a U.S. shipping address and may be required for other countries.

Character length and limitations: 20 single-byte characters.

PAYMENTREQUEST_n_SHIPTOCOUNTRYCODE

Country code. It is required if using a shipping address.

Character length and limitations: 2 single-byte characters.

PAYMENTREQUEST_n_SHIPTOPHONENUM

(Optional) Phone number.

Character length and limitations: 20 single-byte characters.

Payment Details Type Fields

When implementing parallel payments, you can create up to 10 sets of payment details type parameter fields, each representing one payment you are hosting on your marketplace.

FieldDescription

PAYMENTREQUEST_n_AMT

(Required) Total cost of the transaction to the buyer. 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. Set this field to 0 if the transaction does not include a one-time purchase such as when you set up a billing agreement for a recurring payment that is not immediately charged. When the field is set to 0, purchase-specific fields are ignored. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive; except for digital goods, which supports single payments only.

Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC`

PAYMENTREQUEST_n_CURRENCYCODE

(Optional) A 3-character currency code (default is USD). You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive; except for digital goods, which supports single payments only.

Note: When multiple payments are passed in one transaction, all of the payments must have the same currency code.

PAYMENTREQUEST_n_ITEMAMT

Sum of cost of all items in this order. For digital goods, this field is required. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive; except for digital goods, which supports single payments only.

Note: PAYMENTREQUEST_n_ITEMAMT is required if you specify L_PAYMENTREQUEST_n_AMTm.

Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC`

PAYMENTREQUEST_n_SHIPPINGAMT

(Optional) Total shipping costs for this order. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive.

Note: If you specify a value for PAYMENTREQUEST_n_SHIPPINGAMT, you must also specify a value for PAYMENTREQUEST_n_ITEMAMT.

Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC`

PAYMENTREQUEST_n_INSURANCEAMT

(Optional) Total shipping insurance costs for this order. The value must be a non-negative currency amount or null if insurance options are offered. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive.

Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC`

PAYMENTREQUEST_n_SHIPDISCAMT

(Optional) Shipping discount for this order, specified as a negative number. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive. For example (PAYMENTREQUEST_0_SHIPDISCAMT, PAYMENTREQUEST_1_SHIPDISCAMT).

Character length and limitations: `partial:partials/docs/shared/cl_currencylimit_neg.en-XC`

PAYMENTREQUEST_n_INSURANCEOPTIONOFFERED

(Optional) Indicates whether insurance is available as an option the buyer can choose on the PayPal Review page. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive. Is one of the following values:

  • true — The Insurance option displays the string 'Yes' and the insurance amount. If true, the total shipping insurance for this order must be a positive number.
  • false — The Insurance option displays 'No.'

PAYMENTREQUEST_n_HANDLINGAMT

(Optional) Total handling costs for this order. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive.

Note: If you specify a value for PAYMENTREQUEST_n_HANDLINGAMT, you must also specify a value for PAYMENTREQUEST_n_ITEMAMT.

Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC`

PAYMENTREQUEST_n_TAXAMT

(Optional) Sum of tax for all items in this order. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive; except for digital goods, which supports single payments only.

Note: PAYMENTREQUEST_n_TAXAMT is required if you specify L_PAYMENTREQUEST_n_TAXAMTm

Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC`

PAYMENTREQUEST_n_DESC

(Optional) Description of items the buyer is purchasing. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive; except for digital goods, which supports single payments only.

Note: The value you specify is available only if the transaction includes a purchase. This field is ignored if you set up a billing agreement for a recurring payment that is not immediately charged.

Character length and limitations: 127 single-byte alphanumeric characters.

PAYMENTREQUEST_n_CUSTOM

(Optional) A free-form field for your own use. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive.

Note: The value you specify is available only if the transaction includes a purchase. This field is ignored if you set up a billing agreement for a recurring payment that is not immediately charged.

Character length and limitations: 256 single-byte alphanumeric characters.

PAYMENTREQUEST_n_INVNUM

(Optional) Your own invoice or tracking number.You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive; except for digital goods, which supports single payments only.

Note: PayPal recommends using this field to associate transactions with your internal tracking IDs or invoice numbers; populating the invoice ID field will help you pull transaction information at a later date using only your internal ID.
Important: The value you specify is available only if the transaction includes a purchase. This field is ignored if you set up a billing agreement for a recurring payment that is not immediately charged.

Character length and limitations: 256 single-byte alphanumeric characters.

PAYMENTREQUEST_n_NOTIFYURL

(Optional) Your URL for receiving Instant Payment Notification (IPN) about this transaction. If you do not specify this value in the request, the notification URL from your Merchant Profile is used, if one exists.You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive; except for digital goods, which supports single payments only.

Important: The notify URL applies only to DoExpressCheckoutPayment. This value is ignored when set in SetExpressCheckout or GetExpressCheckoutDetails.

Character length and limitations: 2,048 single-byte alphanumeric characters.

PAYMENTREQUEST_n_MULTISHIPPING

(Optional) The value 1 indicates that this payment is associated with multiple shipping addresses.

Character length and limitations: Four single-byte numeric characters.

PAYMENTREQUEST_n_NOTETEXT

(Optional) Note to the merchant. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive.

Character length and limitations: 255 single-byte characters.

NOTETOBUYER

(Optional) A note from the merchant to the buyer that will be displayed in the PayPal checkout window.

Character length and limitations: 165 single-byte characters.

PAYMENTREQUEST_n_ALLOWEDPAYMENTMETHOD

(Optional) The payment method type. Specify the value InstantPaymentOnly. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive.

PAYMENTREQUEST_n_PAYMENTACTION

(Conditional) Defines how to obtain payment. Required for parallel payments and digital goods.

You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive; except in the case of digital goods, which supports single payments only and where n is 0. If the transaction does not include a one-time purchase, this field is ignored. Values are:
  • Sale — This is a final sale for which you are requesting payment (default).
  • Authorization — This payment is a basic authorization subject to settlement with PayPal Authorization and Capture.
  • Order — This payment is an order authorization subject to settlement with PayPal Authorization and Capture.
Note: You cannot set this field to Sale in SetExpressCheckout request and then change the value to Authorization or Order in the DoExpressCheckoutPayment request. If you set the field to Authorization or Order in SetExpressCheckout, you may set the field to Sale.

Character length and limitations: Up to 13 single-byte alphabetic characters.

PAYMENTREQUEST_n_PAYMENTREQUESTID

A unique identifier of the specific payment request, which is required for parallel payments. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive.

Character length and limitations: Up to 127 single-byte characters.

PAYMENTREQUEST_n_BUCKETCATEGORYTYPE(Optional) The category of a payment. Value is:
  • 1 — International shipping
  • 2 — Local delivery
  • 3BOPIS, Buy online pick-up in store
  • 4PUDO, Pick-up drop-off
PAYMENTREQUEST_n_LOCATION_TYPE(Optional) Type of merchant location. Set this field if the items purchased will not be shipped, such as, BOPIS (buy online pick-up in store) transactions. Value is:

  • 1 — Consumer
  • 2 — Store, for BOPIS (buy online pick-up in store) transactions
  • 3 — PickupDropoff, for PUDO (pick-up drop-off) transactions
PAYMENTREQUEST_n_LOCATION_ID(Optional) Location ID specified by the merchant for BOPIS (buy online pick-up in store) or PUDO (pick-up drop-off) transactions.

Payment Details Item Type Fields

Note: If you provide PayPal a user's itemized shopping cart list and a mismatch occurs between the sum of those items and the transaction total, PayPal processes the transaction using the sum of the cart items only when the difference is within $0.50.

FieldDescription
L_PAYMENTREQUEST_n_NAMEm

Item name. This field is required when L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment; except for digital goods, which supports single payments only. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_NAME0, L_PAYMENTREQUEST_n_NAME1).

Character length and limitations: 127 single-byte characters.

L_PAYMENTREQUEST_n_DESCm

(Optional) Item description. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment; except for digital goods, which supports single payments only. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_DESC0, L_PAYMENTREQUEST_n_DESC1).

Character length and limitations: 127 single-byte characters.

L_PAYMENTREQUEST_n_AMTm

(Required) Cost of item. This field is required for the payment details to appear to the buyer at checkout. It is also required when L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed.

You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment; except for digital goods, which supports single payments only. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_AMT0, L_PAYMENTREQUEST_n_AMT1).

Note: If you specify a value for L_PAYMENTREQUEST_n_AMTm, you must specify a value for PAYMENTREQUEST_n_ITEMAMT.

Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC`

Note: If the line item is a discount, a negative value must be passed in this field.
L_PAYMENTREQUEST_n_NUMBERm

(Optional) Item number. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_NUMBER0, L_PAYMENTREQUEST_n_NUMBER1).

Character length and limitations: 127 single-byte characters.

L_PAYMENTREQUEST_n_QTYm Item quantity. This field is required when L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed. For digital goods (L_PAYMENTREQUEST_n_ITEMCATEGORYm=Digital), this field is required. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment; except for digital goods, which only supports single payments. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_QTY0, L_PAYMENTREQUEST_n_QTY1).

Character length and limitations: Any positive integer.

L_PAYMENTREQUEST_n_TAXAMTm

(Optional) Item sales tax. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment; except for digital goods, which only supports single payments. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_TAXAMT0, L_PAYMENTREQUEST_n_TAXAMT1).

Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC`

L_PAYMENTREQUEST_n_ITEMWEIGHTVALUEm, L_PAYMENTREQUEST_n_ITEMWEIGHTUNITm

(Optional) Item weight corresponds to the weight of the item. You can pass this data to the shipping carrier as is without having to make an additional database query. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment;. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_ITEMWEIGHTVALUE0, L_PAYMENTREQUEST_n_ITEMWEIGHTVALUE1).

Character length and limitations: Any positive integer.

L_PAYMENTREQUEST_n_ITEMLENGTHVALUEm, L_PAYMENTREQUEST_n_ITEMLENGTHUNITm

(Optional) Item length corresponds to the length of the item. You can pass this data to the shipping carrier as is without having to make an additional database query. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_ITEMLENGTHVALUE0, L_PAYMENTREQUEST_n_ITEMLENGTHVALUE1).

Character length and limitations: Any positive integer.

L_PAYMENTREQUEST_n_ITEMWIDTHVALUEm, L_PAYMENTREQUEST_n_ITEMWIDTHUNITm

(Optional) Item width corresponds to the width of the item. You can pass this data to the shipping carrier as is without having to make an additional database query. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_ITEMWIDTHVALUE0, L_PAYMENTREQUEST_n_ITEMWIDTHVALUE1).

Character length and limitations: Any positive integer.

L_PAYMENTREQUEST_n_ITEMHEIGHTVALUEm, L_PAYMENTREQUEST_n_ITEMHEIGHTUNITm

(Optional) Item height corresponds to the height of the item. You can pass this data to the shipping carrier as is without having to make an additional database query. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_ITEMHEIGHTVALUE0, L_PAYMENTREQUEST_n_ITEMHEIGHTVALUE1).

Character length and limitations: Any positive integer.

L_PAYMENTREQUEST_n_ITEMURLm

(Optional) URL for the item. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_ITEMURL0, L_PAYMENTREQUEST_n_ITEMURL1).

L_PAYMENTREQUEST_n_ITEMCATEGORYmIndicates whether an item is digital or physical. For digital goods, this field is required and must be set to Digital. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment; except for digital goods, which only supports single payments. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_ITEMCATEGORY0, L_PAYMENTREQUEST_n_ITEMCATEGORY1). Value is:

  • Digital
  • Physical
Important: You must have permission from PayPal to use this field for Digital Goods.

This field is available since version 65.1.

Seller Details Type Field

FieldDescription
PAYMENTREQUEST_n_SELLERPAYPALACCOUNTIDUnique identifier for the merchant. For parallel payments, this field is required and must contain the Payer Id or the email address of the merchant. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive.

Character length and limitations: 127 single-byte alphanumeric characters.

EbayItemPaymentDetailsItem Type Fields

FieldDescription
L_PAYMENTREQUEST_n_EBAYITEMNUMBERm

(Optional) Auction item number. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_EBAYITEMNUMBER0, L_PAYMENTREQUEST_n_EBAYITEMNUMBER1).

Character length: 765 single-byte characters.

L_PAYMENTREQUEST_n_EBAYITEMAUCTIONTXNIDm

(Optional) Auction transaction identification number. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_EBAYITEMAUCTIONTXNID0, L_PAYMENTREQUEST_n_EBAYITEMAUCTIONTXNID1).

Character length: 255 single-byte characters.

L_PAYMENTREQUEST_n_EBAYITEMORDERIDm

(Optional) Auction order identification number. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_EBAYITEMORDERID0, L_PAYMENTREQUEST_n_EBAYITEMORDERID1).

Character length: 64 single-byte characters.

L_PAYMENTREQUEST_n_EBAYCARTIDm

(Optional) The unique identifier provided by eBay for this order from the buyer. You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m specifies the list item within the payment. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_EBAYITEMCARTID0, L_PAYMENTREQUEST_n_EBAYITEMCARTID1).

Character length: 255 single-byte characters.

Buyer Details Fields

FieldDescription
BUYERID

(Optional) The unique identifier provided by eBay for this buyer. The value may or may not be the same as the username. In the case of eBay, it is different.

Character length and limitations: 255 single-byte characters.

BUYERUSERNAME

xs:string

(Optional) The user name of the user at the platform site.

BUYERREGISTRATIONDATE

xs:dateTime

(Optional) Date when the user registered with the marketplace.

Character length and limitations: `partial:partials/docs/shared/cl_utcgmtdate_res.en-XC`

FundingSourceDetailsType Fields

FieldDescription
ALLOWPUSHFUNDING

(Optional) Indicates whether the merchant can accept push funding. Value is:

  • 0 — Merchant cannot accept push funding.
  • 1 — Merchant can accept push funding.
Note: This field overrides the setting in the merchant's PayPal account.

USERSELECTEDFUNDINGSOURCE

(Optional) This element could be used to specify the preferred funding option for a guest user. However, the LANDINGPAGE element must also be set to Billing. Otherwise, it is ignored.

  • ChinaUnionPay
  • CreditCard
  • ELV
  • QIWI

BILLING_AGREEMENT_ID

(Optional) The billing agreement ID that the merchant passes. This ID applies to future payments using reference transactions. The merchant passes the ID when they want to change the payment method for a specific reference transaction.

Shipping Options Type Fields

FieldDescription
L_SHIPPINGOPTIONISDEFAULTn(Required) The default shipping option that appears on the PayPal pages. This field is required if you specify the callback URL. Value is:
  • true — The default. PayPal displays this flat-rate shipping option and its amount as the default shipping option.
  • false — PayPal does not display this flat-rate shipping option and its amount as the default shipping option. If you specify false, you can adjust either or both of these values:
    • PAYMENTREQUEST_n_TAXAMT.

    • PAYMENTREQUEST_n_INSURANCEAMT.

Note: You must specify one and only one default shipping option.
L_SHIPPINGOPTIONNAMEn

Internal name of the shipping option such as Air, Ground, Expedited, and so forth. This field is required if you specify the Callback URL.

Character length and limitations: 50 character-string.

L_SHIPPINGOPTIONAMOUNTn

Amount of the flat rate shipping option. This field is required if you specify the Callback URL.

Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC`

Billing Agreement Details Type Fields

FieldDescription
L_BILLINGTYPEn

(Required) Type of billing agreement. For recurring payments, this field must be set to RecurringPayments.

Note: The n formatting is retained for backwards compatibility and can now only be 0. PayPal ignores any other numbers.

Type of billing agreement for reference transactions. You must have permission from PayPal to use this field. This field must be set to one of the following values:

  • MerchantInitiatedBilling - PayPal creates a billing agreement for each transaction associated with buyer. You must specify version 54.0 or higher to use this option.
  • MerchantInitiatedBillingSingleAgreement - PayPal creates a single billing agreement for all transactions associated with buyer. Use this value unless you need per-transaction billing agreements. You must specify version 58.0 or higher to use this option.
L_BILLINGAGREEMENTDESCRIPTIONn

Description of goods or services associated with the billing agreement. This field is required for the recurring payment billing agreement. There can only be one billing agreement type and one billing agreement description.

Note: The n formatting is retained for backwards compatibility and can now only be 0. PayPal ignores any other numbers.

PayPal recommends that the description contains a brief summary of the billing agreement terms and conditions. For example, buyer is billed at "9.99 per month for 2 years".

Character length and limitations: 127 single-byte alphanumeric characters.

L_PAYMENTTYPEn

(Optional) Type of PayPal payment you require for the billing agreement. Value is:

  • Any — The merchant accepts any payment method for the billing agreement, even if it could take a few working days for the movement of funds to the merchant account; this includes echeck, in addition to credit or debit cards and PayPal balance.

  • InstantOnly — The payment options accepted by the merchant are credit cards, debit cards or PayPal balance only because the merchant expects immediate payment.

Note: For recurring payments, this field is ignored.
L_BILLINGAGREEMENTCUSTOMn

(Optional) Custom annotation field for your own use.

Note: For recurring payments, this field is ignored.

Character length and limitations: 256 single-byte alphanumeric bytes.

Tax Id Details Type Fields

FieldDescription
TAXIDTYPE

Buyer's tax ID type. This field is required for Brazil and used for Brazil only.

For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for businesses.

This field is introduced in API version 72.0.

TAXID

Buyer's tax ID. This field is required for Brazil and used for Brazil only.

For Brazil use only: The tax ID is 11 single-byte characters for individuals and 14 single-byte characters for businesses.

This field is introduced in API version 72.0.

SetExpressCheckout Response Message

SetExpressCheckout Response Fields

FieldDescription
TOKENA timestamped token that indicates Express Checkout processing for the current payment. PayPal also appends this token as a GET parameter named token to your RETURN URL or CANCEL URL when redirecting the buyer back to your website from paypal.com. By default, the token expires after three hours. Contact PayPal customer service to extend the lifetime of a token to 72 hours.

Character length and limitations: 20 single-byte characters.

Deprecated Fields

The following fields are deprecated. Replacement fields are noted when available.

Deprecated SetExpressCheckout Request Fields

Deprecated fieldReplacement fieldSince Version/Date
ALLOWNOTE

(No replacement.)

(Optional) Enables the buyer to enter a note to the merchant on the PayPal page during checkout. The note is returned in the GetExpressCheckoutDetails response and the DoExpressCheckoutPayment response. Value is:

  • 0 — The buyer is unable to enter a note to the merchant.
  • 1 — The buyer is able to enter a note to the merchant.

Character length and limitations: 1 single-byte numeric character
This field is available since version 53.0.

September 2016
AMTPAYMENTREQUEST_n_AMT63
BUYEREMAILOPTINENABLE

(No replacement.)

(Optional) Enables the buyer to provide their email address on the PayPal pages to be notified of promotions or special events. Is one of the following values:

  • 0 – Do not enable buyer to provide email address.
  • 1 – Enable the buyer to provide email address.
In all versions
CARTBORDERCOLOR

(No replacement.)

(Optional) The HTML hex code for your principal identifying color. PayPal blends your color to white in a gradient fill that borders the cart review area of the PayPal checkout user interface.

Character length and limitation: 6 single-byte hexadecimal characters that represent an HTML hex code for a color.

September 2016
CUSTOMERSERVICENUMBER

(No replacement.)

(Optional) Merchant Customer Service number displayed on the PayPal pages.

Character length and limitations: 16 single-byte characters.

September 2016
GIFTMESSAGEENABLE

(No replacement.)

(Optional) Enables the gift message widget on the PayPal pages. Value is:

  • 0 — Do not enable gift message widget.
  • 1 — Enable gift message widget.
Sept. 8, 2016
GIFTRECEIPTENABLE

(No replacement.)

(Optional) Enable gift receipt widget on the PayPal pages. Value is:

  • 0 — Do not enable gift receipt widget.
  • 1 — Enable gift receipt widget.
Sept. 8, 2016
GIFTWRAPENABLE

(No replacement.)

(Optional) Enable gift wrap widget on the PayPal pages. Value is:

  • 0 — Do not enable gift wrap widget.
  • 1 — Enable gift wrap widget.
Note: If you pass the value 1 in this field, values for the gift wrap amount and gift wrap name are not passed, the gift wrap name is not displayed, and the gift wrap amount displays as 0.00.
Sept. 8, 2016
GIFTWRAPNAME

(No replacement.)

(Optional) Label for the gift wrap option such as "Box with ribbon".

Character length and limitations: 25 single-byte characters.

Sept. 8, 2016
GIFTWRAPAMOUNT

(No replacement.)

(Optional) Amount to be charged to the buyer for gift wrapping.

Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC`

Sept. 8, 2016
HDRBACKCOLOR

(No replacement.)

(Optional) Sets the background color for the header of the payment page. By default, the color is white.

Character length and limitations: 6-character HTML hexadecimal ASCII color code.

63
HDRBORDERCOLOR

(No replacement.)

(Optional) 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: 6-character HTML hexadecimal ASCII color code.

63
PAYMENTACTIONPAYMENTREQUEST_n_PAYMENTACTION63
HDRIMG

(Optional) 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 requires that you provide an image that is stored on a secure (https) server. If you do not specify an image, the business name displays.

Character length and limitations: 127 single-byte alphanumeric characters.

63
PAGESTYLE

(No replacement.)

(Optional) Name of the Custom Payment Page Style for payment pages associated with this button or link. It corresponds to the HTML variable page_style for customizing payment pages. It is the same name as the Page Style Name you chose to add or edit the page style in your PayPal Account profile.

Note: You can customize up to 3 different page styles in your PayPal account.

Character length and limitations: 30 single-byte alphabetic characters.

September 2016
PAYFLOWCOLOR

(No replacement.)

(Optional) Sets the background color for the payment page. By default, the color is white.

Character length and limitations: 6-character HTML hexadecimal ASCII color code.

September 2016
REQCONFIRMSHIPPING

(No replacement.)

Indicates whether or not you require the buyer's shipping address on file with PayPal be a confirmed address. For digital goods, this field is required, and you must set it to 0. Value is:

  • 0 — You do not require the buyer's shipping address be a confirmed address.
  • 1 — You require the buyer's shipping address be a confirmed address.
Note: Setting this field overrides the setting you specified in your Merchant Account Profile.

Character length and limitations: 1 single-byte numeric character.

September 2016
SURVEYQUESTION

(No replacement.)

(Optional) Text for the survey question on the PayPal pages. If the survey question is present, at least 2 survey answer options must be present.

Character length and limitations: 50 single-byte characters.

Sept. 8, 2016
SURVEYENABLE

(No replacement.)

(Optional) Enables survey functionality. Value is:

  • 0 — Disables survey functionality.
  • 1 — Enables survey functionality.
Sept. 8, 2016
L_SURVEYCHOICEn

(No replacement.)

(Optional) Possible options for the survey answers on the PayPal pages. Answers are displayed only if a valid survey question is present.

Character length and limitations: 15 single-byte characters.

Sept. 8, 2016

Deprecated Address Type Fields

Deprecated fieldReplacement fieldSince Version
SHIPTONAMEPAYMENTREQUEST_n_SHIPTONAME63
SHIPTOSTREETPAYMENTREQUEST_n_SHIPTOSTREET63
SHIPTOSTREET2PAYMENTREQUEST_n_SHIPTOSTREET263
SHIPTOCITYPAYMENTREQUEST_n_SHIPTOCITY63
SHIPTOSTATEPAYMENTREQUEST_n_SHIPTOSTATE63
SHIPTOZIPPAYMENTREQUEST_n_SHIPTOZIP63
SHIPTOCOUNTRYPAYMENTREQUEST_n_SHIPTOCOUNTRYCODE63
SHIPTOPHONENUMPAYMENTREQUEST_n_SHIPTOPHONENUM63

Deprecated Payment Details Type Fields

Deprecated fieldReplacement fieldSince Version
AMTPAYMENTREQUEST_n_AMT63
CURRENCYCODEPAYMENTREQUEST_n_CURRENCYCODE63
ITEMAMTPAYMENTREQUEST_n_ITEMAMT63
SHIPPINGAMTPAYMENTREQUEST_n_SHIPPINGAMT63
INSURANCEAMTPAYMENTREQUEST_n_INSURANCEAMT63
SHIPPINGDISCAMTPAYMENTREQUEST_n_SHIPDISCAMT63
INSURANCEOPTIONOFFEREDPAYMENTREQUEST_n_INSURANCEOPTIONOFFERED63
HANDLINGAMTPAYMENTREQUEST_n_HANDLINGAMT63
TAXAMTPAYMENTREQUEST_n_TAXAMT63
DESCPAYMENTREQUEST_n_DESC63
CUSTOMPAYMENTREQUEST_n_CUSTOM63
INVNUMPAYMENTREQUEST_n_INVNUM63
NOTIFYURLPAYMENTREQUEST_n_NOTIFYURL63
NOTETEXTPAYMENTREQUEST_n_NOTETEXT63
TRANSACTIONIDPAYMENTREQUEST_n_TRANSACTIONID63
ALLOWEDPAYMENTMETHODPAYMENTREQUEST_n_ALLOWEDPAYMENTMETHOD63
PAYMENTACTIONPAYMENTREQUEST_n_PAYMENTACTION63
PAYMENTREQUESTIDPAYMENTREQUEST_n_PAYMENTREQUESTID63

Deprecated Payment Details Item Type Fields

Deprecated fieldReplacement fieldSince Version
L_NAMEnL_PAYMENTREQUEST_n_NAMEm63
L_DESCnL_PAYMENTREQUEST_n_DESCm63
L_AMTnL_PAYMENTREQUEST_n_AMTm63
L_NUMBERnL_PAYMENTREQUEST_n_NUMBERm63
L_QTYnL_PAYMENTREQUEST_n_QTYm63
L_TAXAMTnL_PAYMENTREQUEST_n_TAXAMTm63
L_ITEMWEIGHTTVALUEnL_PAYMENTREQUEST_n_ITEMWEIGHTVALUEm63
L_ITEMWEIGHTUNITnL_PAYMENTREQUEST_n_ITEMWEIGHTUNITm63
L_ITEMLENGTHVALUEnL_PAYMENTREQUEST_n_ITEMLENGTHVALUEm63
L_ITEMLENGTHUNITnL_PAYMENTREQUEST_n_ITEMLENGTHUNITm63
L_ITEMWIDTHVALUEnL_PAYMENTREQUEST_n_ITEMWIDTHVALUEm63
L_ITEMWIDTHUNITnL_PAYMENTREQUEST_n_ITEMWIDTHUNITm63
L_ITEMHEIGHTVALUEnL_PAYMENTREQUEST_n_ITEMHEIGHTVALUEm63
L_ITEMHEIGHTUNITnL_PAYMENTREQUEST_n_ITEMHEIGHTUNITm63
L_ITEMURLnL_PAYMENTREQUEST_n_ITEMURLm63

Deprecated EbayItemPaymentDetailsItemType Fields

Deprecated fieldReplacement fieldSince Version
L_EBAYITEMNUMBERnL_PAYMENTREQUEST_n_EBAYITEMNUMBERm63
L_EBAYAUCTIONTXNIDnL_PAYMENTREQUEST_n_EBAYAUCTIONTXNIDm63
L_EBAYITEMORDERIDnL_PAYMENTREQUEST_n_EBAYITEMORDERIDm63
L_EBAYITEMCARTIDnL_PAYMENTREQUEST_n_EBAYITEMCARTIDm63

Additional information