Skip to main content

Request Fields

Initial Request (Hosted and Direct Integrations)​

These fields should be sent in addition to the Basic Request Fields excluding any card details.

Field NameMandatory?Description
paymentMethodYes[1]Must be the value ‘paypal’ in lower case only.
checkoutRedirectURLYes[2]URL on Merchant’s server to return to when the PayPal Checkout is closed.
checkoutOptionsNo[3]Record containing options used to customise the PayPal Checkout. Refer here.
payPalCheckoutOptionsNo[4]Record containing options used to customise the PayPal Checkout. Refer here.

Continuation Request (Direct Integration)​

These fields may be sent alone[5][5].

Field NameMandatory?Description
checkoutRefYesUnique reference return in the initial response.
checkoutResponseYesRecord containing the GET and or POST data received by the checkoutRedirectURL page.
checkoutOnlyNoPass Y to complete the processing as far as the next Checkout stage and then return with the loaded Checkout details.

[5] It is only necessary to send the checkoutRef and the checkoutResponse in the continuation request because the checkoutRef will identify the Merchant Account and initial request. You can send any of the normal request fields to modify or supplement the initial request. The message need not be signed but it is highly recommended that you do if not sending over a secure server to server connection. The checkoutRedirectURL and checkoutOptions fields sent in the initial request cannot be modified and any sent in the second request must match those used in the first request, or the second request will fail with a responseCode of 64442 (REQUEST MISMATCH).

Checkout Options (Hosted and Direct Integrations)​

The following options may be set in the payPalCheckoutOptions Hosted Integration field or the checkoutOptions Direct Integration field to customise the PayPal Checkout. The options must be formatted using the record or serialised record formats.

Sub-Field NameDescription
inContext

Use the in-context PayPal Checkout rather than the full screen Checkout when possible.

Possible values are:

0 – use the full screen Checkout.

1 – use the in-context Checkout if possible.

userAction

Determines whether buyers complete their purchases on PayPal or on your website.

Possible values are:

commit – sets the submit button text to ‘Pay Now’ on the PayPal Checkout. This text lets buyers know that they complete their purchases if they click the button.

continue– sets the submit button text to ‘Continue’ on the PayPal Checkout. This text lets buyers know that they will return to the Merchant’s cart to complete their purchases if they click the button.

maxAmountThe expected maximum total amount of the order, including shipping and taxes. PayPal refer to this field as MAXAMT.
reqBillingAddressDetermines whether the buyer’s billing address on file with PayPal is returned. This feature must be enabled by PayPal.
reqConfirmShipping

Determines whether the buyer’s shipping address on file with PayPal must be a confirmed address.

Possible values are:

0 – does not need to be confirmed

1 – must be confirmed

noShipping

Determines whether PayPal displays shipping address.

Possible values are:

0 – display the shipping address

1 – do not display shipping address and remove shipping information

2 – If no deliveryXXXX fields passed, PayPal obtains them from the buyer's account profile.

addrOverride

Determines whether the PayPal Checkout displays the shipping address sent using the deliveryXXXX fields and 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.

Possible values are:

0 – PayPal should not display the address.

1 – PayPal should display the address.

localeCodeLocale 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.
allowNoteEnables the buyer to enter a note to the merchant on the PayPal page during Checkout. The note is returned in the checkoutDetails response field.
pageStyleName of the Custom Payment Page Style used for the PayPal Checkout. It is the same name as the Page Style Name used when adding styles in the PayPal Account.
payflowColorThe HTML hex colour code for the PayPal Checkout’s background colour. By default, the colour is white (FFFFFF).
cardBorderColorThe HTML hex colour code for the PayPal Checkout’s principal identifying colour. The colour will be blended to white in a gradient fill that borders the cart review area.
hdrImgURL 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.
logoImgA 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.
landingPage

Type of PayPal Checkout to display.

Possible values are:

Billing – Non-PayPal account

Login – PayPal account login

channelType

Type of channel.

Possible values are:

Merchant – Non-auction seller

eBayItem – eBay auction

solutionType

Type of Checkout flow.

Possible values are:

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.

totalType

Type declaration for the label to be displayed in MiniCart for UX.

Possible values are:

Total

EstimatedTotal

brandNameA label that overrides the business name in the PayPal account on the PayPal Checkout.
customerServiceNumberMerchant Customer Service number displayed on the PayPal Checkout.
buyerEmailOptInEnable

Enables the buyer to provide an email address on the PayPal pages to be notified of promotions or special events.

Possible values are:

0 – Do not enable buyer to provide email.

1 – Enable the buyer to provide email.

noteToBuyerA note from the merchant to the buyer that will be displayed in the PayPal Checkout.
paymentAction

Defines how to obtain payment. This can be used to override any captureDelay setting that can also be used to indicate a Sale or Authorisation only.

