Pagamentos Agendados (Pix Agendado)

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

• SINGLE: Agendar um pagamento para ocorrer em um momento específico no futuro.
• DAILY: Agendar vários pagamentos para ocorrer todos os dias, a partir de uma data específica.
• WEEKLY: Agendar vários pagamentos para ocorrer todas as semanas, a partir de uma data específica.
• MONTHLY: Agendar vários pagamentos para ocorrer todos os meses, a partir de uma data específica.
• CUSTOM: Agendar vários pagamentos para ocorrer em datas específicas no futuro.

Agendando um pagamento#

1. Crie uma Payment Request incluindo um objeto schedule:

{
  "amount": 1333.33, // O valor a ser pago a cada dia/semana/mês/agendamento personalizado
  "description": "Meu pedido de pagamento 2",
  "schedule": {
    "type": "DAILY",
    "startDate": "2024-06-26", // Data do primeiro pagamento
    "occurrences": 2 // Quantas vezes repetir
  },
  "recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}

2. Autorize o Payment Request com nosso Payments App (visitando o paymentUrl na resposta).

3. Depois que o usuário escolher a instituição para pagar, inserir seu CPF/CNPJ e clicar em Pagar, um Payment Intent 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 Payment Intent mudará o status para PAYMENT_COMPLETED. Isso aciona o webhook payment_intent/completed. Agora, um ou mais Scheduled Payments (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 Scheduled Payments:

{
  "total": 2,
  "totalPages": 1,
  "page": 1,
  "results": [
    {
      "id": "9f12b911-a064-4310-89f2-8d411e10b160",
      "status": "SCHEDULED",
      "scheduledDate": "2024-06-26",
      "description": "Meu pedido de pagamento 1/2"
    },
    {
      "id": "1f1f04e8-0bcf-4baf-bbbd-8bedf8478503",
      "status": "SCHEDULED",
      "scheduledDate": "2024-06-27",
      "description": "Meu pedido 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 Scheduled Payment para COMPLETED ou ERROR em caso de falha. Isso aciona o webhook scheduled_payment/completed ou scheduled_payment/error.

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

8. Depois que todos os Scheduled Payments estiverem COMPLETED, o Payment Request mudará o status para COMPLETED.

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

Depois que o usuário autorizou um Scheduled Payment, você não pode adicionar ou editar os Schedules resultantes. No entanto, você pode excluir um agendamento específico ou cancelar o pagamento inteiro.

O usuário autorizador também pode cancelar todos os agendamentos 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": "SINGLE",
    "date": "2024-06-26"
  },
  "recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}

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

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

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

{
  "amount": 1333.33,
  "description": "Teste",
  "schedule": {
    "type": "CUSTOM",
    "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 Payments App:

1. Crie o pedido de pagamento, incluindo um callbackUrl para seu site:

{
  "amount": 1333.33,
  "description": "Meu pedido de pagamento 2",
  "schedule": {
    "type": "DAILY",
    "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 Payment Intent para esse Payment Request:

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

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

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