Version 2
Specific information about the payment method PayPal.
PayPal is a safe, easy way to pay and get paid online. It is considered a classical wallet, which means, that the owner of the wallet has one or more different payment instruments such as Mastercard, Visa or Amex that he can use for payment. When executing payments via PayPal, the customer's selected payment instrument remains invisible to the outer world. It is all handled by PayPal internally, so that the payment method from the outside is simply treated as "PayPal".
In case you plan to offer PayPal as payment method, make sure to have a merchant contract with PayPal.
The current page describes how merchants can use the PayPal payment method by integrating the Riverty Pre-Built UI into their shops and use the Payments API to trigger all necessary operations.
Customer Experience
Riverty Payments API offers a PayPal Standard Integration for shops.
After collecting the cart items, the Merchant displays the Riverty Pre-Built UI which contains the PayPal payment method and potentially other payment methods alongside.
When clicking the PayPal button, the PayPal popup is loaded and the customer can accept the order.
After clicking the Continue / Pay button, the PayPal popup will close and the WidgetAPI will collect the PayPal OrderId and return to the shop. Further on, the Merchant backend will proceed with the final Authorization of the order.
Look and feel
The Look and Feel of the Button Styles and additional Messages as well as the for the Shopper available Payment options are configurable with the support of the Operations Team. The following settings can be configured on our backend system in order to have the proper look and feel experience for your page:
| Setting | Description |
| PayLater | Should PayLater be visible as Button? Values: True / False Note: This option is available only for certain countries and within some amount limits. Reference: https://developer.paypal.com/braintree/articles/guides/payment-methods/paypal-pay-later-offers |
| PayLaterMessage | Should the PayLater Message be displayed in the Widget? Values: True / False Note: This option is available only for certain countries and within some amount limits. Reference: https://developer.paypal.com/braintree/articles/guides/payment-methods/paypal-pay-later-offers |
| ShippingPreference | Merchant Shipping preference Values: GET_FROM_FILE Use the customer-provided shipping address on the PayPal site. NO_SHIPPING Redact the shipping address from the PayPal site. Recommended for digital goods. SET_PROVIDED_ADDRESS Use the merchant-provided address (provided via the Widget). The customer cannot change this address on the PayPal site. Note: This setting, combined with the sending of ShippingAddress can affect the Merchants PayPal Seller Protection. Reference: For reference, please see PayPal Seller Protection - PayPal US (https://www.paypal.com/us/webapps/mpp/ua/seller-protection) |
| BrandName | Name to be displayed on the PayPal landing page. e.g. 'Style24 Discount' Value: string |
| UserAction | Configures a Continue or Pay Now checkout flow.
Values: CONTINUE After you redirect the customer to the PayPal payment page, a Continue button appears. Use this option when the final amount is not known when the checkout flow is initiated and you want to redirect the customer to the merchant page without processing the payment. PAY_NOW. After you redirect the customer to the PayPal payment page, a Pay Now button appears. Use this option when the final amount is known when the checkout is initiated and you want to process the payment immediately when the customer clicks Pay Now. Note: This must be according to the merchant shop flow If e.g. The shopper is shown an order confirmation page, then "Pay Now" should be shown If the shopper is shown an order review page, then "Continue" should be shown. |
| AllowAmountModification | Allow Amount modification for higher amounts after approval. See Confluence page for details. Values: true / false When the shopper is approving via the Widget to pay with PayPal, the amount is being validated. If "False", the amount must be equal of lower then the originally approved one. If "True", the amount can be higher. PayNext is not validating. In can of complaints from customers, PayPal will address this to the merchant. |
| PayLaterMessageStyle | PayLater Message Style (default is 'black') - e.g. 'monochrome' Values: black (default), if left empty - Black text with colored logo white White text with a white logo monochrome Black text with a black logo grayscale Black text with a grayscale logo Note: This setting, combined with the sending of ShippingAddress can affect the Merchants PayPal Seller Protection. Reference: For reference, please see https://developer.paypal.com/docs/checkout/pay-later/us/integrate/customize-messages |
| Shape | Shape of the buttons Values: rect (default), if left empty - Black text with colored logo pill White text with a white logo Reference: For reference, please see https://www.paypal.com/buttons/smart?flowloggingId=f684932fc0b45 |
| Color | The color of the buttons Values: gold blue silver white black Reference: For reference, please see https://www.paypal.com/buttons/smart?flowloggingId=f684932fc0b45 |
| Layout | The layout of the buttons Values: Horizontal Vertical Reference: For reference, please see https://www.paypal.com/buttons/smart?flowloggingId=f684932fc0b45 |
| Label | The layout of the buttons Values: paypal checkout buynow pay installment Reference: For reference, please see https://www.paypal.com/buttons/smart?flowloggingId=f684932fc0b45 |
| Height | The height of the buttons Values: Between 25 and 55 Reference: For reference, please see https://www.paypal.com/buttons/smart?flowloggingId=f684932fc0b45 |
| Tagline | Enable / Disable Tagline text "The safer, easier way to pay" Values: true / false Reference: For reference, please see https://www.paypal.com/buttons/smart?flowloggingId=f684932fc0b45 |
NOTE: Please be aware, that having multiple countries to serve with PayLater requires a PayPal Account Id per country! For further information, please refer to: https://developer.paypal.com/braintree/docs/guides/paypal/pay-later-offers#pay-later-messaging
Payment Options
This table shows the PayPal payment method type and the countries and currencies which are relevant for PayPal.
| Payment Method Type | Wallet, BNPL (PayLater) |
| Countries | Worldwide |
| Currencies | AUD, BRL, CAD, CNY, CZK, DKK, EUR, HKD, HUF, ILS, JPY, MYR, MXN, TWD, NZD, NOK, PHP, PLN, GBP, RUB, SGD, SEK, CHF, THB, USD |
For further information please refer to https://developer.paypal.com/docs/reports/reference/paypal-supported-currencies/
Technical Overview
For the new PayPal integration, the Payments API uses the PayPal Orders API v2 Orders (paypal.com) and the PayPal Payments V2 API Payments (paypal.com).
Onboarding
To start the ISU process, several steps must be taken by the Merchant with initial support from Payment Operations team.
NOTE: As a prerequisite, the merchant must already have an account with PayPal.
Steps that must be undertaken by the Merchant to process payments with PayPal:
The Merchant provides the following information to the Operations Team:
- Business email account
- Preferred language
- Logo URL
- Address
The Operations Team will generate a request to PayPal and obtain the Onboarding link. Use the link to an Onboarding starting page provided via Email from Operations Team. If permissions are granted by the merchant, then it can already start processing orders via Riverty.
Revoking Consent
The Merchant has the possibility to revoke their consent at any time by following the URL below and logging into their merchant account:
Test: https://www.sandbox.paypal.com/businessprofile/partner/consents/ Production: https://www.paypal.com/businessprofile/partner/consents/
Riverty will be notified, and the merchant configuration will not use the onboarded credentials anymore. Alternatively, the Merchant can request the Operation Team to revoke the consent.
Pre-Built UI Integration (Widget)
This section contains specific information about how to integrate the PayPal payment method in your Payment Page using the Pre-Built UI Widget.
An overview of the processes that happens using the Pre-Built UI:
Once the customer accepts the order and the PayPal popup closes, a payment token is received in the SuccessCallback of the Pre-Build UI widget. The paymentToken must be passed on the Merchant backend and from there issue a Create Authorization (https://api-explorer-test-aqount.finance.arvato.com/api-details#api=payments-api&operation=PaymentsCreateAuthorization-paynext) request using the paymentToken received. If the directCapture flag is set to true, this will result in a direct capture also at PayPal. If the parameter is sent as false, then PayPal will be instructed only to authorize, and then a Capture Transaction (https://api-explorer-test-aqount.finance.arvato.com/api-details#api=payments-api&operation=TransactionsCapture-paynext) request is required to finalize the process.
Special Parameters
All common interface structures including input/output parameters and objects can be found in the Pre-Built UI documentation page. This section only describes the specific requirements for PayPal payment methods.
| Parameter | Description |
| Amount | The amount must be specified in order for the pass it to PayPal to create the initial order |
| ExternalId | The order reference, if available, should be passed in |
| OrderItems | The order items are necessary in order to be displayed in the PayPal popup Note: Please do fill in the orderItems[].additionalProductInfo.productType to one of the following values: DIGITAL_GOODS, PHYSICAL_GOODS, DONATION. The field is mapped to PayPal's items.category property. |
| Shipping Address | The shipping address should be sent to the Pre-Built UI component in order for it to be displayed in the PayPal popup |
Billing Agreements
Riverty supports usage of PayPal Billing Agreements created on the PayPal v1 RestAPI. See Billing Agreements (https://developer.paypal.com/docs/api/payments.billing-agreements/v1/).
Having a Riverty RegistrationToken corresponding to a PayPal v1 BillingAgreement, a new Authorization can be created in PayNext based on the existing BillingAgreement. This works by specifying the RegistrationToken parameter in the Authorize request of the Reverty Payments API.
Settlement
While the end customer pays directly to PayPal, PayPal settles to your bank account directly. Please ensure to configure your merchant account at PayPal by using a bank account that we have read-access to. By default, the bank account will have been part of the list from your technical application.
Furthermore, please note that you will have to provide the PayPal credentials for the PayPal server, so we can fetch the settlement files automatically. The information is normally provided as part of your technical application when referring to the supported payment methods.
Refund
In case of a refund to be handled as part of a return, you should follow our use case Return creation to trigger the refund procedure in Accounting as a Service. Alternatively, if the refund happens in the context of a good will procedure, please follow the use case Good will creation for triggering a good will credit within Accounting as a Service.
Disputes & chargebacks
Consumers can issue disputes / chargebacks. In this case, PayPal will hold the corresponding funds on your account and provide you with a certain time period to clarify the complaint and/or prove the correctness of the transaction. Accounting as a Service can (optionally - if you wish so) work on defending the dispute by uploading documents proving the transaction at PayPal. Nevertheless, some chargebacks can usually not be avoided. In this case PayPal will debit the chargeback amount in the settlement file, Accounting as a Service will book it on the debtor account and either start the dunning flow (if configured) or write-off the chargeback and correct the VAT for the merchant. There is a notification to inform merchants about chargebacks to enable them to e.g. block services or customer accounts
Please note that managing/defending dispute & chargebacks is part of Accounting as a Service's communication related service and can be enabled and configured during your onboarding as part of the technical application).