POST/payments/requests/automatic-pix

Create Automatic PIX payment request

Creates a payment request where the payment is made using automatic PIX. Once consent is granted by the user, payments can be scheduled according to the rules defined in the request.

Request Body

required

object

Automatic PIX data

fixedAmountnumber

Fixed charge amount; if filled in, it represents consent for payments of fixed amounts, not subject to change during the validity of the consent. If it's sent, minimumVariableAmount and maximumVariableAmount cannot be provided.

minimumVariableAmountnumber

Minimum amount allowed per charge; if filled in, it represents consent for payments of variable amounts. If it's sent, fixedAmount cannot be provided.

maximumVariableAmountnumber

Maximum amount allowed per charge; if filled in, it represents consent for payments of variable amounts. If it's sent, fixedAmount cannot be provided.

descriptionstring

Description for the automatic pix authorization

startDaterequiredstring (date)

Represents the expected date for the first occurrence of a payment associated with the recurrence. Date format must be YYYY-MM-DD (for example: 2025-06-16)

expiresAtstring (date)

Expiration date for the automatic pix authorization. The date must be in UTC and the format must follow the following pattern: YYYY-MM-DDTHH:MM:SSZ (for example: 2025-06-16T03:00:00Z).

isRetryAcceptedboolean

Indicates whether the receiving customer is allowed to make payment attempts, according to the rules established in the Pix arrangement.

firstPaymentobject

Definitions for the first payment. It is considered as the user's enrollment payment for the service.

datestring (date-time)

Defines the target settlement date of the first payment. If not provided, it will be settled immediately. Date format must be YYYY-MM-DD (for example: 2025-06-16)

descriptionstring

Description for the first payment. If not provided, the description will be the same as the description of the payment request

amountrequirednumber

Amount for the first payment.

intervalrequiredstring

Permitted frequency for recurring PIX payments under a consent.

WEEKLYMONTHLYQUARTERLYSEMESTERYEARLY

automaticRetriesConfigurationobject

“Configuration for automatic retries. If provided, the scheduled payments associated with this consent will only be retried on the days specified in the array after the original payment date. This does not apply to the first payment, only for scheduled payments.

retryDaysrequiredinteger[]

schedulerConfigurationobject

Configuration for automatic scheduling of payments. When enabled, the system will schedule payments according to the consent interval and start date.

enabledrequiredboolean

When true, payments are automatically scheduled by the system.

descriptionstring

Optional description for the scheduled payment. Overrides the payment request description when set.

valueForVariableAmountnumber

Required when the consent has variable amounts (minimumVariableAmount/maximumVariableAmount). Default amount to use when scheduling the payment.

callbackUrlsobject

Redirect urls after the payment was completed or ended in error status

successstring

Url to be redirected after the payment was completed

pendingstring

