Skip to content

    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.

    Customer Experience - PayPal

    • Select PayPal.
    Paypal widget 1
    • Redirect to PayPal.
    • Log into PayPal account.
    Paypal widget 2
    • Select bank account and confirm the payment.
    Paypal widget 3

    Payengine Details - PayPal

    General

    NameDetails
    ProductPayPal
    Payment Options (for Customer)Express checkout
    ChannelsECOM
    CurrenciesAUD, BRL, CAD, CZK, DKK, EUR, HKD, HUF, INR, ILS, JPY, MYR, MXN, TWD, NZD, NOK, PHP, PLN, GBP, RUB, SGD, SEK, CHF, THB, USD
    CountriesCountries full list available on: https://www.paypal.com/us/webapps/mpp/country-worldwide
    Technical FlowAsynchronous
    RecurringYes
    ChargebacksYes
    Reusable Payment InstrumentsYes
    B2B ApplicableYes

    Supported Features and Services

    NameDetails
    DebitYes
    PreauthorizationNo
    CaptureYes (full & partial)
    CancelationYes (full & partial)
    RefundsYes (full & partial)
    CreditYes (only in EUR)
    NotificationsYes (webhook and email)
    PayLink IntegrationNo
    Settlement ReportingYes, both original and unified settlement

    Integration Types

    NameDetails
    APIYes
    WidgetYes
    BridgeNo
    Shop PluginYes

    Technical Flow

    paypal-tech-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:

    Specifications - PayPal

    Prerequisites for PayPal authorizing transactions

    PrerequisiteMandatory/Optional (M/O)Create Prerequisite
    CustomerOPOST /customers
    PersonaOPOST /customers//personas
    Billing AddressOPOST /customers//addresses
    Shipping AddressOPOST /customers//addresses

    PayPal input parameters

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

    ParameterMandatory/Optional (M/O)DescriptionExample
    async.successUrlMRedirect URL for successful paymenthttps://docs.payengine.de/RedirectURLforsuccessfulpayment
    async.failureUrlMRedirect URL for unsuccessful paymenthttp://my.shop.com/fail
    async.cancelUrlMRedirect URL when payment is canceledhttp://my.shop.com/cancel
    localeOA language tag consisting of a two-letter language code combined with a two-letter country code according to RFC 1766en-US
    meta.addressOverrideO
    • value is true - No option for the customer to change the order's shipping address on PayPal checkout page. As the default shipping address is applied on the customer PayPal account.
    • value is false - An option for the customer to change the Shipping Address of the order on PayPal checkout page

    When meta.addressOverride is set to false a PATCH request is required.

    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

    Create Capture Request

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

    Create Preauth Response

    {
                          "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

    Create Capture Request

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

    Create Capture Response

    {
                          "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

    Create Cancel Request

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

    Create Cancel Response

    {
                          "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

    Create Debit Request

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

    Create Debit Response

    {
                          "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

    Create PATCH Request

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

    Create PATCH Response

    {
                            "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

    Create Refund Request

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

    Create Refund Response

    {
                          "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

    Create Credit Request

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

    Create Credit Response

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