PayPal – Nuvei Documentation

On this page:

Introduction
Supported Countries
Supported Currencies
Implementation Details
User Experience
Configuration Requirements
Gaming Restrictions
Account Validations
In-Context Flow
Billing Agreements and Reference Transactions
Error Handling
Quick Registration

Attributes

METHOD TYPEE-wallet
DEPOSITS
WITHDRAWS
REFUNDS

Introduction

PayPal is an alternative payments system that supports online money transfers for both businesses and individuals. It is most popular in western markets such as the U.S.A, Germany, and the U.K. It is an instant way to wire money. As an e-wallet, PayPal is globally recognized and accepted (except for in sanctioned countries and entities).

PayPal requires creating an account, which is linked to a debit or credit card.

PayPal supports refunds, as well as recurring payments using a submethod.

Supported Countries

Angola
Anguilla
Armenia
Aruba
Azerbaijan
Belarus
Benin
Bhutan
Botswana
British Indian Ocean Territory
Brunei
Burkina Faso
Burundi
Cambodia
Cameroon
Cape Verde
Chad
Comoros
Congo
Cook Islands
Cote dIvoire
Djibouti
Egypt
Eritrea
Ethiopia
Falkland Islands (Malvinas)
Gabon
Gambia
Georgia
Guinea
Guinea-Bissau
Guyana
Kazakhstan
Kenya
Kiribati
Laos
Lesotho
Macedonia
Madagascar
Malawi
Maldives
Mali
Marshall Islands
Mauritania
Mauritius
Mayotte
Monaco
Mongolia
Montenegro
Montserrat
Mozambique
Namibia
Nauru
Nepal
Nicaragua
Niger
Nigeria
Niue
Norfolk Island
Papua New Guinea
Paraguay
Pitcairn
Reunion
Rwanda
Saint Helena
Saint Pierre and Miquelon
Saint Vincent and Grenadines
Samoa
Sao Tome and Principe
Saudi Arabia
Senegal
Serbia
Seychelles
Sierra Leone
Solomon Islands
Somalia
South Africa
Sri Lanka
Suriname
Svalbard and Jan Mayen Islands
Swaziland
Tajikistan
Tanzania, United Republic of
Togo
Tonga
Tunisia
Turkmenistan
Tuvalu
Uganda
Ukraine
Vanuatu
Virgin Islands
Wallis and Futuna
Yemen
Zambia
Zimbabwe
Moldova
Bolivia
Netherlands Antilles
Micronesia

Supported Currencies

Implementation Details

Click tab to open…

for REST API
for Web SDK
for Payment Page

{
    "sessionToken":"<sessionToken from getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientRequestId":"<unique request ID in merchant system>",
    "amount":"200",
    "currency":"USD",
    "userTokenId":"<unique customer identifier in merchant system>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_expresscheckout"
        }
    },
    "billingAddress":{
        "country":"US",
        "email":"john.smith@email.com"
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    },
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}

sfc.createPayment({
    "sessionToken": sessionData.sessionToken,                                   
    "paymentOption" : {        
      "alternativePaymentMethod": {
        "paymentMethod": "apmgw_expresscheckout"
        }},
               "billingAddress": {
        "country": "US",
        "email":"john.smith@email.com"
        }                        
                 
    }, function(res) {
      console.log(res);
    })

