PluggyDocs
POST/payments/requests/automatic-pix

Criar solicitação de pagamento PIX automático

Cria uma solicitação de pagamento onde o pagamento é feito usando PIX automático. Uma vez que o consentimento é concedido pelo usuário, os pagamentos podem ser agendados de acordo com as regras definidas na solicitação.

  • Se a descrição não for fornecida, cada instituição criará sua própria descrição para que o usuário entenda o que está autorizando. Elas podem adicionar "pluggy" em uma descrição genérica. É essencial fornecer uma descrição clara da solicitação e do primeiro pagamento para garantir que o usuário entenda do que se trata.

Request Body

required
object

Automatic PIX data

fixedAmountnumber

Valor de cobrança fixa; se preenchido, representa consentimento para pagamentos de valores fixos, não sujeitos a alteração durante a validade do consentimento. Se enviado, minimumVariableAmount e maximumVariableAmount não podem ser fornecidos.

minimumVariableAmountnumber

Valor mínimo permitido por cobrança; se preenchido, representa consentimento para pagamentos de valores variáveis. Se enviado, fixedAmount não pode ser fornecido.

maximumVariableAmountnumber

Valor máximo permitido por cobrança; se preenchido, representa consentimento para pagamentos de valores variáveis. Se enviado, fixedAmount não pode ser fornecido.

descriptionstring

Descrição para a autorização automática do pix

startDaterequiredstring (date)

Representa a data esperada para a primeira ocorrência de um pagamento associado à recorrência. O formato da data deve ser YYYY-MM-DD (por exemplo: 2025-06-16)

expiresAtstring (date)

Data de expiração para a autorização automática de pix. A data deve estar em UTC e o formato deve seguir o seguinte padrão: YYYY-MM-DDTHH:MM:SSZ (por exemplo: 2025-06-16T03:00:00Z).

isRetryAcceptedboolean

Indica se o cliente receptor está autorizado a fazer tentativas de pagamento, de acordo com as regras estabelecidas no arranjo do Pix.

firstPaymentobject

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

datestring (date-time)

Define a data de liquidação alvo do primeiro pagamento. Se não fornecida, será liquidada imediatamente. O formato da data deve ser YYYY-MM-DD (por exemplo: 2025-06-16)

descriptionstring

Descrição para o primeiro pagamento. Se não fornecida, a descrição será a mesma que a descrição da solicitação de pagamento.

amountrequirednumber

Valor para o primeiro pagamento.

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

Quando verdadeiro, os pagamentos são agendados automaticamente pelo sistema.

descriptionstring

Descrição opcional para o pagamento agendado. Substitui a descrição da solicitação de pagamento quando definida.

valueForVariableAmountnumber

Necessário quando o consentimento tem valores variáveis (minimumVariableAmount/maximumVariableAmount). Valor padrão a ser usado ao agendar o pagamento.

callbackUrlsobject | null
Any of:
option 1object

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

option 2null | null
recipientIdrequiredstring

Identificador principal do destinatário do pagamento

clientPaymentIdstring

Identificador de pagamento do cliente

customerIdstring

Identificador principal do cliente

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

200Criar uma solicitação de pagamento automático via PIX.
object

Response with information related to a payment request

idrequiredstring

Identificador principal

amountnumber

Valor solicitado. Para pix automático, não será devolvido.

feesnumber | null

Taxas cobradas pela solicitação de pagamento. Isso inclui tanto as taxas da Pluggy quanto quaisquer taxas específicas do cliente. As taxas são calculadas com base no método de pagamento (PIX ou Boleto) e na configuração de preços do cliente. Para contas de sandbox, as taxas são definidas como 0.

descriptionstring

Descrição do pagamento

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 | null

Identificador de pagamento do cliente

createdAtrequiredstring (date-time)

Data em que a solicitação de pagamento foi criada

updatedAtrequiredstring (date-time)

Data em que o pedido de pagamento foi atualizado

callbackUrlsobject | null
Any of:
option 1object

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

option 2null | null
recipientobject | null

Destinatário do pagamento. A forma depende do `tipo` do destinatário.

Any of:
option 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.

option 2null | null
customerobject | null

Cliente associado à solicitação de pagamento

Any of:
option 1object

Response with information related to a payment customer

option 2null | null
smartAccountobject | null

Conta inteligente que recebe os fundos, quando aplicável

Any of:
option 1object

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

option 2null | null
paymentUrlrequiredstring

URL para iniciar o fluxo de criação de intenção de pagamento para esta solicitação de pagamento

pixQrCodestring | null

Código QR Pix gerado pelo recebedor do pagamento

boletoobject | null
Any of:
option 1object

Boleto data

option 2null | null
automaticPixobject

Automatic PIX data

fixedAmountnumber

Valor fixo da cobrança; se preenchido, representa consentimento para pagamentos de valores fixos, não sujeitos a alteração durante a validade do consentimento. Se enviado, minimumVariableAmount e maximumVariableAmount não podem ser fornecidos.

minimumVariableAmountnumber

Valor mínimo permitido por cobrança; se preenchido, representa consentimento para pagamentos de valores variáveis. Se enviado, fixedAmount não pode ser fornecido.

maximumVariableAmountnumber

Valor máximo permitido por cobrança; se preenchido, representa consentimento para pagamentos de valores variáveis. Se enviado, fixedAmount não pode ser fornecido.

startDaterequiredstring (date-time)

Representa a data esperada para a primeira ocorrência de um pagamento associado à recorrência.

expiresAtstring (date-time)

Data de expiração para a autorização automática de pix

isRetryAcceptedboolean

Indica se o cliente receptor tem permissão para fazer tentativas de pagamento, de acordo com as regras estabelecidas no arranjo do Pix.

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

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

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.

option 6null | null
errorDetailobject | null

Detalhes do erro quando a solicitação de pagamento falha

codestring

Error code

providerMessagestring

Error message returned by the institution

isSandboxboolean

Indica se esta solicitação de pagamento está no modo sandbox. Padrão: falso.

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
}
curl -X POST \
  'https://api.pluggy.ai/payments/requests/automatic-pix' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -d '{}'
Resposta de exemplo
{
  "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
}