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

```json title="POST /payments/requests"
{
  "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 Agendados](/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": "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:

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

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

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

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

```json title="PERSONALIZADO"
{
  "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:

```json title="POST /payments/requests"
{
  "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 Pagamento](/reference/payment-intent-create) para essa Solicitação de Pagamento:

```json title="POST /payments/intents"
{
  "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.

<Callout variant="info" title="Requer que pagamentos agendados estejam habilitados em sua conta">
O PIX agendado usa seu próprio contrato de iniciação de pagamento, portanto, a iniciação de pagamento para pagamentos agendados deve estar habilitada em sua conta — no sandbox também. Sem isso, criar o Intent de Pagamento (`POST /payments/intents`) para uma Solicitação de Pagamento com um `schedule` retorna `403` com o código `PAYMENT_INITIATION_NOT_ALLOWED`, mesmo quando a solicitação tem `isSandbox: true`. Entre em contato com o suporte da Pluggy para habilitá-lo.
</Callout>

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.

<Callout variant="warning" title="O sandbox não espera pela data agendada">
O sandbox liquida uma solicitação de pagamento agendado **no momento do consentimento**, como um pagamento único datado de hoje, em vez de criar um pagamento por ocorrência e executar cada um em sua data. Use-o para verificar se sua integração cria a solicitação, envia o usuário pelo consentimento e lida com o webhook `scheduled_payment/completed`. Como as ocorrências individuais nunca são agendadas, o sandbox não envia `payment_intent/completed`, `scheduled_payment/created` ou `scheduled_payment/all_created`, e a Solicitação de Pagamento permanece em `AGENDADO` em vez de ser movida para `COMPLETO`. Valide essas etapas contra uma instituição real.
</Callout>

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](/docs/guides/sandbox#testing-payments-and-boletos) para os outros tipos de pagamento.