https://ppp-test.safecharge.com/ppp/purchase.do?merchant_id=5833787323214383259&merchant_site_id=218548&user_token=auto&user_token_id=UserID_8343021444&userid=UserID_8343021444&item_open_amount_1=false&item_min_amount_1=1&item_max_amount_1=100&item_name_1=Cashier%20Test%20product&item_amount_1=10&item_quantity_1=1&item_discount_1=0&numberofitems=1&total_tax=0&discount=0&total_amount=10.00&currency=GBP&version=4.0.0&encoding=UTF-8&first_name=test&last_name=test&address1=test&city=test&zip=123456&country=GB&phone1=123456&email=0939122464%40gmail.com&payment_method=apmgw_expresscheckout&success_url=https%3A%2F%2Fhome.stefanovweb.eu%2Fresponse.php&pending_url=https%3A%2F%2Fhome.stefanovweb.eu%2Fresponse.php&error_url=https%3A%2F%2Fhome.stefanovweb.eu%2Fresponse.php&notify_url=https%3A%2F%2Fhome.stefanovweb.eu%2Fdmn.php%3Fdmnorigin%3DCheckSumCalculator&payment_method_mode=filter&time_stamp=2021-12-21.15%3A58%3A29&checksum=e6115fd7c0107b54e6ba4b245beb855e2498a34e9832900960d2edc785d263b7&

for REST API

{
    "sessionToken":"<sessionToken from getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientRequestId":"<unique request ID in merchant system>",
    "amount":"200",
    "currency":"USD",
    "userTokenId":"<unique customer identifier in merchant system>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_expresscheckout"
        }
    },
    "billingAddress":{
        "country":"US",
        "email":"john.smith@email.com"
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    },
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}

for Web SDK

sfc.createPayment({
    "sessionToken": sessionData.sessionToken,                                   
    "paymentOption" : {        
      "alternativePaymentMethod": {
        "paymentMethod": "apmgw_expresscheckout"
        }},
               "billingAddress": {
        "country": "US",
        "email":"john.smith@email.com"
        }                        
                 
    }, function(res) {
      console.log(res);
    })

for Payment Page

User Experience

Deposit

The user selects PayPal on the Nuvei Payment Page or Cashier.
The user enters the amount to pay/deposit.
PayPal opens a pop-up window for the user to log in to their PayPal account.
After login, the user sees a summary of the payment.
The user confirms and the payment is performed.

Withdrawal

The user enters the amount in the cashier to withdraw.
The user confirms.
A withdrawal request is created.
The withdrawal is processed by the merchant from the back office.

Saved Additional Information

Nuvei saves in “Provider additional information” all the user information that Nuvei gets back from PayPal:

“EMAIL=SCTest1@gmail.com&PAYERID=ZWSUDQJKBYJEL&PAYERSTATUS=verified&SALUTATION=&FIRSTNAME=Nikkie Anne&LASTNAME=Reymoundo Pejmoynto&BILLINGNAME=&STREET=&CITY=&STATE=&ZIP=&COUNTRY=&COUNTRYNAME=&ADDRESSID=&ADDRESSSTATUS=Confirmed”

Configuration Requirements

PayPal payouts require an Instant Payment Notification (IPN) in order to be received and updated on Nuvei’s gateway. This requires the merchant to apply the following IPN URL on their PayPal merchant account in the PayPal merchant area:

https://apm.safecharge.com/paypal/paypalnotification.ashx

For more information, please check the explanation on the PayPal page: https://developer.paypal.com/docs/classic/products/instant-payment-notification/

Required details for PayPal MID setup:

Paypal Merchant Password
Paypal Merchant Username
Paypal Merchant Signature

Gaming Restrictions

The gaming restriction means that a user cannot use more than one PayPal account per website, and other users cannot share the same account. (In other words, one unique PayPal account per user per site.)

Account Validations

After a user logs in into their PayPal account, Nuvei requests from PayPal the user information by imitating the “GetExpressCheckoutDetails API Operation”.

PayPal responds to this call with the user information they have on their system.

Nuvei can use this data to perform an account validation check on our risk system to compare user data such as first name, last name, etc.

Response Example