Possible values are:

Sale – sale with immediate capture.

Authorization – authorisation subject to later capture (note spelling).

Order – order subject to later authorisation and capture.

allowedPaymentMethodThe payment method type. Specify the value InstantPaymentOnly
insuranceOptionOffered

Indicates whether insurance is available as an option that the buyer can choose on the PayPal Review page.

Possible values are:

true – The Insurance option displays 'Yes' and the insuranceAmount. If true, the total shipping insurance for this order must be a positive number.

false – The Insurance option displays 'No'.

multiShipping

Indicates whether this payment is associated with multiple shipping addresses.

Possible values are:

0 – Single/No shipping address.

1 – Multiple shipping addresses.

noteTextNote to the Merchant.
bucketCategoryType

The category of a payment.

Possible values are:

1 – International shipping

2 – Local delivery

3 – BOPIS, Buy online pick-up in store

4 – PUDO, Pick-up drop-off

locationType

Type of merchant location. Required if the items purchased will not be shipped, such as, BOPIS (Buy Online Pick-up In Store) or PUDO (Pick-Up Drop-Off) transactions.

Possible values are:

1 – Consumer.

2 – Store, for BOPIS transactions.

3 – PickupDropoff, for PUDO transactions.

locationIDLocation ID specified by the merchant for BOPIS (Buy Online Pick-up In Store) or PUDO (Pick-Up Drop-Off) transactions.
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.
invNumMerchant’s invoice or tracking number.
customCustom field for your own use.
buyerIDThe 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.
buyerUsernameThe username of the user at the marketplaces site.
buyerRegistrationDateDate when the user registered with the marketplace. In UTC/GMT format, for example, 2013-08-24T05:38:48Z.
allowPushFunding

Indicates whether the Merchant can accept push funding.

Possible values are:

0 – Merchant cannot accept push funding.

1 – Merchant can accept push funding.

userSelectedFundingSource

This element could be used to specify the preferred funding option for a guest user. However, the landingPage Checkout option must also be set to Billing, otherwise, it is ignored.

Possible values are:

ChinaUnionPay.

CreditCard.

ELV.

QIWI.

billingType

Type of billing agreement for reference transactions. You must have permission from PayPal to use this field.

Possible values are:

MerchantInitiatedBilling – PayPal creates a billing agreement for each transaction associated with buyer.

MerchantInitiatedBillingSingleAgreement – PayPal creates a single billing agreement for all transactions associated with buyer. Use this value unless you need per-transaction billing agreements.

billingAgreementDescriptionDescription 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".
paymentType

Type of PayPal payment you require for the billing agreement.

Possible values are:

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.

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.

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

returnFMFDetails

Flag to indicate whether you want the results returned by Fraud Management Filters when doing a recurring/reference transaction.

Possible values are:

0 – Do not receive FMF details (default).

1 – Receive FMF details.

riskSessionCorrelationIDThe ID of the risk session for correlation purposes when doing a recurring/reference transaction.
merchantSessionIDThe buyer session identification token when doing a recurring/reference transaction.
buttonSource[6]PayPal Partner’s BN Code (if required).

For further information on the options, refer to the PayPal Express Checkout documentation: https://developer.paypal.com/api/nvp-soap/set-express-checkout-nvp/

Purchase details (Hosted and Direct Integrations)​

The following request fields may be sent to provide information on the purchased items and to populate the cart on the PayPal Checkout.

Field NameMandatory?Description
shippingAmountNoShipping costs.
shippingDiscountAmountNoDiscount applied to shipping costs.
handlingAmountNoHandling costs.
insuranceAmountNoInsurance costs.
itemXXDescriptionNoDescription of XXth item purchased.
itemXXQuantityNoQuantity of XXth item purchased.
itemXXAmountNoGross amount for XXth item purchased.
itemXXTaxAmountNoTax amount for XXth item purchased.
itemXXProductCodeNoProduct code for XXth item purchased.
itemXXProductURLNoShopping cart URL for XXth item purchased.
itemXXSizeNoSize of XXth item purchased in the format ‘LengthxWidthxHeight Unit’.
itemXXWeightNoWeight of XXth item purchased in the format ‘Weight Unit’.
itemsNoNested array of line items.

Refer to to the Purchase Data - Request Fields section for more information on these fields.

info

The shopping cart items must total to the amount specified in the transaction. If they do not, cart items will not be sent to the PayPal Checkout.

Footnotes

  1. Optional for Hosted Integration.
  2. Not required for Hosted Integration.
  3. Direct Integration Only.
  4. Hosted Integration Only.
  5. See note below.
  6. The BN code is the unique button source code provided by PayPal to its partners and added by its partners to the PayPal buttons used by merchants to offer the PayPal Services that are enabled through Partner Product. The button source code provides a means of identifying and tracking referred merchants' payments.