# 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](/reference/payment-request-create) incluindo um objeto `schedule`:

```json title="POST /payments/requests"
{
  "amount": 1333.33, // O valor a ser pago a cada dia/semana/mês/agendamento personalizado
  "description": "Minha solicitação 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 a 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](/reference/payment-schedules-list):

```json title="GET /payment-requests/{id}/schedules"
{
  "total": 2,
  "totalPages": 1,
  "page": 1,
  "results": [
    {
      "id": "9f12b911-a064-4310-89f2-8d411e10b160",
      "status": "SCHEDULED",
      "scheduledDate": "2024-06-26",
      "description": "Minha solicitação de pagamento 1/2"
    },
    {
      "id": "1f1f04e8-0bcf-4baf-bbbd-8bedf8478503",
      "status": "SCHEDULED",
      "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 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. Após todos os Scheduled Payments serem COMPLETED, a 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:

```json title="SINGLE"
{
  "amount": 1333.33,
  "description": "Teste",
  "schedule": {
    "type": "SINGLE",
    "date": "2024-06-26"
  },
  "recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}
```

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

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

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

```json title="CUSTOM"
{
  "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 a solicitação de pagamento, incluindo um `callbackUrl` para seu site:

```json title="POST /payments/requests"
{
  "amount": 1333.33,
  "description": "Minha solicitação 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](/reference/payment-intent-create) para essa Payment Request:

```json title="POST /payments/intents"
{
  "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 Open Finance da instituição para autorizar o pagamento.

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