SetExpressCheckout API Operation (SOAP)

The SetExpressCheckout API operation initiates an Express Checkout transaction.

SetExpressCheckout Request Message

SetExpressCheckout Request Fields

Field Description

MaxAmount

ebl:BasicAmountType

(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: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

Note This field is required when implementing 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.

Note You must set the currencyID attribute to one of the three-character currency codes for any of the supported PayPal currencies.

ReturnURL

xs:string

(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

xs:string

(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

CallbackURL

xs:string

(Optional) 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

int

(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

ReqConfirmShipping

xs:string

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. It is one of the following values:

  • 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

NoShipping

xs:string

Determines where or not PayPal displays shipping address fields on the PayPal pages. For digital goods, this field is required, and you must set it to 1. It is one of the following values:

  • 0 – PayPal displays the shipping address on the PayPal pages.

  • 1 – PayPal does not display shipping address fields whatsoever.

  • 2 – If you do not pass the shipping address, PayPal obtains it from the buyer's account profile.

Character length and limitations: 4 single-byte numeric characters

FlatRateShippingOptions

ebl:ShippingOptionsType

Flat rate shipping options. This field is required if you are specifying the Callback URL.

AllowNote

xs:string

(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. It is one of the following values:

  • 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.

PaymentDetails

ebl:PaymentDetailsType

(Required) Information about the payment.

AddressOverride

xs:string

(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. It is one of the following values:

  • 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

LocaleCode

xs:string

(Optional) Locale of pages displayed by PayPal during Express Checkout. It is one of the following values supported by PayPal:

  • AU – Australia
  • AT – Austria
  • BE – Belgium
  • BR – Brazil
  • CA – Canada
  • CH – Switzerland
  • CN – China
  • DE – Germany
  • ES – Spain
  • GB – United Kingdom
  • FR – France
  • IT – Italy
  • NL – Netherlands
  • PL – Poland
  • PT – Portugal
  • RU – Russia
  • US – United States
  • The following 5-character codes are also supported for languages in specific countries:

    • da_DK – Danish (for Denmark only)
    • he_IL – Hebrew (all)
    • id_ID – Indonesian (for Indonesia only)
    • ja_JP – Japanese (for Japan only)
    • no_NO – Norwegian (for Norway only)
    • pt_BR – Brazilian Portuguese (for Portugal and Brazil only)
    • ru_RU – Russian (for Lithuania, Latvia, and Ukraine only)
    • sv_SE – Swedish (for Sweden only)
    • th_TH – Thai (for Thailand only)
    • tr_TR – Turkish (for Turkey only)
    • zh_CN – Simplified Chinese (for China only)
    • zh_HK – Traditional Chinese (for Hong Kong only)
    • zh_TW – Traditional Chinese (for Taiwan only)

Note If the locale code is not supplied or the supplied value is not one of the above-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 2-character country code or 5-character code as specified above.

PageStyle

xs:string

(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

cpp-header-image

xs:string

(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 recommends 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

cpp-payflow-color

xs:string

(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

cpp-cart-border-color

xs:string

(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

cpp-logo-image

xs:string

(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 recommends that you store the image on a secure (https) server. Otherwise, web browsers display a message that checkout pages contain non-secure items.

Character length and limit: 127 single-byte alphanumeric characters

BuyerEmail

ebl:EmailAddressType

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

Character length and limitations: 127 single-byte alphanumeric characters

SolutionType

ebl:SolutionTypeType

(Optional) Type of checkout flow. It is one of the following values:

  • Sole – Buyer does not need to create a PayPal account to check out. 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

ebl:LandingPageType

(Optional) Type of PayPal page to display. It is one of the following values:

  • Billing – Non-PayPal account

  • Login – PayPal account login

ChannelType

ebl:ChannelType

(Optional) Type of channel. It is one of the following values:

  • Merchant – Non-auction seller

  • eBayItem – eBay auction

TotalType

ns:TotalType

(Optional) Type declaration for the label to be displayed in MiniCart for UX. It is one of the following values:

  • Total

  • EstimatedTotal

giropaySuccessURL

xs:string

(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

xs:string

(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

xs:string

(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.

BillingAgreement Details

ns:BillingAgreementDetailsType

(Optional) Billing agreement details.

Enhanced CheckoutData

ed:EnhancedCheckoutDataType

(Optional) Enhanced data for different industry segments. This field is for eBay use only.

OtherPaymentMethods

ns:OtherPaymentMethodDetailsType

(Optional) List of other payment methods with which the buyer can pay.

BuyerDetails

ns:BuyerDetailsType

(Optional) Details about the buyer's account.

BrandName

xs:string

(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

FundingSourceDetails

ns:FundingSourceDetailsType

(Optional) Funding source preferences.

CustomerServiceNumber

xs:string

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

Character length and limitations: 16 single-byte characters

GiftMessageEnable

xs:string

(Optional) Enables the gift message widget on the PayPal pages. It is one of the following values:

  • 0 – Do not enable gift message widget.

  • 1 – Enable gift message widget.

GiftReceiptEnable

xs:string

(Optional) Enable gift receipt widget on the PayPal pages. It is one of the following values:

  • 0 – Do not enable gift receipt widget.

  • 1 – Enable gift receipt widget.

GiftWrapEnable

xs:string

(Optional) Enable gift wrap widget on the PayPal pages. It is one of the following values:

  • 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.

GiftWrapName

xs:string

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

Character length and limitations: 25 single-byte characters

GiftWrapAmount

ebl:BasicAmounttype

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

Note You must set the currencyID attribute to one of the three-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

BuyerEmailOptInEnable

xs:string

(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.

SurveyQuestion

xs:string

(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

SurveyEnable

xs:string

(Optional) Enables survey functionality. It is one of the following values:

  • 0 – Disables survey functionality.

  • 1 – Enables survey functionality.

SurveyChoice

xs:string

(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

PaymentReason

ns:PaymentReasonType

Indicates the type of transaction. It is one of the following values:

  • None – Transaction is not identified as a particular type.

  • Refund – Identifies the transaction as a refund.

AddressType Fields

Field Description

Name

xs:string

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

Character length and limitations: 32 single-byte characters

Street1

xs:string

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

Character length and limitations: 100 single-byte characters

Street2

xs:string

(Optional) Second street address.

Character length and limitations: 100 single-byte characters

CityName

xs:string

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

Character length and limitations: 40 single-byte characters

StateOrProvince

xs:string

State or province.
It is required if the address is in one of the following countries: Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand or USA. PayPal accepts State codes for some countries.

Character length and limitations: 40 single-byte characters

PostalCode

xs:string

U.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

Country

ebl:CountryCodeType

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

Character length and limitations: 2 single-byte characters

Phone

xs:string

(Optional) Phone number.

Character length and limitations: 20 single-byte characters

PaymentDetailsType 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.

Field Description

OrderTotal

ebl:BasicAmountType

(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.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

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

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

ItemTotal

ebl:BasicAmountType

Sum of cost of all items in this order. For digital goods, this field is required.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

ShippingTotal

ebl:BasicAmountType

(Optional) Total shipping costs for this order.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

InsuranceTotal

ebl:BasicAmountType

(Optional) Total shipping insurance costs for this order. The value must be a non-negative currency amount or null if you offer insurance options.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

InsuranceTotal is available since version 53.0.

ShippingDiscount

ebl:BasicAmountType

(Optional) Shipping discount for this order, specified as a negative number.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a negative number. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

ShippingDiscount is available since version 53.0.

InsuranceOptionOffered

xs:boolean

(Optional) Indicates whether insurance is available as an option the buyer can choose on the PayPal Review page. 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.'

HandlingTotal

ebl:BasicAmountType

(Optional) Total handling costs for this order.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

TaxTotal

ebl:BasicAmountType

(Optional) Sum of tax for all items in this order.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

OrderDescription

xs:string

(Optional) Description of items the buyer is purchasing.

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

Custom

xs:string

(Optional) A free-form field for your own use.

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

InvoiceID

xs:string

(Optional) Your own invoice or tracking number.

Note PayPal recommends using the InvoiceID 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

NotifyURL

xs:string

(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.

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

ShipToAddress

ns:AddressType

(Optional) Address to which the order is shipped.

MultiShipping

xs:string

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

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

PaymentDetailsItem

ebl:PaymentDetailsItemType

(Optional) Details about each individual item included in the order.

EnhancedPaymentData

ed:EnhancedPaymentDataType

(Optional) Enhanced Data section to accept channel-specific data (eBay).

FulfillmentAddress

ebl:AddressType

(Optional) Address of the fulfillment center.

PaymentCategoryType

ebl:PaymentCategoryType

(Optional) Category of a payment. Possible values are:
InternationalShipping
LocalDelivery

NoteText

xs:string

(Optional) Note to the merchant.

Character length and limitations: 255 single-byte characters

TransactionId

xs:string

(Optional) Transaction identification number of the transaction that was created.

Note This field is only returned after a successful transaction for DoExpressCheckout has occurred.

AllowedPaymentMethod

ns:AllowedPaymentMethodType

(Optional) This is the payment solution for Autopay (used by Express Checkout). It is one of the following values:

  • Default – Merchant supports all funding sources.

  • InstantPaymentOnly – Merchant only supports instant payment.

  • AnyFundingSource – All funding methods allowed, to be chosen by the buyer irrespective of the merchant profile setting.

  • InstantFundingSource – Only instant funding methods are allowed. Block echeck, meft, elevecheck. This value overrides any merchant account profile settings.

PaymentAction

ebl:PaymentActionCodeType

How you want to obtain payment. When implementing parallel payments, this field is required and must be set to Order. When implementing digital goods, this field is required and must be set to Sale. If the transaction does not include a one-time purchase, this field is ignored. It is one of the following values:

  • 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

PaymentRequestID

xs:string

A unique identifier of the specific payment request, which is required for parallel payments.

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

PaymentDetailsItemType Fields

Field Description

Name

xs:string

Item name. This field is required when you pass a value for ItemCategory.

Character length and limitations: 127 single-byte characters

This field is introduced in version 53.0.

Description

xs:string

(Optional) Item description.

Character length and limitations: 127 single-byte characters

This field is introduced in version 53.0.

Amount

ebl:BasicAmountType

Cost of item. This field is required when you pass a value for ItemCategory.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

This field is introduced in version 53.0.

Number

xs:string

(Optional) Item number.

Character length and limitations: 127 single-byte characters

This field is introduced in version 53.0.

Quantity

xs:integer

Item quantity. This field is required when you pass a value for ItemCategory. For digital goods (ItemCategory=Digital), this field is required.

Character length and limitations: Any positive integer

This field is introduced in version 53.0.

Tax

ebl:BasicAmountType

(Optional) Item sales tax.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

ItemWeight

xs:integer

(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.

Character length and limitations: Any positive integer

ItemLength

xs:integer

(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.

Character length and limitations: Any positive integer

ItemWidth

xs:integer

(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.

Character length and limitations: Any positive integer

ItemHeight

xs:integer

(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.

Character length and limitations: Any positive integer

EbayItemPayment DetailsItem

eBl:ebayItemPaymentDetailsItemType

(Optional) Information relating to an auction sale on eBay.

ItemURL

xs:string

(Optional) URL for the item.

EnhancedItemData

ed:EnhancedItemDataType

(Optional) Enhanced data for each item in the cart. For eBay use only.

ItemCategory

ns:ItemCategoryType

Indicates whether an item is digital or physical. For digital goods, this field is required and must be set to Digital. It is one of the following values:

  • Digital

  • Physical

This field is available since version 65.1.

SellerDetailsType Fields

Field Description

PayPalAccountID

xs:string

Unique identifier for the merchant. For parallel payments, this field is required and must contain the Payer Id or the email address of the merchant.

Character length and limitations: 127 single-byte alphanumeric characters

EbayItemPaymentDetailsItemType Fields

Field Description

ItemNumber

xs:string

(Optional) Auction item number.

Character length: 765 single-byte characters

AuctionTransactionId

xs:string

(Optional) Auction transaction identification number.

Character length: 255 single-byte characters

OrderID

xs:string

(Optional) Auction order identification number.

Character length: 64 single-byte characters

CartID

xs:string

(Optional) The unique identifier provided by eBay for this order from the buyer.

Character length: 255 single-byte characters

BuyerDetailsType Fields

Field Description

BuyerId

xs:string

(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 marketplaces site.

BuyerRegistrationDate

xs:dateTime

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

Character length and limitations: Date and time are in UTC/GMT format; for example, 2013-08-24T05:38:48Z.

TaxIdDetails

ebl:TaxIdDetailsType

Details about the buyer's tax information. This field is required for Brazil and is for Brazil use only.

This field is introduced in API version 72.0.

FundingSourceDetailsType Fields

Field Description

AllowPushFunding

xs:string

(Optional) Indicates whether the merchant can accept push funding. It is one of the following values:

  • 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

ns:UserSelectedFundingSourceType

(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.

  • BML – Bill Me Later
  • ChinaUnionPay
  • CreditCard
  • ELV

ShippingOptionsType Fields

Field Description

ShippingOptionIsDefault

xs:boolean

Default shipping option displayed on the PayPal pages. This field is required if you specify the Callback URL. It is one of the following values:

  • true – This is the default flat-rate shipping option. PayPal displays this option and its amount by default.

  • false – This flat-rate shipping option and its amount are not displayed as the default.

Note There must be ONE and ONLY ONE default. It is not OK to have no default.

ShippingOptionName

xs:string

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.

ShippingOptionAmount

ebl:BasicAmountType

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

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

BillingAgreementDetailsType Fields

Field Description

BillingType

ns:BillingCodeType

(Required) Type of billing agreement. For recurring payments, this field must be set to RecurringPayments. In this case, you can specify up to ten billing agreements. Other defined values are not valid.

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.

BillingAgreement Description

xs:string

Description of goods or services associated with the billing agreement. This field is required for each recurring payment billing agreement. PayPal recommends that the description contain 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

PaymentType

ns:MerchantPullPaymentCodeType

(Optional) Type of PayPal payment you require for the billing agreement. It is one of the following values:

  • Any

  • InstantOnly

Note For recurring payments, this field is ignored.

BillingAgreement Custom

xs:string

(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

TaxIdDetailsType Type Fields

Field Description

TaxIdType

xs:string

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

xs:string

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

Note Not all fields shown are available for use. Only use fields described in the documentation.

SetExpressCheckout Response Fields

Field Description

Token

xs:string

A timestamped token by which you identify to PayPal that you are processing this payment with Express Checkout. The token expires after three hours.

Character length and limitations: 20 single-byte characters

Deprecated Fields

The following fields have been deprecated since version 53.0. Use the newer fields in the following table instead.

Deprecated SetExpressCheckout Request Fields

Field Use this field instead in PaymentDetailsType Fields
OrderTotal OrderTotal
OrderDescription OrderDescription
Custom Custom
InvoiceID InvoiceID
Address ShipToAddress
cpp-header-border-color (No replacement)
xs:string
(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.
cpp-header-back-color (No replacement)
xs:string
(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.
PaymentAction PaymentAction