Transactional PIX

1. Creating an Account

Each client should have a dedicated account linked to their CNPJ. Here's how to create an account:

curl --request POST \
     --url https://api.pluggy.ai/payments/smart-accounts \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "address": {
    "city": "São Paulo"
  },
  "itemId": "93ce8ae6-d291-463c-9c50-3db6daa40a23",
  "email": "[email protected]",
  "phoneNumber": "valid Brazilian phone number",
  "isSandbox": false
}
'

 

Parameters:

• itemId: An existent item id belongs to a previous item connected.
• email: Your client’s email address.
• phoneNumber: A valid Brazilian phone number.
• isSandbox: Set to true for sandbox mode, and false for production.

2. Creating a Payment

Once the account is created, you can create a payment request. Keep in mind, the smart account acts as a proxy, so you’ll need to specify the recipient bank account.

Step 1: Create a Payment Request

curl --request POST \
     --url https://api.pluggy.ai/payments/requests \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": 100,
  "description": "Este é um pagamento único.",
  "recipientId": "your-client",
  "smartAccountId": "your-client-smart-account-id"
}
'

Parameters:

• amount: Payment amount.
• description: Brief description of the payment.
• recipientId: The recipient’s bank account ID.
• smartAccountId: The smart account ID created in the previous step.

Step 2: Create a Payment Intent (Generate a PIX QR Code)

curl --request POST \
     --url https://api.pluggy.ai/payments/intents \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "paymentRequestId": "payment-request-id",
  "paymentMethod": "PIX"
}
'

Response Example:

{
    "id": "bb37b8b3-0016-4d18-84bb-96a8d4405c3e",
    "status": "PAYMENT_PENDING",
    "pixData": {
        "value": "00020126580014br.gov.bcb.pix...",
        "qr": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
    },
    "paymentMethod": "PIX"
}

• pixData.value: Use this value if the user prefers to copy and paste the code into their banking app.
• pixData.qr: The QR code in base64 format, which can be rendered for the user to scan and pay.

3. Setting Up Webhooks

You can receive notifications about the payment status by setting up webhooks. Listen to the payment_intent/completed event for payment completion.

For more information on webhooks, refer to the official documentation: Pluggy Webhooks

4. Testing in Sandbox Mode

To test your integration without moving real money, enable sandbox mode by setting isSandbox to true when creating the smart account:

{
  "isSandbox": true
}

Testing Flow:

When a payment is created using a sandbox account, the payment will be a “fake” transaction.

After generating the payment intent, you can scan the QR code or paste the pixData.value into your browser to simulate a successful payment.

The transaction will be automatically fulfilled, allowing you to test the webhook notifications and integration.

This guide should now be ready for you to copy and paste into your project documentation! Let me know if you need any adjustments.