Url to be redirected when the payment is pending (for example, when it has status WAITING_PAYER_AUTHORIZATION

errorstring

Url to be redirected after the payment ended in error status

recipientIdrequiredstring

Primary identifier of the payment recipient

clientPaymentIdstring

Client payment identifier

customerIdstring

Primary identifier of the customer

Example

json

{
  "fixedAmount": 0,
  "minimumVariableAmount": 0,
  "maximumVariableAmount": 0,
  "description": "string",
  "startDate": "2024-01-01",
  "expiresAt": "2024-01-01",
  "isRetryAccepted": true,
  "firstPayment": {
    "date": "2024-01-01T00:00:00Z",
    "description": "string",
    "amount": 0
  },
  "interval": "WEEKLY",
  "automaticRetriesConfiguration": {
    "retryDays": [
      "1"
    ]
  },
  "schedulerConfiguration": {
    "enabled": true,
    "description": "string",
    "valueForVariableAmount": 0
  },
  "callbackUrls": {},
  "recipientId": "string",
  "clientPaymentId": "string",
  "customerId": "string"
}

Responses

200Create a Automatic PIX payment request.

object

Response with information related to a payment request

idrequiredstring

Primary identifier

amountnumber

Requested amount. For automatic pix it won't be returned

feesnumber

Fees charged for the payment request. This includes both Pluggy's fees and any customer-specific fees. Fees are calculated based on the payment method (PIX or Boleto) and the client's pricing configuration. For sandbox accounts, fees are set to 0.

descriptionstring

Payment description

statusrequiredstring

Lifecycle of a payment request. - `CREATED`: the request was created and is waiting for a payment intent. - `IN_PROGRESS`: a payment intent is being processed by the institution. - `WAITING_PAYER_AUTHORIZATION`: the payer must authorize the payment at the institution. - `AUTHORIZED`: only for Automatic PIX. The recurring consent was authorized; individual payments will be executed under it. - `SCHEDULED`: the payment is scheduled for a future date. - `COMPLETED`: the payment was confirmed by the institution. - `ERROR`: the payment failed (see `errorDetail`). - `REFUND_IN_PROGRESS`: a refund was requested and is being processed. - `REFUNDED`: the refund was completed. - `REFUND_ERROR`: the refund failed. - `EXPIRED`: the request expired without being paid. - `CANCELED`: the request was canceled.

CREATEDIN_PROGRESSWAITING_PAYER_AUTHORIZATIONAUTHORIZEDSCHEDULEDCOMPLETEDERRORREFUND_IN_PROGRESSREFUNDEDREFUND_ERROREXPIREDCANCELED

clientPaymentIdstring

Client payment identifier

createdAtrequiredstring (date-time)

Date when the payment request was created

updatedAtrequiredstring (date-time)

Date when the payment request was updated

callbackUrlsobject

Redirect urls after the payment was completed or ended in error status

successstring

Url to be redirected after the payment was completed

pendingstring

Url to be redirected when the payment is pending (for example, when it has status WAITING_PAYER_AUTHORIZATION

errorstring

Url to be redirected after the payment ended in error status

recipientobject | nullnullable

Recipient of the payment. Shape depends on the recipient `type`.

All of:

part 1object

Recipient embedded inside a payment request. Polymorphic depending on the kind of payment. - `BANK_ACCOUNT`: a registered bank-account recipient (see `PaymentRecipient`). - `PIX_QR_CODE`: recipient derived from a PIX QR code attached to the request. - `BOLETO`: recipient derived from a boleto attached to the request.

customerobject | nullnullable

Customer associated with the payment request

All of:

part 1object

Response with information related to a payment customer

smartAccountobject | nullnullable

Smart account that receives the funds, when applicable

All of:

part 1object

Pluggy Smart Account (escrow account) attached to a payment request. Receives funds and lets the client orchestrate splits and withdrawals.

paymentUrlrequiredstring

URL to begin the payment intent creation flow for this payment request

pixQrCodestring

Pix QR code generated by the payment receiver

boletoobject

Boleto data

digitableLinerequiredstring

Boleto digitable line

barcoderequiredstring

Boleto barcode

payerrequiredobject

Boleto payer information

recipientrequiredobject

Boleto recipient information

datestring (date-time)

Boleto issue date

dueDaterequiredstring (date-time)

Boleto due date

expirationDatestring (date-time)

After this date, the boleto cannot be paid

baseAmountrequirednumber

Boleto original amount, without interests, penalties and discounts

penaltyAmountrequirednumber

Boleto penalty amount. If there is no penalty, it will be returned as zero

interestAmountnumber

Boleto interest amount. If there is no interest, it will be returned as zero

discountAmountrequirednumber

Boleto discount amount. If there is no discounts, it will be returned as zero

totalAmountrequirednumber

Boleto final amount. It is equal to the base amount plus penalties and interests, minus discounts

updatedAtstring (date-time)

Date when the lastest information of this boleto has been retrieved

automaticPixobject

Automatic PIX data

fixedAmountnumber

minimumVariableAmountnumber

Minimum amount allowed per charge; if filled in, it represents consent for payments of variable amounts. If it's sent, fixedAmount cannot be provided.

maximumVariableAmountnumber

Maximum amount allowed per charge; if filled in, it represents consent for payments of variable amounts. If it's sent, fixedAmount cannot be provided.

startDaterequiredstring (date-time)

Represents the expected date for the first occurrence of a payment associated with the recurrence.

expiresAtstring (date-time)

Expiration date for the automatic pix authorization

isRetryAcceptedboolean

Indicates whether the receiving customer is allowed to make payment attempts, according to the rules established in the Pix arrangement.

firstPaymentobject

Definitions for the first payment. It is considered as the user's enrollment payment for the service.

intervalrequiredstring

Permitted frequency for recurring PIX payments under a consent.

WEEKLYMONTHLYQUARTERLYSEMESTERYEARLY

automaticRetriesConfigurationobject

schedulerConfigurationobject

Configuration for automatic scheduling of payments. When enabled, the system will schedule payments according to the consent interval and start date.

scheduleobject

One of:

option 1object

Schedule attribute to generate a single payment on a specific future date.

option 2object

Schedule attribute to generate daily payments starting from `startDate`.

option 3object

Schedule attribute to generate weekly payments on a specific day of the week.

option 4object

Schedule attribute to generate monthly payments on a specific day of the month.

option 5object

Schedule attribute to generate payments on an explicit list of dates.

errorDetailobject

Error details when payment request fails

codestring

Error code

providerMessagestring

Error message returned by the institution

isSandboxboolean

Indicates if this payment request is in sandbox mode. Default: false.

Default: false

Example response

json

{
  "id": "c2a6b7d9-3349-435d-8341-44021449ebbc",
  "amount": 150.5,
  "fees": 0.45,
  "description": "Order #4821",
  "status": "CREATED",
  "clientPaymentId": "order-4821",
  "createdAt": "2025-03-12T13:03:45.689Z",
  "updatedAt": "2025-03-12T13:03:45.689Z",
  "callbackUrls": {
    "success": "https://merchant.example.com/orders/4821/success",
    "error": "https://merchant.example.com/orders/4821/error"
  },
  "paymentUrl": "https://pay.pluggy.ai/c2a6b7d9-3349-435d-8341-44021449ebbc",
  "recipient": {
    "type": "BANK_ACCOUNT",
    "id": "5e9f8f8f-f8f8-4f8f-8f8f-8f8f8f8f8f8f",
    "name": "Conta empresa",
    "taxNumber": "12345678900",
    "isDefault": true,
    "paymentInstitution": {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "Banco J. Safra S.A.",
      "ispb": "03017677",
      "tradeName": "Banco Safra",
      "compe": "074",
      "createdAt": "2020-04-21T15:00:00.000Z",
      "updatedAt": "2020-04-21T15:00:00.000Z"
    },
    "account": {
      "branch": "0001",
      "number": "123456",
      "type": "CHECKING_ACCOUNT"
    },
    "pixKey": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "customer": null,
  "smartAccount": null,
  "pixQrCode": null,
  "boleto": null,
  "automaticPix": null,
  "schedule": null,
  "errorDetail": null,
  "isSandbox": false
}

Code Examples

bash

curl -X POST 'https://api.pluggy.ai/payments/requests/automatic-pix' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -d '{}'

Try It

API Key

Request Body (JSON)