PayPal
Integrate PayPal and allow merchants to accept payments via one of the largest payment methods in the world.
PPRO offers a 'Pay with PayPal' flow integration, where consumers can choose to pay at the merchant's payment selection page with the shipping address provided to PayPal. After logging in to their PayPal account, consumers can choose to pay via their PayPal wallet balance, or credit/debit cards or Pay Later products (e.g. PayPal credit, Pay in 3, Pay in 4, if available. They can also add bank accounts to their PayPal account.
Payment Method Properties
| Available country codes | Global |
| Processing (Presentation) currencies | AUD, BRL, CAD, CZK, DKK, EUR, HKD, HUF, JPY, MYR, MXN, NOK, NZD, PHP, PLN, GBP, SGD, SEK, CHF, TWD, THB, USD Special requirements apply for some currencies. See the Note below for more details. |
| Settlement currencies | Not applicable. Processing-only. PayPal handles the settlement. |
| Consumer currencies | Global |
| Channel member tag | paypalwallet |
| Scheme name in the settlement file | PayPal Wallet |
| Minimum transaction amount | Wallet balance, credit/debit cards, or bank accounts: No limit For HUF, TWD - cents not allowed. Set the cent amount to 00. Buy now, pay later: Pay in 4 (US): USD 30 (which eligible US consumers can use to pay in four, interest-free payments) Pay Monthly (US): USD 199 (which eligible US consumers can use to pay in 3, 6,12 or 24 monthly installments) Pay in 3 (UK): GBP 30 (which eligible UK consumers can use to pay in three, interest-free payments) PayPal Credit (UK): GBP 99 (which eligible UK consumers can use to pay interest free within the first 4 months) Pay in 4 (FR): EUR 30 (which eligible French consumers can use to pay in four, interest-free payments) Pay in 4 (AU): AUD 30 (which eligible Australian consumers can use to pay in four, interest-free payments) Pay Monthly (DE): EUR 99 (which eligible German consumers can use to pay in 3, 6,12 or 24 monthly installments) Pay in 30 (DE): EUR 1 (which eligible German consumers can use to pay within 30 days of purchase) Pay in 3 (ES): EUR 30 (which eligible Spanish consumers can use to pay in three, interest-free payments) Pay in 3 (IT): EUR 30 (which eligible Italian consumers can use to pay in three, interest-free payments) For more information visit Pay Later offers |
| Maximum transaction amount | Wallet balance, credit/debit cards, or bank accounts: Maximum subject to wallet balance, card limits or bank account balance (whichever is applicable). Buy now, pay later: Pay in 4 (US): USD 1,500 (which eligible US consumers can use to pay in four, interest-free payments) Pay Monthly (US): 10,000 (which eligible US consumers can use to pay in 3, 6,12 or 24 monthly installments) Pay in 3 (UK): GBP 2,000 (which eligible UK consumers can use to pay in three, interest-free payments) PayPal Credit (UK): none (which eligible UK consumers can use to pay interest free within the first 4 months) Pay in 4 (FR): EUR 2,000 (which consumers from France can use to pay in four, interest-free payments) Pay in 4 (AU): AUD 2000 (which eligible Australian consumers can use to pay in four, interest-free payments) Pay Monthly (DE): EUR 5000 (which eligible German consumers can use to pay in 3, 6,12 or 24 monthly installments) Pay in 30 (DE): EUR 1000 (which eligible German consumers can use to pay within 30 days of purchase) Pay in 3 (ES): EUR 2000 (which eligible Spanish consumers can use to pay in three, interest-free payments) Pay in 3 (IT): EUR 2000 (which eligible Italian consumers can use to pay in three, interest-free payments) For more information visit Pay Later offers |
| Session timeout | 73 hours |
| Refund | Full, partial and multiple partial refunds are all available. |
| Refund Validity | 180 days |
| Chargeback | Yes (between PayPal and merchant) |
| Integration Type | Asynchronous |
| Sandbox | Scheme-hosted Test payment methods for use within the PayPal sandbox can be found at the following link. |
Note
MYR: the merchant must be in-country.
HUF, TWD: PayPal does not support decimal amounts for these currencies. Amounts must be in multiples of 100.
BRL: If the fund receiver is not from Brazil, PayPal converts funds into the primary holding currency of the account with the applicable currency conversion rate. The currency conversion rate includes PayPal's applicable spread or fee.
Transaction Flow
- The consumer checks out on the merchant's webpage.
- The merchant/PSP sends PPRO the transaction request.
- PPRO sends PayPal a create order request.
- PayPal returns a create order response along with the checkout URL.
- PPRO returns the transaction response along with a checkout redirect URL to the merchant/PSP.
- The merchant forwards the redirect URL to the consumer's browser.
- The consumer is redirected to the PayPal-hosted payment page to authenticate and approve the checkout.
- The consumer approves the checkout.
- PPRO sends a capture order request.
- PPRO receives the capture order response.
- After a successful capture order, PPRO redirects the consumer back to the merchant’s webpage and displays the payment result.
- PayPal sends PPRO a capture status notification.
- PPRO notifies the PSP of the status update.
- If the capture status is not known, PPRO sends a query order request to PayPal to query the transaction status.
- PayPal returns the query order result.
PayPal Integration
Specific input parameters for the TRANSACTION call
| Field Name | M/O/C | Type | Regex | Description |
|---|---|---|---|---|
specin.locale | O | String | ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$ | The BCP 47-formatted locale of pages that the PayPal payment experience shows. PayPal supports a five-character code. Example: jp-JP, no-NO |
specin.shippingaddrline1 | M (if shippingreqd is yes or not provided) | String | .{0,255} | The first line of the consumer's address |
specin.shippingaddrline2 | O (if shippingreqd is yes or not provided) | String | .{0,255} | The second line of the consumer's address |
specin.shippingaddrline2 | M (if shippingreqd is yes or not provided) | String | .{0,60} | The consumer's postal code (zip code or equivalent) |
specin.shippingcntrycde | M (if shippingreqd is yes or not provided) | String | Valid country code | The two-character ISO 3166-1 code that identifies the country or region |
specin.shippingname | M (if shippingreqd is yes or not provided) | String | .{0,255} | The consumer's name |
specin.shippingreqd | O | String | ^[yY][eE][sS]|[nN][oO]$ | Specifies whether the shipping address is required. Used in the case of digital goods, when no shipping is required. Case-insensitive Possible values: yes/no Default value: yes If set to no , the rest of the shipping parameters are not passed in the transaction call. |
specin.shippingadminarea1 | O | String | .{0,120} | The highest level subdivision in a country. Usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. Example: CA (and not California)Sample subdivisions: • UK: a county • US: a state • Canada: a province • Japan: a prefecture • Switzerland: a canton |
specin.shippingadminarea2 | O | String | .{0,100} | A city, town, or village. Smaller than shippingadminarea1 |
transientin.orderitems | O | String | .* | A list of items in the customer’s cart that is being purchased. Format: A serialised JSON array containing item objects Each item object contains the following fields: name - Name of the itemprice - Price of the item. (Note: In minor units) Sum of item amounts, each multiplied by its quantity (next field) must equal to the amount on the order.quantity - Quantity of item bought, in integerExample: [{"name":"table","price":"2000","quantity":2},{"name":"Laptop 2.0","price":"3000","quantity":2}]In the above example, there are two items in the basket as shown below. Item 1 Name: table Unit price: 2000 Quantity: 2 Item 2 Name: Laptop 2.0 Unit price: 3000 Quantity: 2 Since the total cost of all items is 10000 (Note: In minor units), the transaction amount must be 10000 (Note: In minor units eg cents). Please ensure that the total cost of all items equals to the transaction amount. |
For standard input parameters, see Input parameters for the TRANSACTION call.
Specific output parameters for the TRANSACTION call
| Field Name | Type | Description |
|---|---|---|
| SPECOUT.PAYEREMAIL | String | The consumer's email |
| SPECOUT.PAYERGIVENNAME | String | The consumer's given name |
| SPECOUT.PAYERID | String | The consumer's PayPal ID |
| SPECOUT.PAYERSURNAME | String | The consumer's surname |
| SPECOUT.SELLERACCOUNTID | String | The PayPal-generated merchant ID |
| SPECOUT.SELLERPROTECTIONSTATUS | String | The seller protection status Possible values: • ELIGIBLE: The PayPal balance remains intact if the consumer claims that they did not receive an item or the account holder claims that they did not authorize the payment• PARTIALLY_ELIGIBLE: The PayPal balance remains intact if the consumer claims that they did not receive an item• NOT_ELIGIBLE: This transaction is not eligible for seller protection |
For standard output parameters, see Output parameters for the TRANSACTION call.
TRANSACTION call input
tag=paypalwallet
&txtype=TRANSACTION
&countrycode=US
¤cy=USD
&amount=32000
&merchanttxid=MYp3MF6zHDQm
&login=johndoe
&password=wXBrpVporFVjGO4R
&contractid=JOHNDOETESTCONTRACT
&channel=testchannel
&merchantredirecturl=https%3A%2F%2Fmerchant.com%2Fwork%2Fppro2%2Flanding.php
¬ificationurl=https%3A%2F%2Fmerchant.com%2Fwork%2Fppro2%2Fnotification.php
&accountholdername=Tester+Doe
&specin.locale=en-US
&specin.shippingaddrline1=Marina%20Bay%20Sands
&specin.shippingaddrline2=Level%2056
&specin.shippingaddrpostalcde=123456
&specin.shippingadminarea1=CA
&specin.shippingadminarea2=Los%20Angeles
&specin.shippingcntrycde=US
&specin.shippingname=Michael
&specin.shippingreqd=yes
&returnmode=urlencodeext
TRANSACTION call output
REQUESTSTATUS:SUCCEEDED
&STATUS:SUCCEEDED
&TXID:487447256
&ERRMSG:
&CHANNEL:testchannel
&TAG:paypalwallet
&PAYMENTGUARANTEE:NONE
&REDIRECTSECRET:Dp6eF8m1BCBwyoojxyl7MYzkI3MeTVfr
&SPECOUT.PAYEREMAIL:[email protected]
&SPECOUT.PAYERGIVENNAME:John
&SPECOUT.PAYERID:J4P9XUXBEQJPN
&SPECOUT.PAYERSURNAME:Doe
&SPECOUT.SELLERACCOUNTID:T5NC54ZR3J&X6
&SPECOUT.SELLERPROTECTIONSTATUS:ELIGIBLE
Configuring a PayPal Sandbox Account
- Navigate to developer.paypal.com
- Create an account if you do not already have one
- Click the Accounts page under the SANDBOX group from the navigation tree on the left of the page
- Select the “personal” account to view your sandbox account details and credentials for checking out in the PayPal sandbox environment; you can also create additional sandbox accounts if desired
- You can also view the sandbox accounts by logging on to sandbox.paypal.com
Branding guidelines
For branding information, see the PayPal branding guidelines.
Updated 8 months ago