> ## Documentation Index
> Fetch the complete documentation index at: https://developers.paycode.com.mx/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagos recurrentes

Te permite programar cobros automáticos a tus clientes en fechas específicas, sin necesidad de ejecutarlos manualmente cada vez.

**Métodos de pago compatibles:**

<Badge color="blue" size="lg">Tarjeta de débito</Badge> <Badge color="blue" size="lg">Cuentas bancarias CLABE</Badge>

**Frecuencias de cobro disponibles:**

| Frecuencia    | Descripción                                                       |
| ------------- | ----------------------------------------------------------------- |
| Pago único    | Se cobra una sola vez en la fecha definida                        |
| Semanal       | Se cobra cada semana en el día configurado                        |
| Quincenal     | Se cobra dos veces al mes                                         |
| Mensual       | Se cobra una vez al mes en el día configurado                     |
| Personalizado | El intervalo lo define el integrador, hasta un máximo de 180 días |

<Note>
  El monto mínimo para crear un pago recurrente es de \$50.00 MXN. El cliente debe verificar que los datos de pago sean correctos y autorizar los cobros antes de programarlos. Una vez configurados el sistema los ejecutará automáticamente en las fechas definidas.
</Note>

***

## Paso 1. Autenticación

Para usar el módulo de pagos recurrentes necesitas un `access_token`. Este token se obtiene enviando tu API Key al endpoint de autenticación y debe incluirse en todas las llamadas siguientes.

**Método:** `POST` **Endpoint:** `/api/v3/auth/login`

**Header requerido:**

| Header          | Valor      |
| --------------- | ---------- |
| `Authorization` | Tu API Key |

**Flujo de autenticación:**

<Steps>
  <Step title="Obtén tu API Key con el equipo de desarrollo de PayCode" />

  <Step title="Envía una solicitud POST al endpoint de autenticación incluyendo el header Authorization con tu API Key" />

  <Step title="Guarda el access_token que recibes en la respuesta" />

  <Step title="Incluye ese token en todas las llamadas siguientes con el formato Bearer {token}" />
</Steps>

<Warning>
  Tu API Key es confidencial. Guárdala en tu servidor y nunca en el código visible al usuario.
</Warning>

<Warning>
  El `access_token` expira. Asegúrate de solicitar uno nuevo cuando eso ocurra para que tu integración no se interrumpa.
</Warning>

**Ejemplo de respuesta 200 OK:**

```json theme={null}
{
  "success": true,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_at": "2026-04-06 15:07:24"
}
```

***

## Paso 2: Crear pago recurrente

Crea un nuevo pago recurrente. El endpoint es el mismo para todos los tipos de frecuencia — lo que cambia es el valor del campo `periodicity` y los campos adicionales requeridos según el tipo.

**Método:** `POST` **Endpoint:** `/api/v3/schedule_payments`

**Header requerido:** `Authorization: Bearer {token}`

**Campos del request:**

Los siguientes campos aplican a todos los tipos de pagos recurrentes:

| Campo                   | Tipo    | Requerido               | Descripción                                             |
| ----------------------- | ------- | ----------------------- | ------------------------------------------------------- |
| `amount`                | float   | Sí                      | Monto a cobrar. Mínimo \$50.00 MXN                      |
| `first_name`            | string  | Sí                      | Nombre del cliente                                      |
| `paternal_surname`      | string  | Sí                      | Apellido paterno del cliente                            |
| `maternal_surname`      | string  | Sí                      | Apellido materno del cliente                            |
| `email`                 | string  | Sí                      | Correo electrónico del cliente                          |
| `clabe`                 | string  | No                      | CLABE interbancaria del cliente (18 dígitos)            |
| `date_start_payments`   | string  | Sí                      | Fecha de inicio de cobros en formato `YYYY-MM-DD`       |
| `date_end_payments`     | string  | Según tipo              | Fecha de término de cobros en formato `YYYY-MM-DD`      |
| `periodicity`           | string  | Sí                      | Tipo de frecuencia (ver tabla en la introducción)       |
| `payment_day`           | integer | Según tipo              | Día de cobro — su significado varía según la frecuencia |
| `payment_days_interval` | string  | Solo para personalizado | Intervalo en días entre cobros                          |

<Note>
  `date_start_payments` no puede ser anterior a la fecha actual ni exceder 30 días a partir de ella.
</Note>

<Note>
  Si `date_start_payments` es el mismo día del registro, el cobro se ejecuta 24 horas después de la creación.
</Note>

### 2.1 Pago único `periodicity: 1`

<Note>
  Aunque este módulo está diseñado para pagos recurrentes, también permite realizar un cobro que se ejecuta una sola vez. No requiere `date_end_payments` ni `payment_day`.
</Note>

**Ejemplo de request:**

```json theme={null}
{
  "amount": 50,
  "clabe": "012180015520945151",
  "date_start_payments": "2026-05-01",
  "first_name": "María",
  "paternal_surname": "García",
  "maternal_surname": "López",
  "email": "maria@ejemplo.com",
  "periodicity": "1"
}
```

**Ejemplo de respuesta 201 Created:**

```json theme={null}
{
  "success": true,
  "data": {
    "id": 375991,
    "amount": "50.00",
    "date_start": "01/05/2026",
    "next_payment_date": "01/05/2026",
    "payment_day": 0,
    "periodicity": "1",
    "customer": {
      "id": 337327,
      "first_name": "María",
      "paternal_surname": "García",
      "maternal_surname": "López",
      "email": "maria@ejemplo.com",
      "alias": "000000000000337327"
    },
    "created_at": "06/04/2026 02:28:20 PM"
  },
  "msg": ""
}
```

### 2.2 Pago semanal `periodicity: 2`

Cobros automáticos cada semana en el día definido. Requiere `date_end_payments` y `payment_day`.

**Campo** `payment_day `**día de la semana en el que se ejecutará el cobro:**

| Valor | Día       |
| ----- | --------- |
| 1     | Lunes     |
| 2     | Martes    |
| 3     | Miércoles |
| 4     | Jueves    |
| 5     | Viernes   |

**Ejemplo de request:**

```json theme={null}
{
  "amount": 50,
  "clabe": "012180015520945151",
  "date_start_payments": "2026-05-01",
  "date_end_payments": "2026-05-11",
  "first_name": "María",
  "paternal_surname": "García",
  "maternal_surname": "López",
  "email": "maria@ejemplo.com",
  "payment_day": 2,
  "periodicity": 2
}
```

### 2.3 Pago quincenal `periodicity: 3`

Cobros automáticos dos veces al mes. Requiere `date_end_payments` y `payment_day`.

**Ejemplo de request:**

```json theme={null}
{
  "amount": 50,
  "clabe": "012180015520945151",
  "date_start_payments": "2026-05-01",
  "date_end_payments": "2026-05-11",
  "first_name": "María",
  "paternal_surname": "García",
  "maternal_surname": "López",
  "email": "maria@ejemplo.com",
  "payment_day": 14,
  "periodicity": 3
}
```

### 2.4 Pago mensual `periodicity: 4`

Cobros automáticos una vez al mes en el día configurado. Requiere `date_end_payments` y `payment_day`.

El campo `payment_day` define el día del mes en el que se ejecutará el cobro. Los valores permitidos son del `1` al `30`.

<Note>
  Para mantener una recurrencia consistente el sistema considera todos los meses como si tuvieran 30 días. Si un mes tiene 31 días el cobro se ejecuta el día 30. En febrero el día 30 corresponde al último día del mes.
</Note>

**Ejemplo de request:**

```json theme={null}
{
  "amount": 50,
  "clabe": "012180015520945151",
  "date_start_payments": "2026-05-01",
  "date_end_payments": "2026-05-11",
  "first_name": "María",
  "paternal_surname": "García",
  "maternal_surname": "López",
  "email": "maria@ejemplo.com",
  "payment_day": 30,
  "periodicity": 4
}
```

### 2.5 Pago personalizado `periodicity: 5`

Cobros automáticos con un intervalo fijo en días definido por el integrador. En lugar de `payment_day` se usa `payment_days_interval`.

**Campo `payment_days_interval`:** valores permitidos del `1` al `180`, define el número de días entre cada cobro contado a partir de `date_start_payments`.

<Note>
  Los cobros se calculan de forma incremental a partir de `date_start_payments` usando el valor definido en `payment_days_interval`. Fórmula: `siguiente_ejecución = date_start_payments + (n × payment_days_interval)` donde **n** representa el número de ejecución (0, 1, 2…).
</Note>

<Note>
  El cálculo se realiza usando días naturales consecutivos. A diferencia del pago mensual esta periodicidad no aplica la normalización del mes comercial de 30 días.
</Note>

**Ejemplo:** si `date_start_payments` es `2026-01-01` y `payment_days_interval` es `60`, los cobros ocurrirán el 2026-01-01, 2026-03-02, 2026-05-01 y así sucesivamente hasta `date_end_payments`.

<Warning>
  Si `date_start_payments` coincide con la fecha de creación del pago recurrente, el primer cobro se ejecutará en la siguiente fecha calculada según el intervalo configurado.
</Warning>

**Ejemplo de request:**

```json theme={null}
{
  "amount": 50.0,
  "clabe": "012180015520945151",
  "date_start_payments": "2026-04-27",
  "date_end_payments": "2026-12-07",
  "first_name": "María",
  "paternal_surname": "García",
  "maternal_surname": "López",
  "email": "maria@ejemplo.com",
  "periodicity": "5",
  "payment_days_interval": "180"
}
```

***

