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 Name | Mandatory? | Description |
|---|---|---|
| paymentMethod | Yes[1] | Must be the value ‘paypal’ in lower case only. |
| checkoutRedirectURL | Yes[2] | URL on Merchant’s server to return to when the PayPal Checkout is closed. |
| checkoutOptions | No[3] | Record containing options used to customise the PayPal Checkout. Refer here. |
| payPalCheckoutOptions | No[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 Name | Mandatory? | Description |
|---|---|---|
| checkoutRef | Yes | Unique reference return in the initial response. |
| checkoutResponse | Yes | Record containing the GET and or POST data received by the checkoutRedirectURL page. |
| checkoutOnly | No | Pass 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 Name | Description |
|---|---|
| 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. |
| maxAmount | The expected maximum total amount of the order, including shipping and taxes. PayPal refer to this field as MAXAMT. |
| reqBillingAddress | Determines 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 |
| addrOverride | Determines whether the PayPal Checkout displays the shipping address sent using the Possible values are: 0 – PayPal should not display the address. 1 – PayPal should display the address. |
| localeCode | 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. |
| allowNote | Enables the buyer to enter a note to the merchant on the PayPal page during Checkout. The note is returned in the checkoutDetails response field. |
| pageStyle | Name 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. |
| payflowColor | The HTML hex colour code for the PayPal Checkout’s background colour. By default, the colour is white (FFFFFF). |
| cardBorderColor | The 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. |
| 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 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. |
| logoImg | 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. |
| 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 |
| brandName | A label that overrides the business name in the PayPal account on the PayPal Checkout. |
| customerServiceNumber | Merchant 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. |
| noteToBuyer | A 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. |
| allowedPaymentMethod | The 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 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. |
| noteText | Note 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. |
| locationID | Location ID specified by the merchant for BOPIS (Buy Online Pick-up In Store) or PUDO (Pick-Up Drop-Off) transactions. |
| sellerPayPalAccountID | 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. |
| invNum | Merchant’s invoice or tracking number. |
| custom | Custom field for your own use. |
| buyerID | 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. |
| buyerUsername | The username of the user at the marketplaces site. |
| buyerRegistrationDate | Date 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 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. |
| billingAgreementDescription | 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". |
| 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. |
| riskSessionCorrelationID | The ID of the risk session for correlation purposes when doing a recurring/reference transaction. |
| merchantSessionID | The 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 Name | Mandatory? | Description |
|---|---|---|
| shippingAmount | No | Shipping costs. |
| shippingDiscountAmount | No | Discount applied to shipping costs. |
| handlingAmount | No | Handling costs. |
| insuranceAmount | No | Insurance costs. |
| itemXXDescription | No | Description of XXth item purchased. |
| itemXXQuantity | No | Quantity of XXth item purchased. |
| itemXXAmount | No | Gross amount for XXth item purchased. |
| itemXXTaxAmount | No | Tax amount for XXth item purchased. |
| itemXXProductCode | No | Product code for XXth item purchased. |
| itemXXProductURL | No | Shopping cart URL for XXth item purchased. |
| itemXXSize | No | Size of XXth item purchased in the format ‘LengthxWidthxHeight Unit’. |
| itemXXWeight | No | Weight of XXth item purchased in the format ‘Weight Unit’. |
| items | No | Nested array of line items. |
Refer to to the Purchase Data - Request Fields section for more information on these fields.
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.