PayPal Checkout


Please note, that this functionality is only available through selected distribution channels in EMEA region.


New PayPal framework adheres to the latest compliance and security standards and offers smoother checkout process with the lightbox.

Hosted Payment Page

Initiate a transaction

You can start by placing a ‘PayPal’ button next to other payment methods you process in your webshop. With clicking on this button, you construct a Sale (or PreAuth) transaction request to our Gateway. This will take your customers to our hosted payment page, where PayPal JS Smart Buttons are rendered. After being redirected to the wallet login page, the cardholders can proceed with payment completion.

Alternatively, you can let your customer select the payment method on the Gateway’s hosted payment method selection page. If you prefer this option, please do not submit a value for the payment method parameter in your payment request.

In addition to mandatory fields, it is also recommended to include PayPal specific fields, as listed below.

Field NameType*Description
checkoutoptionMSet the value for this parameter to combinedpage
customParam_client-meta-idCThe purpose of this parameter is to pass the session information to PayPal to correlate your payment request with the corresponding call submitted to the PayPal Risk Services.

Example: <input type="hidden" name="customParam_client-meta-id" value="123456"/>

String, Limit of 32 characters.
customParam_stc-contentCThis parameter will provide content for the PayPal Set Transaction Context (STC) with sufficient data for the PayPal Risk Services analysis before the transaction is authorized.

Example: <input type="hidden" name="customParam_stc-content" value="{"name":"jan", "id":"1234"}"/>

In addition to 'customParam_stc-content' consider also a need to submit a specific risk tracking id ('customParam_client-meta-id') in your request.
item1 - item999OThe line items are regular Connect integration key-value parameters (URL-encoded) that allow you to send basket information in the following format:

As part of a line item, you can also submit your VAT and shipping cost (as a delivery/shipping fee).

Example: <book>;<The Hobbit>;\<1>;\<4.50>;\<2.92>;\<0.58>;\<1.00>
invoicenumberCRepresents PayPal invoice ID, the field must be populated if available during request submission. This value will be visible in your PayPal seller account while reviewing a transaction.
paymentMethodOOptional parameter, you can submit a value ‘paypal’ directly. If you do not submit this parameter, the Gateway will display a Hosted Payment Page to choose from all the payment methods activated for your store.
snameOShip-to Name
Alphanumeric characters, spaces, and dashes limited to 96
saddr1OShipping City
Limit of 96 characters, including spaces
scountryOCountry of Shipping Address
2 letter country code in the ISO alpha code format (e.g.: DE)
szipOZip or Postal Code
Limit of 24 characters, including spaces
shippingPreferenceOUse this parameter to indicate the way you would like to handle your customer's shipping address.
Available values:
SET_PROVIDED_ADDRESS: Customer can see the address details inside the wallet but cannot change it. The address details are provided as part of the Gateway response.

NO_SHIPPING: Customer cannot see the address details inside the wallet nor can change it. No address details are provided as part of the Gateway response.
txntypeMSupported transaction types:
• 'sale’
• 'preauth’
• ‘void’
• 'postauth’

*(M)=Mandatory (O)=Optional (C)=Conditional

Recurring Payments

If you want to use PayPal’s Reference Transaction feature, please contact PayPal to verify if your PayPal business account meets the PayPal requirements for this feature.

Your account must have set up Data Vault / Hosted Data service and you need to submit the parameter ‘chargetotal’ with a zero value in your preauthorization request. Such transaction request is always used to create a Billing Agreement ID on the PayPal side, returned to you in the field ‘hostedDataId’.

Transaction Response

Response parameterDescription
approval_codeTransaction approval code. Initial character indicates the transaction status.
‘Y’ – Transaction approved
‘N’ – Transaction declined
‘?:waiting PAYPAL’ – Transaction has been initiated but a final result is not yet available
statusTransaction status, e.g. ‘APPROVED’, ‘DECLINED’, ‘FAILED’ or ‘WAITING’
hostedDataIdStores “Billing Agreement ID”
snameShip-to Name
saddr1Shipping Address
scityShipping City
scountryCountry of Shipping Address
szipZip or Postal Code
fail_reasonIndicates why the transaction was declined
ipgTransactionIdIt is mapped to the PayPal Custom. You will be able to see this value in your PayPal seller account while reviewing a transaction
refnumberRepresents the PayPal Transaction ID. The value will be visible in your PayPal seller account while reviewing a transaction

Initiating a Return transaction

To initiate a Return transaction please use the Gateway’s Virtual Terminal or REST API.


Please note, in case you are integrated with PayPal Legacy solution, you are required to migrate to PayPal Checkout solution upon your earliest convenience. Please reach out to your customer service team for assistance.

Want a quick overview?