Procurando a documentação anterior?Acesse v1.docs.pluggy.ai
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

Dados automáticos do PIX

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

Definições para o primeiro pagamento. É considerado como o pagamento de inscrição do usuário para o serviço.

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

Frequência permitida para pagamentos recorrentes de PIX sob um consentimento.

WEEKLYMONTHLYQUARTERLYSEMESTERYEARLY
automaticRetriesConfigurationobject

Configuração para tentativas automáticas. Se fornecido, os pagamentos agendados associados a este consentimento serão tentados novamente apenas nos dias especificados na matriz após a data do pagamento original. Isso não se aplica ao primeiro pagamento, apenas para pagamentos agendados.

retryDaysrequiredinteger[]
schedulerConfigurationobject

Configuração para agendamento automático de pagamentos. Quando ativado, o sistema agendará pagamentos de acordo com o intervalo de consentimento e a data de início.

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

Redirecionar URLs após o pagamento ser concluído ou encerrado com status de erro

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": 100.5,
  "startDate": "2025-06-10",
  "expiresAt": "2025-10-01",
  "isRetryAccepted": true,
  "firstPayment": {
    "date": "2025-06-10",
    "description": "Primeiro pagamento",
    "amount": 100.5
  },
  "interval": "WEEKLY",
  "callbackUrls": null,
  "recipientId": "05c693bf-c196-47ea-a28c-8251d6bb8a06",
  "isSandbox": false
}

Responses

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

Resposta com informações relacionadas a uma solicitação de pagamento

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

Ciclo de vida de uma solicitação de pagamento. - `CREATED`: a solicitação foi criada e está aguardando uma intenção de pagamento. - `IN_PROGRESS`: uma intenção de pagamento está sendo processada pela instituição. - `WAITING_PAYER_AUTHORIZATION`: o pagador deve autorizar o pagamento na instituição. - `AUTHORIZED`: apenas para PIX Automático. O consentimento recorrente foi autorizado; pagamentos individuais serão executados sob ele. - `SCHEDULED`: o pagamento está agendado para uma data futura. - `COMPLETED`: o pagamento foi confirmado pela instituição. - `ERROR`: o pagamento falhou (veja `errorDetail`). - `REFUND_IN_PROGRESS`: um reembolso foi solicitado e está sendo processado. - `REFUNDED`: o reembolso foi concluído. - `REFUND_ERROR`: o reembolso falhou. - `EXPIRED`: a solicitação expirou sem ser paga. - `CANCELED`: a solicitação foi cancelada.

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

Redirecionar URLs após o pagamento ser concluído ou encerrado com status de erro

option 2null | null
recipientobject | null

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

Any of:
option 1object

Destinatário incorporado dentro de uma solicitação de pagamento. Polimórfico dependendo do tipo de pagamento. - `BANK_ACCOUNT`: um destinatário de conta bancária registrada (veja `PaymentRecipient`). - `PIX_QR_CODE`: destinatário derivado de um código QR PIX anexado à solicitação. - `BOLETO`: destinatário derivado de um boleto anexado à solicitação.

option 2null | null
customerobject | null

Cliente associado à solicitação de pagamento

Any of:
option 1object

Resposta com informações relacionadas a um cliente de pagamento

option 2null | null
smartAccountobject | null

Conta inteligente que recebe os fundos, quando aplicável

Any of:
option 1object

Conta Pluggy Smart (conta de custódia) vinculada a uma solicitação de pagamento. Recebe fundos e permite que o cliente orquestre divisões e retiradas.

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

Dados do Boleto

option 2null | null
automaticPixobject

Dados automáticos do PIX

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

Definições para o primeiro pagamento. É considerado como o pagamento de inscrição do usuário para o serviço.

intervalrequiredstring

Frequência permitida para pagamentos recorrentes de PIX sob um consentimento.

WEEKLYMONTHLYQUARTERLYSEMESTERYEARLY
automaticRetriesConfigurationobject

Configuração para tentativas automáticas. Se fornecido, os pagamentos agendados associados a este consentimento serão tentados novamente apenas nos dias especificados na matriz após a data do pagamento original. Isso não se aplica ao primeiro pagamento, apenas para pagamentos agendados.

schedulerConfigurationobject

Configuração para agendamento automático de pagamentos. Quando ativado, o sistema agendará pagamentos de acordo com o intervalo de consentimento e a data de início.

scheduleobject
One of:
option 1object

Agende um atributo para gerar um único pagamento em uma data futura específica.

