PayPal: New Integration
Please be advised that PayPal New Integration is exclusive to the Hosted Payment Page Interface.
New PayPal framework adheres to the latest compliance and security standards and offers smoother checkout process with the lightbox.
In addition to mandatory fields, it is also recommended to include PayPal specific fields, as listed below.
| Field Name | Type* | Description |
|---|---|---|
checkoutoption | M | Set the value for this parameter to combinedpage |
client-meta-id | C | The 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. Possible values: • Magnes • FraudNet For more information, you can review the following: Magnes FraudNet |
full_bypass | O | When using your own input form set this parameter to false. |
item1 - item999 | O | The line items are regular Connect integration key-value parameters (URL-encoded) that allow you to send basket information in the following format: id;description;quantity;item_total_price;sub_total;vat_tax;shipping;local_tax;category;detailed_category As part of a line item, you can also submit your VAT and shipping cost (as a delivery/shipping fee). Example: ;;<1>;<4.50>;<2.92>;<0.58>;<1.00>;<0>;; |
invoicenumber | C | Represents 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 |
paymentMethod | O | Optional 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. |
sname | O | Ship-to Name Alphanumeric characters, spaces, and dashes limited to 96 |
saddr1 | O | Shipping City Limit of 96 characters, including spaces |
scountry | O | Country of Shipping Address 2 letter country code in the ISO alpha code format (e.g.: DE) |
szip | O | Zip or Postal Code Limit of 24 characters, including spaces |
shippingPreference | O | Use 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.If the address data is missing or incomplete data in the transaction request, no address data will be passed to PayPal and your transaction will be declined with an error “invalid country name for shipping”. |
txntype | M | Supported 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.
Initiating a Return Transaction
To initiate a Return transaction using the Gateway’s Virtual Terminal or REST API.
Transaction Response
| Response parameter | Description |
|---|---|
approval_code | Transaction 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 |
status | Transaction status, e.g.‘APPROVED’, ‘DECLINED’, ‘FAILED’ or ‘WAITING’ |
sname | Ship-to Name |
saddr1 | Shipping Address |
scity | Shipping City |
scountry | Country of Shipping Address |
szip | Zip or Postal Code |
fail_reason | Indicates why the transaction was declined |
ipgTransactionId | It is mapped to the PayPal Custom. You will be able to see this value in your PayPal seller account while reviewing a transaction |
refnumber | Represents the PayPal Transaction ID. The value will be visible in your PayPal seller account while reviewing a transaction |
Note: In case you are integrated with PayPal legacy solution, you can continue to use your existing PayPal business account. If you wish to migrate to the new PayPal solution, please reach out to your customer service team.
Updated 16 days ago