TOKEN=EC710956894Y3076712&BILLINGAGREEMENTACCEPTEDSTATUS=0&CHECKOUTSTATUS=PaymentActionNotInitiated&TIMESTAMP=2019-05-19T21:02:13Z&CORRELATIONID=67ff4f2ef129&ACK=Success&VERSION=63.0&BUILD=52747458&EMAIL=kevinmarkmillard@yahoo.co.uk&PAYERID=GMVUCTGWCJW2J&PAYERSTATUS=verified&FIRSTNAME=Kevin&LASTNAME=Millard&COUNTRYCODE=GB&BILLINGNAME=Kevin Millard&STREET=48 ffordd-llanbad&STREET2=Gilfach-Goch&CITY=porth&STATE=Rhondda Cynon Taff&ZIP=Cf398fl&COUNTRY=GB&COUNTRYNAME=United Kingdom&ADDRESSID=PayPal&ADDRESSSTATUS=Confirmed&CURRENCYCODE=GBP&AMT=20.00&ITEMAMT=20.00&SHIPPINGAMT=0.00&HANDLINGAMT=0.00&TAXAMT=0.00&CUSTOM=7B7FE23E66BA42F395233E170B0CBC24&NOTIFYURL=https://apm.safecharge.com/paypal/paypalnotification.ashx&INSURANCEAMT=0.00&SHIPDISCAMT=0.00&INSURANCEOPTIONOFFERED=false&L_NAME0=ptadapter&L_QTY0=1&L_TAXAMT0=0.00&L_AMT0=20.00&PAYMENTREQUEST_0_CURRENCYCODE=GBP&PAYMENTREQUEST_0_AMT=20.00&PAYMENTREQUEST_0_ITEMAMT=20.00&PAYMENTREQUEST_0_SHIPPINGAMT=0.00&PAYMENTREQUEST_0_HANDLINGAMT=0.00&PAYMENTREQUEST_0_TAXAMT=0.00&PAYMENTREQUEST_0_CUSTOM=7B7FE23E66BA42F395233E170B0CBC24&PAYMENTREQUEST_0_NOTIFYURL=https://apm.safecharge.com/paypal/paypalnotification.ashx&PAYMENTREQUEST_0_INSURANCEAMT=0.00&PAYMENTREQUEST_0_SHIPDISCAMT=0.00&PAYMENTREQUEST_0_SELLERPAYPALACCOUNTID=paypal@mansion.com&PAYMENTREQUEST_0_INSURANCEOPTIONOFFERED=false&L_PAYMENTREQUEST_0_NAME0=ptadapter&L_PAYMENTREQUEST_0_QTY0=1&L_PAYMENTREQUEST_0_TAXAMT0=0.00&L_PAYMENTREQUEST_0_AMT0=20.00

In-Context Flow

The PayPal Express Checkout with the In-Context flow gives customers a simplified checkout experience, which keeps them local to the merchant’s website throughout the payment authorization process.

PayPal Redirect In-Context Message

Billing Agreements and Reference Transactions

To work with “Billing Agreements and Reference Transactions”, there are some risk requirements that merchants need to address directly with PayPal.

Billing Agreements are established when a buyer agrees to allow a merchant to use their PayPal account as a funding source for transactions.

This allows two types of deposit flows:

Direct deposit – After the first deposit, when the user is redirected to PayPal and signs the billing agreement, all future deposits of the user are direct deposits without any redirect to PayPal.
Rebilling – Signing the billing agreement allows the merchant to make future charges according to a billing plan. The first transaction can be a sign and pay deposit, or only a sign deposit (when sending amount=0).

Technical Requirements

To initiate the first deposit for signing the billing agreements, merchants need to send “submethod” = “ReferenceTransaction”. In the response from PayPal, Nuvei gets the referenceID that Nuvei used for the future direct/billing transactions. The first transaction can be deposit + agreement signing (when amount>0), or only agreement signing (when amount=0).

First Deposit Request Example

