Getting Started
Integrating with pluggy's payment gateway
This guide will walk you through the basics of creating your first Pix Automático payment request using Pluggy’s Payment Gateway. You’ll learn how to set up both fixed and variable amount requests, understand the available methods, and use the payment URL to deliver a seamless experience to your users.
Prerequisites
- Create a
PaymentRecipient
same as other payment methods, the destinatary account is configured as a PaymentRecipient.- Prepeare a callbackUrl to return to your application after payment has been succesfull / errored.
- Setup webhooks to receive notifications from PaymentRequests, PaymentIntents or PixAutomaticPayments.
- Understand how Pluggy manages payment requests, to share with end-users Payment Authorization Links.
1. Creating a Payment Request
To initiate a Pix Automático payment, you’ll need to create a payment request (mandate) via Pluggy’s API. This request defines the payer, the recurrence, and the payment details.
Example: Creating a Payment Request
POST /payments/requests/automatic-pix
Content-Type: application/json
{
"description": "Pix Automatico",
"recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
"interval": "WEEKLY",
"startDate": "2025-06-10",
"minimumVariableAmount": 0.01,
"maximumVariableAmount": 0.02,
"firstPayment": {
"date": "2025-06-08",
"amount": 0.03,
"description": "First month"
}
}
2. Fixed and Variable Amounts
Pluggy supports both fixed and variable amount payment requests:
- Fixed Amount: The same amount is charged on every recurrence (e.g., a subscription).
- Variable Amount: The amount can change for each payment (e.g., utility bills).
{
"description": "Your rent",
"recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
"interval": "MONTHLY",
"startDate": "2025-06-10",
"fixedAmount": 0.01,
"firstPayment": {
"date": "2025-06-08",
"amount": 100,
"description": "Rent"
}
}
{
"description": "Pix Automatico",
"recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
"interval": "WEEKLY",
"startDate": "2025-06-10",
"minimumVariableAmount": 100,
"maximumVariableAmount": 200,
"firstPayment": {
"date": "2025-06-08",
"amount": 300,
"description": "First month"
}
}
Extra considerations
When submitting payments you will be able to send an amount between minimumVariableAmount and maximumVariableAmount. You won't be able to send a value outside that range without creating another authentication.
The fixed payments won't be able submit a different value than the one configured.
First payment amounts can be different and bigger than the authorization that was requested. It doesn't affect the limits for that interval either.
3. Redirecting the user to Authorize
Once a payment request is created, Pluggy generates a payment URL. This URL is where your user (payer) will review and authorize the Pix Automático mandate.
-
How it works:
Redirect or send the payment URL to your user. They’ll be guided through the authorization process, which is fully compliant with Central Bank of Brazil requirements. -
Example response:
{
"id": "req_abc123",
"paymentUrl": "https://pay.pluggy.ai/pix-automatico/req_abc123",
"status": "CREATED"
}
- Best practices:
- Display the payment URL in your app or send it via email/SMS.
- Monitor the status of the payment request via webhooks or polling the API.
Direct API
To create a Pix Automático payment intent via the API, you need to send a POST request to /payments/intents
with a payload that includes the paymentRequestId, the payer’s CPF/CNPJ, and name.
// https://api.pluggy.ai/payments/intents
{
"paymentRequestId": "req_abc123", // The ID of the previously created payment request
"connectorId": 123, // The ID of the connector (bank/institution)
"parameters": {
"cpf": "12345678900", // CPF numbers
"name": "Maria Silva" // Full name of the payer
}
}
4. What Happens After Authorization?
- Once the user authorizes the payment request via the
paymentUrl
, Pluggy will generate a Payment Intent for the specificconnectorId
(the financial institution or bank selected by the user). - The Payment Intent represents the actual scheduled payment and can be tracked via Pluggy’s API and webhooks.
- You will receive real-time updates about the status of the Payment Intent, Payment Request and Automatic PIX.
- Including successful authorizations (
PAYMENT_COMPLETED
), rejections (CONSENT_REJECTED
) - Includes first payment notifications and future payments that are being scheduled
- Including successful authorizations (
Timeouts
If the payment authorization process is not completed it will update to
CONSENT_REJECTED
after 60 minutes and will be notified through webhooks as well.
5. First Payment
Automatically, after the authorization has been granted, if the first payment is scheduled for the same day (immediate payments), you will receive notifications that the payment has been scheduled and is being processed, and you will receive a second notification that the payment has been completed.
{
}
{}
6. Charging your customer
Once the payment request is authorized (Payment Request status is AUTHORIZED
), you can schedule new payments for your customer using the Pluggy API.
Scheduling a New Payment
To schedule a new Pix Automático payment, make a POST
request to: POST /payments/requests/{id}/automatic-pix/schedule
Where {id}
is the ID of the authorized payment request.
// POST /payments/requests/req_abc123/automatic-pix/schedule
// Content-Type: application/json
{
"amount": 150.00,
"date": "2025-07-10",
"description": "July utility bill"
}
{
"id": "66d503f1-0cfa-4d64-9f87-0782d959eba7",
"status": "SCHEDULED",
"amount": 150.00,
"description": "July utility bill",
"date": "2025-07-10",
"endToEndId": null,
"errorDetail": null
}
Important Considerations
- The payment request must be in the
AUTHORIZED
status.- The scheduled date must respect the interval and limits defined in the original authorization (e.g., monthly, weekly).
- Only one payment can be made in the interval. If you have configured the PaymentRequest to be monthly, you will be able to generate only one monthly payment
- For variable amount mandates, the amount must be within the authorized min/max range.
- All payment validations will return a HTTP 400 error explaining why the payment won't be scheduled.
Reviewing payments
- You can list all payments for a request using:
This will include the first payment as well.GET /payments/requests/{id}/automatic-pix/schedules
- Once you schedule an Automatic PIX, we will return it on the list and will send webhooks (
automatic_pix_payment/created
) when it is created. - On the date the payment was scheduled, it will try the payment and change to
COMPLETED
You will be able to list it and receive webhook notifications as well.
For more details, see the Pluggy API Reference: Schedule Automatic PIX payment.
Updated 2 days ago