Procurando a documentação anterior?Acesse v1.docs.pluggy.ai
PluggyDocs

Perguntas Frequentes

Perguntas comuns relacionadas a como o Pix Automático funciona, incluindo solicitações de pagamento, primeiros pagamentos, agendamento, cancelamento e tentativas.

Ver como Markdown

Common questions related to how Pix Automatico works.

Criando um pedido de pagamento automático PIX#

  • A autorização expira? O consentimento recorrente não tem uma data de expiração por padrão. Se necessário, você pode definir uma incluindo o campo expiresAt ao criar o pedido de pagamento. A tentativa inicial de autorização automática do PIX expira após 60 minutos se o pagador não a completar, e o consentUrl usado para autorização bancária expira após 5 minutos.

  • Quais são os campos fixedAmount, minimumVariableAmount e maximumVariableAmount? Nota: O seguinte se aplica apenas a pagamentos agendados e não ao primeiro pagamento. Para detalhes sobre o primeiro pagamento, veja a próxima seção "Primeiro Pagamento."

    • Se fixedAmount for fornecido, todos os pagamentos agendados associados a este pedido de pagamento devem ter exatamente esse valor.
    • Se minimumVariableAmount e maximumVariableAmount forem fornecidos, cada pagamento agendado deve ter um valor dentro dessa faixa. Uma vez que o consentimento é autorizado, esses valores não podem ser modificados. Importante: Algumas instituições (por exemplo, Nubank) permitem modificar o maximumVariableAmount quando o usuário autoriza o consentimento.

  • O que é o interval? Isso define a frequência do pagamento. Por exemplo, se o intervalo for definido como MONTHLY, apenas um pagamento por mês é permitido (excluindo o primeiro pagamento). O intervalo não pode ser alterado após a autorização do consentimento.

  • O que acontece se a description não for enviada? A instituição define uma descrição padrão.

  • Quais tipos de destinatários podem ser configurados no pedido de pagamento? Apenas empresas (CNPJ) podem ser configuradas como destinatários para pagamentos automáticos do Pix. O pagador pode ser uma pessoa física (CPF) ou uma empresa (CNPJ).

  • Posso mudar a conta do receptor? Sim, você pode fazer isso de duas maneiras:

Primeiro pagamento#

  • O valor pode exceder ou diferir do limite autorizado? Sim. O valor do primeiro pagamento é independente dos limites de pagamento autorizados. Por exemplo, se o usuário autorizou pagamentos entre R$100 e R$500, o primeiro pagamento ainda pode ser R$2.000.

  • Quando este pagamento é liquidado? Na firstPayment.date, se você a enviar. Se você omitir a data, o primeiro pagamento é liquidado imediatamente, no dia em que o usuário autoriza o pedido de pagamento.

  • O primeiro pagamento pode ser liquidado no mesmo dia que startDate? Não. O primeiro pagamento deve ser liquidado em um dia diferente de startDate, o início da recorrência. Se você enviar firstPayment.date, deve ser uma data diferente de startDate. Se você omitir, o primeiro pagamento é liquidado no dia em que o usuário autoriza (no horário de Brasília), então startDate não pode ser esse dia. Por exemplo, para cobrar a matrícula hoje e iniciar uma recorrência mensal, defina startDate um mês a partir de hoje.

    Caso contrário, a API retorna 400, tanto ao criar o pedido de pagamento quanto quando uma intenção de pagamento é criada para ele (POST /payments/intents):

    json
    {
  "code": 400,
  "codeDescription": "AUTOMATIC_PIX_INVALID_FIRST_PAYMENT_DATE",
  "message": "A data do primeiro pagamento deve ser diferente da data de início. Quando firstPayment.date não é fornecida, o primeiro pagamento é liquidado hoje."
}

  • É considerado parte dos limites de intervalo da autorização? Não. Por exemplo, se o usuário autorizou um pagamento por mês, o primeiro pagamento não afeta esse limite.

  • É obrigatório configurar um primeiro pagamento? Não, é completamente opcional.