{
    "clientRequestId":"20211203355101",
    "merchantId":"321231666932625700",
    "merchantSiteId":"224668",
    "timeStamp":"20211201155101",
    "checksum":"10F14BF35DC1E16B5A0402D9FD3C008DB47ABA3392B117239AFB08425CA8CCE4",
    "sessionToken":"b0858285-3c2d-4812-b9f4-e6065153246d",
    "userTokenId":"testJohn",
    "clientUniqueId":"Sunisshining444",
    "transactionType":"Sale",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_expresscheckout"
        },
        "userPaymentOptionId": "null",
        "subMethod":{
            "subMethod":"ReferenceTransaction"
        }
    },
    "currency":"GBP",
    "amount":"10",
    "deviceDetails":{
        "ipAddress":"93.146.254.172"
    },
    "billingAddress":{
        "firstName":"John",
        "lastName":"Smith",
        "email":"john.smith@email.com",
        "phone":"123456789",
        "address":"39 Rotschild st",
        "city":"London",
        "country":"GB"
    },
    "urlDetails":{
        "notificationUrl":"https://cashier.com.e/paymentservice/safecharge/deposit-notification"
    }
}

First Deposit Response Example

{
    "orderId":"301028008",
    "userTokenId":"testJohn",
    "paymentOption":{
        "redirectUrl":"https://www.sandbox.paypal.com/ca/cgi-bin/merchantpaymentweb?cmd=_express-checkout&token=EC-1YT80578R0459232J",
        "userPaymentOptionId":"71693528",
        "card":{
            
        }
    },
    "transactionStatus":"REDIRECT",
    "sessionToken":"b0858285-3c2d-4812-b9f4-e6065153246d",
    "clientUniqueId":"Sunisshining444",
    "internalRequestId":342526048,
    "status":"SUCCESS",
    "errCode":0,
    "reason":"",
    "merchantId":"321231666932625700",
    "merchantSiteId":"224668",
    "version":"1.0",
    "clientRequestId":"20211203355101"
}

Second Deposit Request Example

{
    "clientRequestId":"20211201155101",
    "merchantId":"321231666932625700",
    "merchantSiteId":"224668",
    "timeStamp":"20211201155101",
    "checksum":"AFC3B55C7A6EC562043599C8C8CAB20AFE97FA282085B7D95C5282877F73853F",
    "sessionToken":"e5d01bad-8c0c-44d5-8821-a0ea78f43153",
    "userTokenId":"testJohn",
    "clientUniqueId":"Sunisshining445",
    "transactionType":"Sale",
    "paymentOption":{
        "userPaymentOptionId":"71693528",
        "subMethod":{
            "subMethod":"ReferenceTransaction"
        }
    },
    "currency":"GBP",
    "amount":"10",
    "deviceDetails":{
        "ipAddress":"93.146.254.172"
    },
    "billingAddress":{
        "firstName":"John",
        "lastName":"Smith",
        "email":"john.smith@email.com",
        "phone":"123456789",
        "address":"39 Rotschild st",
        "city":"London",
        "country":"GB"
    },
    "urlDetails":{
        "notificationUrl":"https://cashier.com.e/paymentservice/safecharge/deposit-notification"
    }
}

Second Deposit Response Example

{
    "orderId":"301031778",
    "userTokenId":"testJohn",
    "paymentOption":{
        "userPaymentOptionId":"71693528",
        "card":{
            
        }
    },
    "transactionStatus":"APPROVED",
    "transactionId":"711000000003645919",
    "sessionToken":"e5d01bad-8c0c-44d5-8821-a0ea78f43153",
    "clientUniqueId":"Sunisshining445",
    "internalRequestId":342540878,
    "status":"SUCCESS",
    "errCode":0,
    "reason":"",
    "merchantId":"321231666932625700",
    "merchantSiteId":"224668",
    "version":"1.0",
    "clientRequestId":"20211201155101"
}

Error Handling

The Recovery feature in PayPal after receiving Error 10486 is not relevant when using PayPal’s billing agreement:

On the redirect flow, if the Error 10486 response from PayPal is received, Nuvei redirects the customer back to PayPal instead of back to the cashier in order to fix the funding source.
On the direct flow (billing agreement), there is no redirect so we cannot redirect the user to PayPal to fix the funding source and therefore we decline it.

Quick Registration

PayPal’s Quick Registration allows costumers that do not have an account on the merchant site to use their PayPal account details to register them on the site by making a purchase.