PayPal

PayPal is a widely recognized digital wallet in Brazil that allows customers to pay for online purchases using their PayPal account balance, linked bank accounts, or credit cards. By integrating PayPal, merchants can reach a broad base of customers who prefer a trusted and globally recognized payment method, providing a secure and convenient checkout experience.

This guide outlines the key concepts and implementation details required to integrate PayPal via API. It covers essential steps such as creating a payment request, redirecting the customer for authorization, and monitoring payment status changes.

Requirements

• API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
• Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters. See EBANX Direct for more info.
• Knowledge of your development environment and tools.

How it works

PayPal enables digital wallet payments for online purchases in Brazil. Here is how the process works when integrated with the EBANX API:

• Initiate payment - When the customer selects PayPal, send a payment request to EBANX with the appropriate parameters, including the PayPal payment_type_code.
• Redirect customer - Redirect the customer to the PayPal checkout page using the redirect_url from the response. The customer authorizes the payment in their PayPal account.
• Payment confirmation - Once the customer completes the payment, EBANX updates the payment status from pending (PE) to confirmed (CO). If the payment is not completed, the status updates to canceled (CA).

Technical flow

Instructions

Follow the steps below.

1. Select your environment

   Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

   SandboxProduction

   https://sandbox.ebanx.com/ws/direct

2. Payment request

   Once your customer submits a PayPal payment at checkout, create a payment request using the ws/direct endpoint. Assign the payment_type_code parameter to the digital wallet code.

   
   

   Payment parameters

   Basic parameters

   Parameter	Type	Required	Description
   integration_key	string	Yes	Your unique EBANX integration key.
   payment.name	string	Yes	Customer full name.
   payment.email	string	Yes	Customer email address.
   payment.document	string	Yes	Customer document (CPF for Brazil).
   payment.country	string	Yes	Two-letter country code. Use br for Brazil.
   payment.payment_type_code	string	Yes	Must be paypal.
   payment.merchant_payment_code	string	Yes	Unique merchant-generated payment identifier.
   payment.currency_code	string	Yes	Currency code. Use BRL for Brazil.
   payment.amount_total	number	Yes	Total payment amount.
   payment.redirect_url	string	No	URL where the customer is redirected after completing or canceling the payment on PayPal. Used as both return and cancel URL.

   
   

   Sample request

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/direct' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "{{integration_key}}",
       "payment": {
         "amount_total": 99.85,
         "currency_code": "BRL",
         "name": "John Doe",
         "email": "john.doe@example.com",
         "country": "br",
         "payment_type_code": "paypal",
         "merchant_payment_code": "{{unique_merchant_code}}",
         "redirect_url": "https://merchant.example.com/callback",
         "document": "{{tax_id}}"
       }
     }'

   Tip

   The redirect_url parameter is used by PayPal as both the return URL (after the customer approves the payment) and the cancel URL (if the customer cancels). Ensure this URL handles both scenarios appropriately.

3. Payment response

   Each request returns a response similar to the example below.

   {
     "payment": {
       "hash": "<{hash_here}>",
       "country": "br",
       "merchant_payment_code": "{{unique_merchant_code}}",
       "order_number": null,
       "status": "PE",
       "status_date": null,
       "open_date": "{{YYYY-MM-DD HH:mm:ss}}",
       "confirm_date": null,
       "transfer_date": null,
       "amount_br": "99.85",
       "amount_ext": "99.85",
       "amount_iof": "0.00",
       "currency_rate": "1.0000",
       "currency_ext": "BRL",
       "due_date": "{{YYYY-MM-DD}}",
       "instalments": "1",
       "payment_type_code": "paypal",
       "redirect_url": "https://www.sandbox.paypal.com/checkoutnow?token=<{hash_here}>",
       "pre_approved": false,
       "capture_available": null
     },
     "status": "SUCCESS"
   }

   At this stage, the payment will appear as pending (PE) in your

   Merchant Areachevron_right

4. Redirect URL

   Redirect the customer to the link provided in the redirect_url field of the response. This URL points to the PayPal checkout page where the customer can authorize the payment.

   "redirect_url": "https://www.sandbox.paypal.com/checkoutnow?token=<{hash_here}>"

   Caution

   The PayPal order expires in 3 days if the customer does not approve it. If the order expires, the payment status will be updated to canceled (CA).

   Once the customer approves the payment on PayPal, EBANX automatically captures the payment through a webhook notification from PayPal. No additional action is required from the merchant to complete the capture.

5. Notifications

   • EBANX will send a notification whenever a payment status changes.

   • Make sure your system is set up to receive notifications from EBANX for any changes in payment status.

   • Learn more about Payment Notificationschevron_right

   Status

   • After receiving a notification, retrieve the payment status.

   • When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will automatically update to canceled (CA).

   • Learn more about Retrieving Payment Statuschevron_right

6. Congratulations!

   You have successfully integrated PayPal.

   For more information, refer to the

   Direct API reference guidechevron_right

Resources

Use the following resources when testing in your sandbox environment.

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.