Pagamentos Agendados (Pix Agendado)

Com nossa funcionalidade de iniciação de pagamentos, você pode agendar pagamentos para ocorrer no futuro (também chamado de PIX RECORRENTE) usando qualquer um dos seguintes modos:

• ÚNICO: Agendar um pagamento para ocorrer em um momento específico no futuro.
• DIÁRIO: Agendar vários pagamentos para ocorrer todos os dias, a partir de uma data específica.
• SEMANAL: Agendar vários pagamentos para ocorrer todas as semanas, a partir de uma data específica.
• MENSAL: Agendar vários pagamentos para ocorrer todos os meses, a partir de uma data específica.
• PERSONALIZADO: Agendar vários pagamentos para ocorrer em datas específicas no futuro.

Agendando um pagamento#

1. Crie uma Solicitação de PagamentoAPI incluindo um objeto schedule:

{
  "amount": 1333.33, // O valor a ser pago todos os dias/semanais/mensais/personalizados
  "description": "Minha solicitação de pagamento 2",
  "schedule": {
    "type": "DIÁRIO",
    "startDate": "2024-06-26", // Data do primeiro pagamento
    "occurrences": 2 // Quantas vezes repetir
  },
  "recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}

2. Autorize a Solicitação de Pagamento com nosso App de Pagamentos (visitando o paymentUrl na resposta).

3. Após o usuário escolher a instituição para pagar, inserir seu CPF/CNPJ e clicar em Pagar, um Intent de Pagamento com status CONSENT_AWAITING_AUTHORIZATION é criado. Isso aciona o webhook payment_intent/created. O usuário agora é redirecionado para sua instituição para autorizar o pagamento agendado.

4. Uma vez autorizado, o Intent de Pagamento mudará o status para PAYMENT_COMPLETED. Isso aciona o webhook payment_intent/completed. Agora, um ou mais Pagamentos Agendados (pagamentos a ocorrer no futuro) serão criados. Cada criação acionará o webhook scheduled_payment/created.

5. Você pode agora obter a lista de Pagamentos AgendadosAPI:

{
  "total": 2,
  "totalPages": 1,
  "page": 1,
  "results": [
    {
      "id": "9f12b911-a064-4310-89f2-8d411e10b160",
      "status": "AGENDADO",
      "scheduledDate": "2024-06-26",
      "description": "Minha solicitação de pagamento 1/2"
    },
    {
      "id": "1f1f04e8-0bcf-4baf-bbbd-8bedf8478503",
      "status": "AGENDADO",
      "scheduledDate": "2024-06-27",
      "description": "Minha solicitação de pagamento 2/2"
    }
  ]
}

6. Em cada uma das datas agendadas, um pagamento será acionado na instituição. Isso resultará na mudança de status do Pagamento Agendado para COMPLETO ou ERRO em caso de falha. Isso aciona o webhook scheduled_payment/completed ou scheduled_payment/error.

7. Se o usuário cancelar um Pagamento Agendado da instituição, ele mudará o status para CANCELADO e acionará o webhook scheduled_payment/canceled.

8. Após todos os Pagamentos Agendados serem COMPLETOS, a Solicitação de Pagamento mudará o status para COMPLETO.

Modificando ou cancelando pagamentos agendados#

Se o usuário ainda não autorizou um pagamento agendado, você pode modificá-lo usando o endpoint PATCH /payment-requests/{id}, ou excluí-lo usando o endpoint DELETE /payment-requests/{id}.

Após o usuário ter autorizado um Pagamento Agendado, você não pode adicionar ou editar os Schedules resultantes. No entanto, você pode excluir um schedule específico ou cancelar o pagamento inteiro.

O usuário autorizador também pode cancelar todos os schedules diretamente de seu banco. Você pode reagir a essa mudança com um webhook.

Modos de Agendamento#

Aqui estão exemplos de como configurar todos os diferentes modos de agendamento:

{
  "amount": 1333.33,
  "description": "Teste",
  "schedule": {
    "type": "ÚNICO",
    "date": "2024-06-26"
  },
  "recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}

{
  "amount": 1333.33,
  "description": "Teste",
  "schedule": {
    "type": "DIÁRIO",
    "startDate": "2024-06-26",
    "occurrences": 2
  },
  "recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}

{
  "amount": 1333.33,
  "description": "Teste",
  "schedule": {
    "type": "SEMANAL",
    "startDate": "2024-06-26",
    "dayOfWeek": "SEGUNDA",
    "occurrences": 2
  },
  "recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}

{
  "amount": 1333.33,
  "description": "Teste",
  "schedule": {
    "type": "MENSAL",
    "startDate": "2024-06-26",
    "dayOfMonth": 1,
    "occurrences": 2
  },
  "recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}

{
  "amount": 1333.33,
  "description": "Teste",
  "schedule": {
    "type": "PERSONALIZADO",
    "dates": ["2024-06-26", "2024-06-28"]
  },
  "recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}

Usando uma UI personalizada#

Se você quiser usar sua própria UI para implementar o fluxo de Pagamento Agendado em vez de nosso App de Pagamentos:

1. Crie a solicitação de pagamento, incluindo um callbackUrl para seu site:

{
  "amount": 1333.33,
  "description": "Minha solicitação de pagamento 2",
  "schedule": {
    "type": "DIÁRIO",
    "startDate": "2024-06-26", // Data do primeiro pagamento
    "occurrences": 2 // Quantas vezes repetir
  },
  "recipientId": "376af75c-05fa-4a50-9347-d790a2d19940",
  "callbackUrls": {
    "success": "<seu-site>/success",
    "error": "<seu-site>/error"
  }
}

2. Crie um Intent de PagamentoAPI para essa Solicitação de Pagamento:

{
  "paymentRequestId": "4f05247c-d9ee-4d5b-a0ea-c1c52cc30f69",
  "connectorId": 600, // este é sandbox
  "parameters": {
    "cpf": "76109277673"
  }
}

3. Redirecione o usuário para o consentUrl na resposta, que o levará à tela de Iniciação de Pagamento Open Finance da instituição para autorizar o pagamento.

4. Você será redirecionado de volta para o callbackUrl correspondente (sucesso ou erro).

Testando no sandbox#

Você pode executar o fluxo de UI personalizada acima de ponta a ponta contra o banco sandbox.

1. Crie a Solicitação de Pagamento com isSandbox: true e um schedule — por exemplo ÚNICO com uma date futura.
2. Crie o Intent de Pagamento com o conector 600 e o CPF sandbox 76109277673, como no exemplo acima.
3. Abra o consentUrl, faça login com user-ok / password-ok e aprove.

Um amount de 404.04 faz com que o sandbox rejeite o pagamento quando você cria o Intent de Pagamento, então você pode testar esse caminho de erro também. Veja Testando pagamentos e boletos para os outros tipos de pagamento.