Getting Started

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 specific connectorId (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

📘
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.

{
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "automaticPixPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
  "endToEndId": "E37943755202506111319U0da92d1b7e",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "automatic_pix_payment/created"
}

{
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "automaticPixPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
  "endToEndId": "E37943755202506111319U0da92d1b7e",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "automatic_pix_payment/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:
```
GET /payments/requests/{id}/automatic-pix/schedules
```
This will include the first payment as well.
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 COMPLETEDYou will be able to list it and receive webhook notifications as well.

How to Retry a Payment

Sometimes, a scheduled PIX AUTOMATICO payment may fail due to insufficient funds, network issues, or other temporary problems. To ensure your payment workflow is robust, consider implementing a retry mechanism for failed payments.

Identify the Failed Payment
Monitor the status of your scheduled payments using the Pluggy API. Payments with a status such as ERROR are eligible for retry. You will receive webhook notifications for each payment status that changes.
Initiate a Retry
To retry a payment, use the API endpoint for creating a new payment, referencing the original payment’s details. You may need to provide the original payment ID and update any necessary fields (such as the scheduled date).
```
POST /payments/requests/{id}/automatic-pix/schedules/{scheduleId}/retry
Content-Type: application/json

{
  "date": "2024-07-01"
}
```
Track the Retry Attempt
Each retry will generate a new payment record. Use the response to track the new payment’s status.

📘
Rules and Best Practices

If a scheduled Pix fails, the system will retry up to three times within a seven-day window, using the same amount each time

First attempt occurs between 00:00–08:00 (BRT) on the scheduled day. If it fails, at least one retry is required between 18:00–21:00 (BRT) the same day. Institutions may choose to perform multiple retries within that evening window, but only the first retry is mandatory.

Example Workflow

The payment scheduled for July 1st failed due to insufficient funds.
Institutions may retry during that day after 18hs.
If the second attempt fails, you schedule a retry for the next day.
After 3 failed attempts, payment can be considered as unsuccessful.

Canceling Authorizations or Payments

Canceling an Authorization

Authorizations allow scheduled payments to be processed automatically. If a user wishes to stop future payments, they can cancel the authorization at any time.

How to Cancel an Authorization

Send a Cancel Request
Use the API endpoint to cancel the authorization. This will prevent any future payments from being processed under this authorization.
```
POST /payments/requests/{id}/automatic-pix/cancel
Content-Type: application/json
```
Check Payment Request Status
The API will return a 204 that the cancellation request has been accepted and that the bank will proceed to process the cancellation.
Listen to Webhooks: The updated payment request status will be sent as a notification. Confirm that the status is now CANCELED or equivalent.

📘
Important
Payment scheduled for the next day or first payments won't be cancelled.

Canceling a Payment

If a payment is scheduled but has not yet been processed, you may cancel it to prevent the transfer of funds.

How to Cancel a Payment

Send a Cancel Request
Use the API endpoint to cancel the payment.
```
POST /payments/requests/{paymentId}/automatic-pix/schedules/{scheduleId}/cancel
Content-Type: application/json
```
Replace {paymentId} with the actual ID of the payment you want to cancel.
Check Pix Automatico Payment Scheduled Status
The API will return a 204 that the cancellation request has been accepted and that the bank will proceed to process the cancellation.
Listen to Webhooks: The updated payment schedule status will be sent as a notification. Confirm that the status is now CANCELED or equivalent.

📘
Important:
Payments that are already processed or in a terminal state (e.g., COMPLETED, ERROR) cannot be canceled.
For cancellations done after the previous day time window (22hs BRT), may not be cancelled.

For more details, see the Pluggy API Reference: Schedule Automatic PIX payment.

Getting Started

📘
Prerequisites

1. Creating a Payment Request

Example: Creating a Payment Request

2. Fixed and Variable Amounts

📘
Extra considerations

3. Redirecting the user to Authorize

Direct API

4. What Happens After Authorization?

📘
Timeouts

5. First Payment

6. Charging your customer

Scheduling a New Payment

📘
Important Considerations

Reviewing payments

How to Retry a Payment

📘
Rules and Best Practices

Example Workflow

Canceling Authorizations or Payments

Canceling an Authorization

How to Cancel an Authorization

📘
Important

Canceling a Payment

How to Cancel a Payment

📘
Important:

📘Prerequisites

1. Creating a Payment Request

Example: Creating a Payment Request

2. Fixed and Variable Amounts

📘Extra considerations

3. Redirecting the user to Authorize

Direct API

4. What Happens After Authorization?

📘Timeouts

5. First Payment

6. Charging your customer

Scheduling a New Payment

📘Important Considerations

Reviewing payments

How to Retry a Payment

📘Rules and Best Practices

Example Workflow

Canceling Authorizations or Payments

Canceling an Authorization

How to Cancel an Authorization

📘Important

Canceling a Payment

How to Cancel a Payment

📘Important:

📘
Prerequisites

📘
Extra considerations

📘
Timeouts

📘
Important Considerations

📘
Rules and Best Practices

📘
Important

📘
Important: