Sign in

v1

latestOpenAPI 3.1.0MIT2026-07-2484155300.5 KB
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.

post/payments/requests/automatic-pix

Request body

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

startDatestring date required

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.

interval'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'SEMESTER' | 'YEARLY' required

Permitted frequency for recurring PIX payments under a consent.

recipientIdstring required

Primary identifier of the payment recipient

clientPaymentIdstring

Client payment identifier

customerIdstring

Primary identifier of the customer

Example request

{
  "callbackUrls": {}
}

Response

Create a Automatic PIX payment request.

idstring required

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

status'CREATED' | 'IN_PROGRESS' | 'WAITING_PAYER_AUTHORIZATION' | 'AUTHORIZED' | 'SCHEDULED' | 'COMPLETED' | 'ERROR' | 'REFUND_IN_PROGRESS' | 'REFUNDED' | 'REFUND_ERROR' | 'EXPIRED' | 'CANCELED' required

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

Client payment identifier

createdAtstring date-time required

Date when the payment request was created

updatedAtstring date-time required

Date when the payment request was updated

paymentUrlstring required

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

pixQrCodestring

Pix QR code generated by the payment receiver

isSandboxboolean

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

Example response

{
  "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
}