Agendando um pagamento#

  • Quando um pagamento pode ser agendado? Após o pedido de pagamento ser autorizado, os pagamentos podem ser agendados entre D+2 e D+10 a partir de hoje, e somente se a periodicidade do pagamento permitir. Por exemplo, se a periodicidade for WEEKLY e um pagamento for agendado para quinta-feira, um novo pagamento pode ser agendado a partir da próxima quinta-feira (um pagamento por semana). O mesmo se aplica para outros tipos de intervalo (MONTHLY: mesmo dia todo mês, anualmente).

  • Como os ciclos de pagamento são calculados?

    Dependendo do tipo de intervalo selecionado, os ciclos de pagamento são calculados de maneira diferente, usando a startDate configurada como referência. Os pagamentos podem ser agendados em qualquer dia entre as datas de início e fim de cada ciclo (levando em conta as restrições D+2 e D+10 mencionadas anteriormente). Por exemplo:

    Data de início do consentimento: 20/12/2025

    • WEEKLY: Um novo ciclo começa a cada 7 dias
      • Primeiro ciclo: 20/12/2025 - 26/12/2025
      • Segundo ciclo: 27/12/2025 - 02/01/2026
      • Etc.
    • MONTHLY: Um novo ciclo começa no mesmo dia de cada mês. Se o dia não existir em um mês específico (por exemplo, 31/04), o ciclo começa no último dia disponível desse mês (neste caso, 30/04)
      • Primeiro ciclo: 20/12/2025 - 19/01/2026
      • Segundo ciclo: 20/01/2026 - 19/02/2026
      • Etc.
    • QUARTERLY: Mesmas regras que MONTHLY, mas a cada 3 meses:
      • Primeiro ciclo: 20/12/2025 - 19/03/2026
      • Segundo ciclo: 20/03/2026 - 19/06/2026
      • Etc.
    • SEMESTER: Mesmas regras que MONTHLY, mas a cada 6 meses:
      • Primeiro ciclo: 20/12/2025 - 19/06/2026
      • Segundo ciclo: 20/06/2026 - 19/12/2026
      • Etc.
    • YEARLY: Mesmas regras que MONTHLY, mas a cada 1 ano:
      • Primeiro ciclo: 20/12/2025 - 19/12/2026
      • Segundo ciclo: 20/12/2026 - 19/12/2027
      • Etc.

  • O que acontece se o pagamento falhar? Veja a seção "Tentativas".

  • Um pagamento agendado pode ser modificado? Não, uma vez que um pagamento é agendado, ele não pode ser modificado. Se você precisar alterar a data, o valor ou a descrição, deve cancelá-lo e agendar um novo.

Cancelando pagamentos e revogando consentimentos#

  • Quais pagamentos podem ser cancelados? Apenas pagamentos com o status SCHEDULED podem ser cancelados. Uma vez que o pagamento é concluído, ele só pode ser reembolsado manualmente pelo destinatário. Veja: Cancelar Agendamento de PIX AutomáticoAPI

  • Um consentimento automático do PIX pode ser revogado? Sim. Veja: Cancelar Consentimento de PIX AutomáticoAPI. Após revogar o consentimento, nenhum novo pagamento pode ser agendado sob esse pedido de pagamento. Este processo é assíncrono, então após receber uma resposta desse endpoint, alguns segundos podem passar até que o consentimento seja cancelado. Todos os pagamentos agendados (exceto aqueles a serem liquidadas no mesmo dia da cancelamento) também serão cancelados.

Tentativas#

  • Como implementar tentativas?

    Existem duas maneiras de implementar tentativas:

    • Usando o sistema de tentativas automáticas da Pluggy (recomendado)
    • Implementando um fluxo de tentativas personalizado. Mais informações aqui: Como Tentar um Pagamento

  • Quantas vezes o banco tenta executar o pagamento? O banco tenta executar o pagamento duas vezes:

    • Primeira tentativa: Entre 00:00 e 08:00 no dia agendado.
    • Segunda tentativa: Se a primeira tentativa falhar (por exemplo, devido a fundos insuficientes), uma segunda tentativa é feita entre 18:00 e 21:00 no mesmo dia.

    Depois disso, se o consentimento automático do PIX estiver configurado para permitir tentativas, até três tentativas adicionais podem ser feitas dentro de uma janela de 7 dias (5 para pagamentos semanais). Essas tentativas devem ser enviadas até 22:00 no dia anterior à nova data de pagamento agendada. Se o pedido de pagamento não permitir tentativas ou o número máximo de tentativas for alcançado, o pagamento receberá um status ERROR e não poderá ser tentado novamente.

    Para tentar um pagamento, ele deve ter sido agendado com sucesso e depois falhado na data de liquidação.

    Importante: se você perder a janela de 7 dias para agendar uma tentativa, esse pagamento não poderá mais ser tentado e você não poderá agendar novos pagamentos durante esse período. Além disso, a janela de 7 dias pode ser mais curta se o ciclo de pagamento terminar antes desse dia.

Sandbox#

  • Como posso testar o Pix Automático sem uma conta bancária real? Use o banco sandbox: crie o pedido de pagamento com isSandbox: true, um destinatário CNPJ e uma intenção de pagamento com conector 600 e os parâmetros cpf: "76109277673" e name. Um firstPayment sem data ou datado para hoje é executado logo após o consentimento, desde que startDate seja um dia posterior; um firstPayment futuro e os pagamentos que você agenda (entre D+2 e D+10) são executados às 09:00 UTC na sua data. O valor 404.04 simula uma falha da instituição. Veja Testando no sandbox.
Esta página foi útil?