## Paso 3: Listar pagos recurrentes

Obtiene la lista de todos los pagos recurrentes registrados, paginados en bloques de 25 registros por página.

**Método:** `GET` **Endpoint:** `/api/v3/schedule_payments`

**Header requerido:** `Authorization: Bearer {token}`

**Ejemplo de respuesta 200 OK:**

```json theme={null}
{
  "data": [
    {
      "id": 516080,
      "amount": 50.21,
      "next_payment_date": "15/04/2026",
      "periodicity": 1,
      "customer": {
        "id": 438162,
        "first_name": "Raúl",
        "paternal_surname": "Juárez",
        "maternal_surname": "Monroy",
        "email": "raul@gmail.com",
        "alias": "000000000000438154"
      },
      "created_at": "27/05/2026 10:05:34 AM"
    }
  ],
  "success": true,
  "links": {
    "first": "https://plataforma.paycode.com.mx/api/v3/schedule_payments?page=1",
    "last": "https://plataforma.paycode.com.mx/api/v3/schedule_payments?page=61",
    "prev": null,
    "next": "https://plataforma.paycode.com.mx/api/v3/schedule_payments?page=2"
  },
  "meta": {
    "current_page": 1,
    "last_page": 61,
    "per_page": 25,
    "total": 1524
  }
}
```

### Obtener detalle de un pago recurrente

Obtiene toda la información de un pago recurrente específico.

**Método:** `GET` **Endpoint:** `/api/v3/schedule_payments/{id}`

<Note>
  Reemplaza `{id}` con el identificador del pago recurrente.
</Note>

**Ejemplo de respuesta 200 OK:**

```json theme={null}
{
  "success": true,
  "data": {
    "id": 375991,
    "amount": 50,
    "date_start": "01/05/2026",
    "next_payment_date": "01/05/2026",
    "payment_day": "0",
    "periodicity": 1,
    "customer": {
      "id": 337327,
      "first_name": "Saige",
      "paternal_surname": "Wintheiser",
      "maternal_surname": "Hand",
      "email": "test@hotmail.com",
      "alias": "000000000000337327"
    },
    "created_at": "06/04/2026 02:28:20 PM"
  },
  "msg": ""
}
```

***

## Paso 4: Editar pago recurrente

Actualiza los parámetros de un pago recurrente existente. Solo se modifican los campos incluidos en el request.

**Método:** `PUT` **Endpoint:** `/api/v3/schedule_payments/edit/{id}`

**Header requerido:** `Authorization: Bearer {token}`

**Campos editables:**

| Campo                   | Tipo   | Descripción                                                  |
| ----------------------- | ------ | ------------------------------------------------------------ |
| `date_end_payments`     | string | Nueva fecha de término en formato `YYYY-MM-DD`               |
| `amount`                | float  | Nuevo monto a cobrar. Mínimo \$50.00 MXN                     |
| `periodicity`           | string | Nueva frecuencia de cobro                                    |
| `payment_day`           | string | Nuevo día de cobro                                           |
| `payment_days_interval` | string | Nuevo intervalo en días (solo para frecuencia personalizada) |

**Ejemplo de request:**

```json theme={null}
{
  "date_end_payments": "2026-05-10",
  "amount": 50.0,
  "periodicity": "2",
  "payment_day": "3",
  "payment_days_interval": "1"
}
```

**Ejemplo de respuesta 201 Created:**

```json theme={null}
{
  "success": true,
  "data": {
    "id": 375992,
    "amount": 50,
    "date_start": "01/05/2026",
    "date_expired": "10/05/2026",
    "next_payment_date": "07/04/2026",
    "payment_day": "3",
    "payment_days_interval": "1",
    "periodicity": "2",
    "customer": {
      "id": 337328,
      "first_name": "Nina",
      "paternal_surname": "Krajcik",
      "maternal_surname": "Brown",
      "email": "test@yahoo.com",
      "alias": "000000000000337328"
    },
    "created_at": "06/04/2026 02:30:42 PM"
  },
  "msg": ""
}
```

***

## Paso 5: Cancelar pago recurrente

**Método:** `DELETE` **Endpoint:** `/api/v3/schedule_payments/cancel/{id}`

**Header requerido:** `Authorization: Bearer {token}`

<Danger>
  Una vez cancelado el pago recurrente no puede reactivarse ni procesarse.
</Danger>

**Parámetros:**

| Parámetro | Tipo   | Requerido | Descripción                                        |
| --------- | ------ | --------- | -------------------------------------------------- |
| `id`      | string | Sí        | Identificador único del pago recurrente a cancelar |

<Warning>
  El `id` debe corresponder a un pago recurrente existente. No es posible cancelar un pago que ya haya sido procesado.
</Warning>

**Ejemplo de respuesta 200 OK:**

```json theme={null}
{
  "success": true,
  "data": [],
  "msg": ""
}
```