--- title: "PayPal" description: "PayPal is one of the most widely used payment methods in the world. In this guide you will find out how to activate it, configure it on Fabrick Payment Orchestra and integrate it correctly in your ecommerce." url: "https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/paypal/" language: "en" --- # PayPal ## Why choose PayPal PayPal is one of the **most widely used payment methods in the world**, available in over 200 countries. Integrating it into your ecommerce expands the available payment options and increases user trust thanks to a well-established and recognisable checkout experience. > **Learn more** > > For further information visit the [official website](https://www.paypal.com/us/business) --- ## Services and features available through Fabrick integration The integration of PayPal with Fabrick Payment Orchestra provides a complete ecosystem of features to simplify transaction management and improve the experience for both the merchant and the customer. - **Seller Protection**: protects the merchant from unauthorised transactions or disputes, reducing the risk of fraud ([learn more](https://www.paypal.com/it/webapps/mpp/paypal-safety-and-security)). - **Fabrick Guaranteed Payments**: fraud prevention service supporting the merchant ([learn more](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/features/fraud-prevention/fabrick-guaranteed-payments/)). - **Instalment payments**: the *Pay Later* solution allows customers to split the amount into instalments, increasing purchasing flexibility ([learn more](https://developer.paypal.com/docs/checkout/pay-later/it/)). - **Recurring payments**: ideal for subscriptions or ongoing services. - **Advanced transaction management**: support for partial or multiple captures and refunds for flexible payment management. - **Separated or unified authorization and financial confirmation**: the capture can be unified with the authorization or requested at a later time. - **Multi-currency support**: compatibility with multiple currencies ([full list](https://developer.paypal.com/docs/reports/reference/paypal-supported-currencies/)). - **International coverage**: available in over 200 countries ([learn more](https://www.paypal.com/us/webapps/mpp/country-worldwide)). - **Simplified reconciliation**: payment management via dedicated reports ([learn more](https://www.fabrick.com/it-it/assistenza/fabrick-dashboard/)). - **Chargeback**: disputes are managed directly through the PayPal dashboard ([learn more](https://securepayments.paypal.com/it/cshelp/article/che-cosa-sono-i-chargeback-e-perch%C3%A9-ne-ho-ricevuto-uno-help607)). --- ### Separated and unified capture To set or change how transactions are handled for the payment method: 1. Log in to the Dashboard and go to **Settings → Access the configurations** ![Accessing the configurations from the Dashboard](https://docs.fabrick.com/en/assets/images/dashboard-access-configurations-f4782eb17db7b8fb6f23649ba8e3e5d7.png) 2. Once redirected to the back office, go to **Configurations → Environment** and click **MOTO**: a side panel opens with the list of active payment methods 3. Find the payment method and select the mode you want between **Unify transaction** and **Separate** ![MOTO configuration for PayPal](https://docs.fabrick.com/en/assets/images/paypal-moto-62b5c1d7b12834d19c72704a37b10d6d.png) > **MOTO** > > For more details on how the two modes work, see the [separated and unified capture](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/introduction/getting-started/#moto) section. --- ## PayPal on Fabrick Payment Orchestra: activation and integration methods ### Activation request You can request the activation of PayPal through Fabrick by: - Contacting your account manager - Contacting support at the following [link](https://landing.fabrick.com/fabrick-dashboard-support) ### Linking your PayPal Business account Once the payment method has been activated, you need to link your PayPal Business account to the Fabrick platform: - **Sandbox**: use a [test PayPal Business account](https://developer.paypal.com/tools/sandbox/accounts/) - **Production**: log in with your Business account credentials To complete the connection: 1. Access the Fabrick Dashboard 2. From the side menu, select **Workspace → Stores → \[Select store] → Configurations → Activate now** ![PayPal](https://docs.fabrick.com/en/assets/images/pp-link-01-960484e165e84bd24ca201bbe9d6e1a3.png) 3. Click **Activate now**, you will be redirected to the PayPal connection page ![PayPal](https://docs.fabrick.com/en/assets/images/pp-link-02-199aaaa1f77f7acfb896ef315f153338.png) 4. Enter your Business account credentials and confirm access 5. Authorise Fabrick by clicking **Allow** ![PayPal](https://docs.fabrick.com/en/assets/images/pp-link-03-28e3d53f4a11e6cbd19df015dc2ec096.png) 6. After authorisation, click **Return to store** to complete the procedure ![PayPal](https://docs.fabrick.com/en/assets/images/pp-link-04-4f5f42e2cbc323efbc36710fbc997d2e.png) 7. The status in the dashboard will change from **Activate now** to **Activated** ![PayPal](https://docs.fabrick.com/en/assets/images/pp-link-05-3824315bf14384d28c7178857ccb5132.png) > **Activation complete** > > From this moment, your e-commerce is ready to accept PayPal payments through Fabrick Payment Orchestra. ### Integration types Fabrick offers two integration methods for using PayPal: - **Hosted integration** ### Supported integrations ✓ — Checkout Page ✓ — Pay By Link ✓ — Web Component ✓ — Lightbox PayPal is displayed directly on the Fabrick payment page, with no development effort required on the merchant's side. Fabrick autonomously handles the display of the payment method and the entire processing phase. - **API integration** ### Supported integrations ✓ — API Only With this integration type the redirect to PayPal is handled directly through the API. You need to initialise the transaction with `payment/create` and handle the buyer's redirect. --- ## Hosted integration **PayPal is displayed directly on the Fabrick payment page**, with no additional development required from the merchant. Fabrick autonomously handles the display of the payment method and the entire transaction processing phase. To set up the call for the hosted integration, go to the [creating the transaction and redirecting to PayPal](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/paypal/#creating-the-transaction-and-redirecting-to-paypal) section and **remove the `paymentType` field** from the `payment/create` call. ![PayPal](https://docs.fabrick.com/en/assets/images/pp-buyer-01-07f96f9bbe23c868d9941e0f5d35f5ec.png) When the user selects PayPal, they are redirected to the service to log in and complete the payment. ![PayPal](https://docs.fabrick.com/en/assets/images/pp-buyer-02-ee59217d6a05d4918f7967e285cb7f22.png) --- ## API integration To request a PayPal payment using the API integration, initialize the transaction through `payment/create`, setting the `paymentType` field to the **`PAYPAL`** tag, and handle the buyer redirect to the payment method. ### Creating the transaction and redirecting to PayPal **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (production): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "100", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "paymentType": ["PAYPAL"], // Remove this line for the hosted integration "paymentChannel": { "channelType": ["LINK"] } } ``` The response returns the redirect link for the buyer to PayPal in the `payload.userRedirect.href` field. **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "paymentToken": "f0419188-8a78-4918-913c-a491e4e78084", "paymentID": "1881129911957", "userRedirect": { "href": "https://sandbox-web.axerve.com/orchestra/checkout/a/f991s1ba01d24eacaa3fac4b2145262a/b/36ab092425ff34515f7430e38babb28b84f16a31d63102b829072a1366c13580ae128e86-d779-4d98-88a2-0c035bcbd42eiAQ8ZaRT3IFyanLLjcIxtsuc3DTwycBdj5FD7FjuhlKm-mNnpirMdm9p3O8bhycmHVVPz6QOyo811UzHG3csjOSlH2KbF2EiUIxEwWFPAvk9TdUDrgWtyKLJYWayfzbZlP4iULt9eHTvhJEhK21sS8Smd0hX" }, "qrCode": null } } ``` > **PayPal button** > > The returned link can be used under a *Pay with PayPal* button, following [PayPal's graphic guidelines](https://developer.paypal.com/docs/log-in-with-paypal/customize/button-design-guide/). --- ## Additional payment method features You can enable additional features on the transaction by modifying the `payment/create` call to include specific services. The configured services will be automatically applied to the transaction when the customer selects PayPal. ### Seller Protection To request the Seller Protection feature applied to a PayPal transaction, in the `POST /payment/create` call, add the `OrderDetails` object by populating the `ShippingAddress` fields, so that the shipping information is correctly transmitted to PayPal. **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (production): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "10", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "paymentType": ["PAYPAL"], "paymentChannel": { "channelType": ["LINK"] }, "OrderDetails": { "ShippingAddress": { "FirstName": "John", "Lastname": "Doe", "StreetName": "Via Corradino Sella, 10", "Streetname2": "", "CountryCode": "IT", "State": "Biella", "StateCode": "BI", "City": "Biella", "ZipCode": "13900", "PrimaryPhone": "015012345" } } } ``` ![PayPal](https://docs.fabrick.com/en/assets/images/pp-seller-01-315fc851b6cc67664af352bd40463199.png) ### Fabrick Guaranteed Payment For a PayPal transaction it is possible to add the [Fabrick Guaranteed Payment](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/features/fraud-prevention/fabrick-guaranteed-payments/) service in the call. It can also be used in combination with Seller Protection for an additional level of protection. ### Installment payment No specific parameters need to be added in the call — PayPal automatically offers the installment option based on the rules of the [Pay Later](https://developer.paypal.com/docs/checkout/pay-later/it/) service. Upon completion of the transaction, the full amount is credited to the merchant. ![PayPal](https://docs.fabrick.com/en/assets/images/pp-paylater-02-it-5f53033b8221396e7db6bb7c6c5b1719.png) Upon request, the **Pay Later** button can be enabled separately. ![PayPal](https://docs.fabrick.com/en/assets/images/pp-paylater-01-97c987bd7a69e460a579d0471707281e.png) > **Direct redirect to the payment method** > > To redirect the buyer directly to the installment payment, if you have requested separate activation of the **Pay Later** button, set the `paymentType` field to the **`PAYPAL_BNPL`** tag in the `POST /payment/create` call. ### Recurring payments #### Billing agreement initialisation In the `POST /payment/create` call, add the `payPalDescription` field with the agreement description. **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (production): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "100", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "paymentChannel": { "channelType": ["LINK"] }, "payPalDescription": "Description Billing Agreements" } ``` **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "paymentToken": "f0419188-8a78-4918-913c-a491e4e78084", "paymentID": "1881129911957", "userRedirect": { "href": "https://sandbox-web.axerve.com/orchestra/checkout/a/f991s1ba01d24eacaa3fac4b2145262a/b/36ab092425ff34515f7430e38babb28b84f16a31d63102b829072a1366c13580ae128e86-d779-4d98-88a2-0c035bcbd42eiAQ8ZaRT3IFyanLLjcIxtsuc3DTwycBdj5FD7FjuhlKm-mNnpirMdm9p3O8bhycmHVVPz6QOyo811UzHG3csjOSlH2KbF2EiUIxEwWFPAvk9TdUDrgWtyKLJYWayfzbZlP4iULt9eHTvhJEhK21sS8Smd0hX" }, "qrCode": null } } ``` The buyer confirms authorisation by clicking **Accept and continue**. ![PayPal](https://docs.fabrick.com/en/assets/images/pp-recurring-01-2e705fe9c121382dff575a36c4d64837.png) Upon completion, retrieve the generated token via `GET /payment/detail` in the `payload.token` field and save it for subsequent payments. **Request** ```http GET /api/v1/payment/detail/{paymentID} Host (sandbox): sandbox.gestpay.net Host (production): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "transactionType": "detail", "transactionResult": "APPROVED", "transactionState": "AUT", "transactionErrorCode": "0", "transactionErrorDescription": "Transaction successfully completed", "bankTransactionID": "1363", "shopTransactionID": "FBK_OrderID", "shopTransactionID_2": "", "authorizationCode": "PP7476", "paymentID": "1881129911957", "currency": "EUR", "country": "", "company": "PayPal", "tdLevel": "", "threeDS": { "authenticationResult": null, "transDetails": null }, "events": [ { "event": { "eventtype": "AUT", "eventamount": "10.00", "eventdate": "07/05/25 14:45:31", "eventARN": "", "eventID": "", "eventReferred": "" } } ], "buyer": { "name": "", "email": "" }, "risk": { "riskResponseCode": "", "riskResponseDescription": "" }, "customInfo": null, "alertCode": "", "alertDescription": "", "cvvPresent": "FALSE", "dcc": null, "maskedPAN": "", "paymentMethod": "PayPal", "productType": "", "token": "PPG5KMGN62NGKRLV", "tokenExpiryMonth": "", "tokenExpiryYear": "", "tokenDetails": null, "fraudPrevention": { "check": "FALSE", "state": "", "description": "", "order": "" }, "automaticOperation": { "type": "CAN", "date": "01/06/25 00:00:00", "amount": "10.00" } } } ``` > **Amount €0** > > It is possible to set the amount to €0. In this way, at the time of billing agreement initialisation, PayPal will not charge the customer any amount but will still return the token needed for subsequent payments. > > **Response detail** > > **Request** > > ```http > GET /api/v1/payment/detail/{paymentID} > Host (sandbox): sandbox.gestpay.net > Host (production): ecomms2s.sella.it > Authorization: apikey **************** > Content-Type: application/json > ``` > > **Response** > > ```json > { > "error": { > "code": "0", > "description": "request correctly processed" > }, > "payload": { > "transactionType": "detail", > "transactionResult": "APPROVED", > "transactionState": "", > "transactionErrorCode": "", > "transactionErrorDescription": "", > "bankTransactionID": "", > "shopTransactionID": "", > "shopTransactionID_2": "", > "authorizationCode": "", > "paymentID": "", > "currency": "", > "country": "", > "company": "", > "tdLevel": "", > "threeDS": { > "authenticationResult": null, > "transDetails": null > }, > "events": null, > "buyer": null, > "risk": null, > "customInfo": null, > "alertCode": "", > "alertDescription": "", > "cvvPresent": "", > "dcc": null, > "maskedPAN": "", > "paymentMethod": "", > "productType": "", > "token": "PPG5KMGN62NGKRLV", > "tokenExpiryMonth": "", > "tokenExpiryYear": "", > "tokenDetails": null, > "fraudPrevention": null, > "automaticOperation": null > } > } > ``` > **What is a billing agreement?** > > A **billing agreement** is an agreement between the buyer and the merchant that allows charges to be made to the customer's PayPal account for future payments, without the buyer needing to authenticate again for each transaction. It is the foundation for recurring and on-demand payments via PayPal ([learn more](https://developer.paypal.com/api/rest/integration/orders-api/api-use-cases/billing-agreements/)). > **Compatibility** > > This service does not support **payment in installments**. #### Using the token for subsequent payments Create the payment request using the `POST /payment/create` call. **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (production): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "100", "currency": "EUR", "shopTransactionID": "FBK_OrderID" } ``` **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "paymentToken": "f0419188-8a78-4918-913c-a491e4e78084", "paymentID": "1881129911957", "userRedirect": null, "qrCode": null } } ``` In the `POST /payment/submit` call, use the token to process the payment: - Header **`PaymentToken`**: set to the `paymentToken` received in the previous step - Body: add `paymentTypeDetails.payPal.token` set to the PayPal token **Request** ```http POST /api/v1/payment/submit Host (sandbox): sandbox.gestpay.net Host (production): ecomms2s.sella.it PaymentToken: f0419188-8a78-4918-913c-a491e4e78084 Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "paymentType": "PAYPAL", "paymentTypeDetails": { "payPal": { "token": "PPG5KMGN62NGKRLV" } } } ``` **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "transactionType": "submit", "transactionResult": "OK", "transactionErrorCode": "0", "transactionErrorDescription": "Transaction successfully completed", "bankTransactionID": "1414", "shopTransactionID": "FBK_OrderID", "shopTransactionID_2": "", "authorizationCode": "PP2163", "paymentID": "1881129911957", "currency": "EUR", "country": "", "company": null, "tdLevel": "", "buyer": { "name": "", "email": "" }, "risk": { "riskResponseCode": "", "riskResponseDescription": "" }, "customInfo": {}, "alertCode": "", "alertDescription": "", "cvvPresent": "", "maskedPAN": "", "paymentMethod": "", "productType": "", "token": "", "tokenExpiryMonth": "", "tokenExpiryYear": "", "userRedirect": { "href": "https://sandbox.gestpay.net/pagam/AxerveThankYou.aspx" } } } ``` > **Recurring payment** > > If a recurring payment is requested, the system returns a direct link to PayPal, bypassing the selection page. --- ## Reconciliation From the Reports section of the dashboard you can configure dedicated reports for reconciliation. **By event:** - *Custom number* (PayPal) ↔ *Reconciliation key* (Fabrick) - *Transaction code* (PayPal) ↔ *PayPal ID* (Fabrick) - *Merchant order number* (PayPal) ↔ *Shop transaction ID + \_ + Capture ID* (Fabrick) **By payment:** - *Custom number* (PayPal) ↔ *Reconciliation key* (Fabrick) - *Transaction code* (PayPal) ↔ *PayPal ID* (Fabrick) For more details, refer to the [dashboard guide](https://www.fabrick.com/it-it/assistenza/fabrick-dashboard/). --- ## Support **Fabrick** - **Status page**: [https://status.fabrick.com/](https://status.fabrick.com/) - **Support**: [https://landing.fabrick.com/fabrick-dashboard-support](https://landing.fabrick.com/fabrick-dashboard-support) **PayPal** - **Status page**: [https://www.paypal-status.com/product/production](https://www.paypal-status.com/product/production) - **Support**: [https://developer.paypal.com/support/](https://developer.paypal.com/support/)