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.

{
}

{}

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.

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