Attributes

• METHOD TYPEE-wallet
• PAYMENTS
• PAYOUTS
• REFUNDS
• RECURRING

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

• Albania
• Algeria
• Andorra
• Angola
• Anguilla
• Antigua and Barbuda
• Argentina
• Armenia
• Aruba
• Australia
• Austria
• Azerbaijan
• Bahamas
• Bahrain
• Barbados
• Belarus
• Belgium
• Belize
• Benin
• Bermuda
• Bhutan
• Bolivia
• Bosnia-Herzegovina
• Botswana
• Brazil
• Saint Lucia
• British Indian Ocean Territory
• Brunei
• Bulgaria
• Burkina Faso
• Burundi
• Cambodia
• Cameroon
• Canada
• Cape Verde
• Cayman Islands
• Chad
• China
• Colombia
• Comoros
• Congo
• Cook Islands
• Costa Rica
• Cote dIvoire
• Croatia
• Cyprus
• Chile
• Denmark
• Djibouti
• Dominica
• Dominican Republic
• Ecuador
• Egypt
• El Salvador
• Eritrea
• Estonia
• Ethiopia
• Falkland Islands (Malvinas)
• Faroe Islands
• Fiji
• Finland
• France
• French Guiana
• French Polynesia
• Gabon
• Gambia
• Georgia
• Germany
• Gibraltar
• Greece
• Greenland
• Grenada
• Guadeloupe
• Guatemala
• Guinea
• Guinea-Bissau
• Guyana
• Honduras
• Hong Kong
• Hungary
• Iceland
• India
• Czech Republic
• Ireland
• Israel
• Italy
• Jamaica
• Japan
• Jordan
• Kazakhstan
• Kenya
• Kiribati
• Kuwait
• Laos
• Latvia
• Lesotho
• Liechtenstein
• Lithuania
• Luxembourg
• Macedonia
• Madagascar
• Malawi
• Malaysia
• Maldives
• Mali
• Malta
• Marshall Islands
• Martinique
• Mauritania
• Mauritius
• Mayotte
• Mexico
• Micronesia
• Indonesia
• Moldova
• Monaco
• Mongolia
• Montenegro
• Montserrat
• Morocco
• Mozambique
• Namibia
• Nauru
• Nepal
• Netherlands
• Netherlands Antilles
• New Caledonia
• New Zealand
• Nicaragua
• Niger
• Nigeria
• Niue
• Norfolk Island
• Norway
• Oman
• Palau
• Panama
• Papua New Guinea
• Paraguay
• Peru
• Philippines
• Pitcairn
• Poland
• Portugal
• Qatar
• Reunion
• Romania
• Russia
• Rwanda
• Saint Helena
• Saint Kitts and Nevis
• Saint Pierre and Miquelon
• Saint Vincent and Grenadines
• Samoa
• San Marino
• Sao Tome and Principe
• Saudi Arabia
• Saudi Arabia
• Senegal
• Serbia
• Seychelles
• Sierra Leone
• Singapore
• Slovakia
• Slovenia
• Solomon Islands
• Somalia
• South Africa
• South Korea
• Spain
• Sri Lanka
• Suriname
• Svalbard and Jan Mayen Islands
• Swaziland
• Sweden
• Switzerland
• Taiwan
• Tajikistan
• Tanzania, United Republic of
• Thailand
• Togo
• Tonga
• Trinidad and Tobago
• Tunisia
• Turkmenistan
• Turks and Caicos Islands
• Tuvalu
• Uganda
• Ukraine
• United Arab Emirates
• United Kingdom
• United States
• Uruguay
• Vanuatu
• Venezuela
• Vietnam
• Virgin Islands
• Wallis and Futuna
• Yemen
• Zambia
• Zimbabwe

Supported Currencies

• AUD
• BRL
• CAD
• CHF
• CNY
• CZK
• DKK
• EUR
• GBP
• HKD
• HUF
• ILS
• JPY
• MXN
• MYR
• NOK
• NZD
• PHP
• PLN
• RUB
• SEK
• SGD
• THB
• TWD
• USD

Payment (Deposit) Flow

There are two flows where you can use PayPal: regular Sale flow and Auth-Settle flow. The default is Sale.
If you want to use an Auth-Settle flow when integrated through REST API, you  must send transactionType: Auth in the /payment request.
Authorization places a temporary hold on the funds and is valid for 29 days. However, settlement is guaranteed within the first 3 days. After that, the transaction may not be settled (see Appendix).

Press tab to open…

{
  "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"
    }
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "billingAddress":{
    "firstName": "John",
    "lastName": "Smith",
    "country":"US",
    "email":"[email protected]"
  },
  "userDetails":{
    "firstName": "John",
    "lastName": "Smith",
    "country":"US",
    "email":"[email protected]"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

sfc.createPayment({
  sessionToken: "<sessiontoken>",                                   
  paymentOption : {        
    alternativePaymentMethod: {
      paymentMethod: "apmgw_expresscheckout"
  }},                     
  deviceDetails:{
    ipAddress:"<customer's IP address>"
  },
  billingAddress: {
    firstName: "John",
    lastName: "Smith",
    country: "US",
    email:"[email protected]"
  },   
  userDetails: {
    firstName: "John",
    lastName: "Smith",
    country: "US",
    email:"[email protected]"
  },      
}, function(res) {
      console.log(res);
});

Payout (Withdrawal) Flow

Send a /payout request and include the userPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.

After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided in urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

User Experience

Payment

1. PayPal opens a pop-up window for the user to log in to their PayPal account.
   
2. After logging in, the user sees a summary of the payment.
   
3. The user confirms and the payment is performed.

Saved Additional Information

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

"[email protected]&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 to 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 protected]&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&[email protected]&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

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, you must include this submethod = “ReferenceTransaction” parameter. Once the first payment is complete, Nuvei receives a response from PayPal with the Reference ID (associated with the userPaymentOptionId), which Nuvei automatically uses for any future direct/billing transactions. When sending subsequent direct transaction requests, you must include this submethod = “ReferenceTransaction” parameter along with the userPaymentOptionId.

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":"<customer's IP address>"
    },
    "billingAddress":{
        "firstName":"John",
        "lastName":"Smith",
        "email":"[email protected]",
        "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":"<customer's IP address>"
    },
    "billingAddress":{
        "firstName":"John",
        "lastName":"Smith",
        "email":"[email protected]",
        "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 page 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 customers 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.

Testing

• Usernames: [email protected], [email protected]
• Password: 1q2w3e$R

In addition, a merchant can also create a test account on developer.paypal.com using the their PayPal credentials.

Appendix

For detailed information, refer to https://developer.paypal.co.