Payment Method Properties


Available country codes	US
Processing (Presentation) currencies	USD
Settlement currencies	Not applicable. Processing-only. PayPal handles the settlement.
Consumer currencies	USD
Channel member tag	paypalwallet
Scheme name in the settlement file	PayPal Wallet
Minimum transaction amount	None
Maximum transaction amount	For non-KYC users: a weekly spending limit of US $299.99; this limit includes person-to-person payments and payments to authorised merchants. For KYC users: a weekly spending limit of US $7,000 on online/in-store purchases, including person-to-person payments.
Session timeout	73 hours
Refund	Full Partial Multiple partial
Refund Validity	180 days
Chargeback	Yes (between Venmo and merchant)
Integration Type	Asynchronous
Sandbox	Scheme-hosted Test payment methods for use within the PayPal sandbox can be found at the following link.

Transaction Flow

The consumer conducts the checkout process on the merchant's webpage.
The merchant/PSP sends the Transaction request to PPRO.
A Create Order request is sent to PayPal.
A Create Order response is returned alongside the checkout URL.
PPRO returns the Transaction response along with a PPRO HPP URL to the merchant/PSP.
The merchant forwards the PPRO HPP URL to the consumer's browser.
The consumer is redirected to the PPRO HPP URL to select the payment method.
The consumer selects the payment method and gets a PayPal checkout pop-up window.
The consumer approves the checkout.
PPRO sends a Capture Order request upon the consumer approving the checkout.
PPRO receives a Capture Order response.
Upon a successful capture order, PPRO redirects the consumer back to the merchant's webpage and displays the result.
PayPal also sends PPRO a capture status notification.
A notification is sent to the PSP informing them of a 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.

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. For example, `da-DK, he-IL, id-ID, ja-JP, no-NO, pt-BR, ru-RU, sv-SE, th-TH, zh-CN, zh-HK, or zh-TW.`
`specin.fundingsources`	O	string	`^(card\|paylater\|venmo)(,(card\|paylater\|venmo))\*$`	Comma-delimited funding sources to be enabled for Smart Buttons. Valid funding sources: `card / paylater / venmo.` E.g `card,paylater` This takes precedence over the `fundingSources` (if provided) during onboarding. This is a newly added specin for the Smart Buttons flow. This only applies for transactions with `specin.smartbuttons = yes.`
`specin.merchantlogourl`	O	string	`.\*`	Link to image of merchant logo to be displayed on the HPP. This takes precedence over the `merchantLogoUrl` (if provided) during onboarding. This is a newly added specin for the Smart Buttons flow. This only applies for transactions with `specin.smartbuttons = yes.`
`specin.merchantname`	O	string	`.\*`	Merchant Name to be displayed on Smart Buttons HPP. This takes precedence over the `merchantName` (if provided) during onboarding. This is a newly added specin for the Smart Buttons flow. This only applies for transactions with `specin.smartbuttons = yes.`
`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 not provided). If set to `no` , the rest of the shipping parameters are not passed in the transaction call.
`specin.shippingaddrline1`	M (if `shippingreqd` is yes or not provided)	string	`.{0,255}`	The first line of the address of the person to whom to ship the items.
`specin.shippingaddrline2`	O	string	`.{0,255}`	The second line of the address of the person to whom to ship the items
`specin.shippingaddrpostalcde`	M (if `shippingreqd` is yes or not provided)	string	`.{0,60}`	The postal code, which is the 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 name of the person to whom to ship the items.
`specin.shippingadminarea1`	O	string	`.{0,120}`	The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, CA and not California. Value, by country, is: UK. A county. US. A state. Canada. A province. Japan. A prefecture. Switzerland. A kanton.
`specin.shippingadminarea2`	O	string	`.{0,100}`	A city, town, or village. Smaller than shippingadminarea1 The field is conditional for scheme based on country. Otherwise will get Error while making Create Order request: The specified country requires a city (address.admin_area_2)
`specin.smartbuttons`	O	string	`.\*`	Smart Buttons toggle. Allowed values: yes / no. Leave empty if merchant does not want to use smart buttons.
`specin.smartbuttonssandboxbuyercountry`	O	string	Valid country code	Smart Buttons Sandbox Buyer Country. Allows override of the buyer country. Only available in PayPal sandbox.
`transientin.orderitems`	O (if wishing to display per-item data during the PayPal checkout)	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 item price - 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 integer For example: `[{"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). 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.

This payment method supports the dynamic descriptor field (see The dynamic descriptor).

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 authorise 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
&currency=USD
&amount=32000
&merchanttxid=MYp3MF6zHDQm
&login=johndoe
&password=wXBrpVporFVjGO4R
&contractid=JOHNDOETESTCONTRACT
&channel=testchannel
&merchantredirecturl=https%3A%2F%2Fmerchant.com%2Fwork%2Fppro2%2Flanding.php
&notificationurl=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
&specin.smartbuttons=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

Additional Information

Specin parameters relevant to the PayPal Smart Buttons flow

There are 5 new, optional spec-ins added to support the PayPal Smart Buttons flow, they are:

specin.smartbuttons
specin.fundingsources
specin.merchantlogourl
specin.merchantname
specin.smartbuttonssandboxbuyercountry

The specin.smartbuttonssandboxbuyercountry is only applicable in the PayPal sandbox where it simulates the buyer country. Venmo is not available in PayPal's sandbox environment, so even if the specin.smartbuttonssandboxbuyercountry, is set to US the Venmo button will not be displayed. The Venmo button will only appear in a live environment when the consumer is located in the US.

Display of the Smart Payment Buttons

If specin.smartbuttons is set to yes, the consumer will be redirected to a PPRO-hosted payment method selection page where the payment buttons will be dynamically displayed depending on the consumer location.

The funding sources (along with the consumer location) determine which Smart Payment Buttons will appear on the PPRO-hosted payment method selection page. Valid values are card, paylater, venmo. At a minimum, the 'Pay with PayPal' button will show.

The funding sources can be provided to our Support team during merchant onboarding, in which case the respective specin.fundingsources need not be passed into the TRANSACTION call.

If a merchant decides to change the funding sources, or would like to show different funding sources at the transaction level, the new funding sources can be sent in the specin.fundingsources in the TRANSACTION call where the new values will overwrite the configuration during merchant onboarding.

Display of the merchant logo and name on the PPRO HPP

Similar to the above on funding sources, if the merchant's logo and name is provided to our Support team during onboarding, both the logo and name will be displayed on the PPRO HPP if specin.smartbuttons is set to yes.

In the above case, the respective specins, i.e. specin.merchantlogourl and specin.merchantname need not be passed into the TRANSACTION call.

If a merchant would like to show a different logo at a transaction level (e.g. may be a different, festive logo), then the new logo URL can be sent in the specin.merchantlogourl in the TRANSACTION call, and the new URL in the spec-in will overwrite the logo URL supplied during onboarding.