option 2object

Agende o atributo para gerar pagamentos diários a partir de `startDate`.

option 3object

Agende o atributo para gerar pagamentos semanais em um dia específico da semana.

option 4object

Agende o atributo para gerar pagamentos mensais em um dia específico do mês.

option 5object

Agende o atributo para gerar pagamentos em uma lista explícita de datas.

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": "d7059555-eadc-4f63-bb8c-1fb367b8dac6",
  "description": "Automatic PIX",
  "status": "CREATED",
  "createdAt": "2025-06-10T17:50:12.919Z",
  "updatedAt": "2025-06-10T17:50:12.919Z",
  "callbackUrls": null,
  "paymentUrl": "https://pay.pluggy.ai/d7059555-eadc-4f63-bb8c-1fb367b8dacd",
  "recipient": {
    "type": "BANK_ACCOUNT",
    "id": "02a1fde6-5183-4571-85cc-1ada6d25839d",
    "name": "My recipient",
    "taxNumber": "33333333000133",
    "isDefault": false,
    "paymentInstitution": {
      "id": "6dc10a50-c8ef-4c10-a505-84e701c2cfbb",
      "name": "Banco C6 S.A.",
      "tradeName": "BCO C6 S.A.",
      "ispb": "31872495",
      "compe": "336",
      "createdAt": "2023-12-08T11:44:20.234Z",
      "updatedAt": "2023-12-08T11:44:20.234Z"
    },
    "account": {
      "type": "*******",
      "number": "******396",
      "branch": "*001"
    },
    "pixKey": null,
    "createdAt": "2025-06-03T20:29:10.846Z",
    "updatedAt": "2025-06-03T20:29:10.846Z"
  },
  "clientPaymentId": null,
  "customer": null,
  "fees": null,
  "pixQrCode": null,
  "boleto": null,
  "smartAccount": null,
  "schedule": null,
  "automaticPix": {
    "interval": "WEEKLY",
    "expiresAt": "2025-06-16T23:59:59Z",
    "startDate": "2025-06-11",
    "fixedAmount": 0.01,
    "firstPayment": {
      "amount": 0.01
    }
  },
  "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 '{ "fixedAmount": 100.5, "startDate": "2025-06-10", "expiresAt": "2025-10-01", "isRetryAccepted": true, "firstPayment": { "date": "2025-06-10", "description": "Primeiro pagamento", "amount": 100.5 }, "interval": "WEEKLY", "callbackUrls": null, "recipientId": "05c693bf-c196-47ea-a28c-8251d6bb8a06", "isSandbox": false }'
Resposta de exemplo
{
  "id": "d7059555-eadc-4f63-bb8c-1fb367b8dac6",
  "description": "Automatic PIX",
  "status": "CREATED",
  "createdAt": "2025-06-10T17:50:12.919Z",
  "updatedAt": "2025-06-10T17:50:12.919Z",
  "callbackUrls": null,
  "paymentUrl": "https://pay.pluggy.ai/d7059555-eadc-4f63-bb8c-1fb367b8dacd",
  "recipient": {
    "type": "BANK_ACCOUNT",
    "id": "02a1fde6-5183-4571-85cc-1ada6d25839d",
    "name": "My recipient",
    "taxNumber": "33333333000133",
    "isDefault": false,
    "paymentInstitution": {
      "id": "6dc10a50-c8ef-4c10-a505-84e701c2cfbb",
      "name": "Banco C6 S.A.",
      "tradeName": "BCO C6 S.A.",
      "ispb": "31872495",
      "compe": "336",
      "createdAt": "2023-12-08T11:44:20.234Z",
      "updatedAt": "2023-12-08T11:44:20.234Z"
    },
    "account": {
      "type": "*******",
      "number": "******396",
      "branch": "*001"
    },
    "pixKey": null,
    "createdAt": "2025-06-03T20:29:10.846Z",
    "updatedAt": "2025-06-03T20:29:10.846Z"
  },
  "clientPaymentId": null,
  "customer": null,
  "fees": null,
  "pixQrCode": null,
  "boleto": null,
  "smartAccount": null,
  "schedule": null,
  "automaticPix": {
    "interval": "WEEKLY",
    "expiresAt": "2025-06-16T23:59:59Z",
    "startDate": "2025-06-11",
    "fixedAmount": 0.01,
    "firstPayment": {
      "amount": 0.01
    }
  },
  "errorDetail": null,
  "isSandbox": false
}