PicPay

PicPay is a widely used digital wallet in Brazil that allows customers to make payments by authorizing transactions through the PicPay app via a payment URL. By integrating PicPay, merchants can reach a large base of mobile-first consumers in Brazil, providing a fast and convenient checkout experience.

This guide outlines the key concepts and implementation details required to integrate PicPay via API. It covers essential steps such as creating payment requests, redirecting customers for authorization, and monitoring payment status.

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.

How it works

PicPay 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 PicPay, send a payment request to EBANX with the appropriate parameters, including the PicPay payment type code.
• Redirect customer - Redirect the customer to the payment URL returned in the response. The customer authorizes the payment directly in the PicPay app.
• 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 cancelled (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 PicPay payment at checkout, create a payment request using the ws/direct endpoint. Set the payment_type_code parameter to picpay.

   
   

   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 CPF (Brazilian tax ID).
   payment.country	string	Yes	Two-letter country code. Must be br.
   payment.payment_type_code	string	Yes	Must be picpay.
   payment.merchant_payment_code	string	Yes	Unique merchant-generated payment identifier.
   payment.currency_code	string	Yes	Currency code. Must be BRL.
   payment.amount_total	number	Yes	Total payment amount.

   Optional parameters

   Parameter	Type	Required	Description
   payment.redirect_url	string	No	URL to redirect the customer back to your site after completing or abandoning the payment on PicPay.

   Tip

   Including a redirect_url is recommended so customers can return to your site after completing or cancelling the payment on PicPay.

   
   

   Sample request

   curl -X POST \
     --location 'https://api.ebanxpay.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": "picpay",
         "merchant_payment_code": "{{unique_merchant_code}}",
         "document": "{{tax_id}}",
         "redirect_url": "https://merchant.example.com/callback"
       }
     }'

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": "picpay",
       "redirect_url": "https://sandbox.ebanx.com/ws/redirect?hash=<{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 redirect_url provided in the response. This takes the customer to PicPay where they can complete the payment by authorizing it directly in the PicPay app.

   "redirect_url": "https://sandbox.ebanx.com/ws/redirect?hash=<{hash_here}>"

   PicPay app

   If the customer has the PicPay app installed, they can also receive a push notification to authorize the payment directly in-app when their registered buyer information (name, CPF, and email) matches their PicPay account.

   Caution

   If the customer does not complete the payment before the expiration time, the payment status will automatically change to cancelled (CA).

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 cancelled (CA).

   • Learn more about Retrieving Payment Statuschevron_right

6. Congratulations!

   You have successfully integrated PicPay.

   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.