PayEngine - PayPal

Overview - PayPal

PayPal Holdings Inc. is a leading technology platform and digital payments company that enables digital and mobile payments on behalf of consumers and merchants worldwide. PayPal platform is available in more than 200 countries/regions and supports 25 currencies.

PayPal operates a two-sided proprietary global technology platform that links its customers, which consist of both merchants and consumers, around the globe to facilitate the processing of payment transactions, allowing PayPal to connect millions of merchants and consumers worldwide.

Activation - PayPal

To activate PayPal as a payment method and to add it to your PayEngine Merchant Center, you need to complete the onboarding journey.

Please provide our support with the following information from your PayPal business account:

• API username
• API password
• API Signature

The description of how to generate the API Signature can be found here.

Customer Experience - PayPal

• Select PayPal.

• Redirect to PayPal.
• Log into PayPal account.

• Select bank account and confirm the payment.

Payengine Details - PayPal

General

Supported Features and Services

Integration Types

Technical Flow

Webhook notifications

As it is not ensured at the time of the redirect to the shop that the payment was 100% successful, the Payengine waits for the final asynchronous notification before a status is moved from PENDING into SUCCESS or FAILURE.

A merchant should register for the Payengine webhook notifications in order to receive this final status update.

Alternatively a GET request on the order or DEBIT/PREAUTH transaction would also work, but it is not ensured that the final status will be available immediately after the redirect and a merchant might have to query the GET multiple times.

Therefore it is strongly recommended that the asynchronous notifications from the Payengine are used instead.

The PayPal notifications could be subscribed:

• via the payengine API (link to API documentation)
• via the Payengine Merchant Center (link to Merchant Center notifications docu)

Specifications - PayPal

Prerequisites for PayPal authorizing transactions

PayPal input parameters

The following input parameters are required for initiating a PayPal payment via direct API integration.

Executing PATCH request will lead to:

• updating the order with changes in Shipping Address and order amount (if there is such change)
• executing the order with updated values

Samples

Preauth

The Preauth is an authorizing transaction that doesn't directly book the initial amount of the order. It has to be followed by 'Capture' in order funds to be received.

POST /orders/preauth

{
                    "description": "description for operation.",
                    "initialAmount": 1190,
                    "currency": "EUR",

{
                      "createdAt": 1554450801720,
                      "modifiedAt": 1554450801741,
                      "merchantId": "merchant_6rpfjfvaxq",

Successful response of Preauth request will contain:

• Preauth transaction with status PENDING.
• redirectUrl to PayPal account of the customer.

After receiving of notification the status of transaction will be updated either to SUCCESS or FAILURE.

Capture

A Capture transaction can be created for amount not bigger than initial amount of Preauth.

POST/orders/{orderId}/transactions/{transactionId}/capture

{
                    "description": "description for operation.",
                    "initialAmount": 1190,
                    "currency": "EUR",

{
                      "createdAt": 1554468760457,
                      "modifiedAt": 1554468760497,
                      "type": "CAPTURE",

Cancel

Any pre-authorized order can still be cancelled as long as the order has not been captured.

A Cancel transaction can be created for amount not bigger than initial amount of Preauth transaction.

POST/orders/{orderId}/transactions/{transactionId}/cancel

{
                    "description": "description for transaction.",
                    "initialAmount": 1190,
                    "currency": "EUR",

{
                      "createdAt": 1554476477120,
                      "modifiedAt": 1554476479260,
                      "type": "CANCEL",

Debit

Debit is an authorizing transaction that directly books the full amount of the order.

If Debit transaction is preferred instead of Preauth, the goods from the order will be considered as shipped to the end customer.

POST/orders/debit

{
                    "product": "paypal",
                    "terms": 1468590412476,
                    "privacy": 1468590412476,

{
                      "createdAt": 1570710976957,
                      "modifiedAt": 1570710977017,
                      "merchantId": "Merchant-9f44a531-cde3-4cf8-898c-7af9af48b1aa",

Successful Debit request will result in creating of Debit transaction with status PENDING.

PATCH

Perform PATCH when meta.addressOverride is set to false.

PATCH/orders/orderId

{
                      "initialAmount": 4000,
                      "shippingAddress": "address_1mudpcot9f",
                      "executeOrder": true

{
                        "createdAt": 1554731928695,
                        "modifiedAt": 1554732809511,
                        "merchantId": "merchant_6rpfjfvaxq",

Successful PATCH request will result in changing of status of authorizing transaction from IN_PROGRESS to SUCCESS.

Refund

A Refund transaction can be created on a request of the end customer when there is an existing successful Debit or Capture transaction for the order.

POST/orders/{orderId}/transactions/{transactionId}/refund

{
                    "description": "description for transaction.",
                    "initialAmount": 200,
                    "currency": "EUR",

{
                      "createdAt": 1554736206270,
                      "modifiedAt": 1554736209852,
                      "type": "REFUND",

PayPal Credit Transaction

PayPal Credit transaction is available only for those merchants that have explicit permission from PayPal to execute such type of transactions. Successful Credit transaction will result in transferring funds from merchant's account to an end-customer's account. Credit transaction is addressable via public API and it's a special type of Authorizing transaction without any subsequent referencing transaction only available in EUR currency. Examples for Create Credit request and response can be found below.

POST/orders/credit

{
                      "product" : "paypal",
                      "terms": 1468590412476,
                      "privacy": 1468590412476,

{
                        "createdAt": 1554815333929,
                        "modifiedAt": 1554815334022,
                        "merchantId": "merchant_mbm2ed3lng",