# API · Crear cobros

> Crear cobros: POST /api/v1/collect/set/payments.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-10-20
- url: https://tilopay.com/developers/api/cobros-tarjetas-guardadas/set-payments

```http
POST /api/v1/collect/set/payments
```

## Qué hace [#que-hace]

Crear cobros.

## Autenticación [#autenticacion]

Servidor: `https://app.tilopay.com`. Requiere el token bearer del API en `Authorization: Bearer <token>` y la llave de la integración en el cuerpo (`key`).

[Obtener el token del API](/developers/api/autenticacion/token-api).

## Parámetros [#parametros]

<Param id="set-payments-parametro-key" name="key" type="string" required>
Llave de la integración.
</Param>

<Param id="set-payments-parametro-capture" name="capture" type="integer">
1 captura; 0 solo autoriza.
</Param>

<Param id="set-payments-parametro-reason" name="reason" type="string" required>
Concepto del cobro.
</Param>

<Param id="set-payments-parametro-users" name="users" type="array">
Afiliados: arreglo de `{id, amount, currency, date}`.
</Param>

<Param id="set-payments-parametro-groups" name="groups" type="array">
Grupos: arreglo de `{id, amount, currency, date}`; amount es el monto por afiliado.
</Param>

El campo `date` vacío indica cobro inmediato; `YYYY-MM-DD` programa el cobro. En `groups`, `amount` es el monto por afiliado.

## Ejemplo de request [#ejemplo-request]

`<api_key>` es el marcador de tu llave de integración.

```json
{
  "key": "<api_key>",
  "capture": 1,
  "reason": "Cobro mensualidad",
  "users": [
    {
      "id": "5",
      "amount": "500.00",
      "currency": "CRC",
      "date": ""
    },
    {
      "id": "32",
      "amount": "1000.00",
      "currency": "CRC",
      "date": "2024-06-20"
    },
    {
      "id": "25",
      "amount": "10.00",
      "currency": "USD",
      "date": "2024-06-20"
    }
  ],
  "groups": [
    {
      "id": "10",
      "amount": "25.00",
      "currency": "USD",
      "date": ""
    }
  ]
}
```

## Respuesta [#respuesta]

batch es el code del lote para get/massive/detail. date vacío = cobro inmediato; YYYY-MM-DD = programado. Repetir esta operación genera otro cobro.

<Param id="set-payments-respuesta-status" name="status" type="unknown">
`status`.
</Param>

<Param id="set-payments-respuesta-errors" name="errors" type="unknown">
`errors`.
</Param>

<Param id="set-payments-respuesta-users_errors" name="users_errors" type="string | array">
`users_errors`.
</Param>

<Param id="set-payments-respuesta-groups_errors" name="groups_errors" type="string | array">
`groups_errors`.
</Param>

<Param id="set-payments-respuesta-programeds" name="programeds" type="object">
`programeds`.
</Param>

<Param id="set-payments-respuesta-batch" name="batch" type="unknown">
`batch`.
</Param>

```json
{
  "status": 200,
  "errors": "",
  "users_errors": "",
  "groups_errors": "",
  "programeds": {
    "users": [
      "5",
      "32",
      "25"
    ],
    "groups": [
      "10"
    ]
  },
  "batch": "SGZqbHlHalJiWmRNSEszd3ZEZHo4dz09"
}
```

```schema
{
  "type": "object",
  "properties": {
    "status": {
      "type": "integer"
    },
    "errors": {
      "type": "string"
    },
    "users_errors": {
      "type": [
        "string",
        "array"
      ],
      "items": {}
    },
    "groups_errors": {
      "type": [
        "string",
        "array"
      ],
      "items": {}
    },
    "programeds": {
      "type": "object",
      "properties": {
        "users": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "groups": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "batch": {
      "type": "string"
    }
  }
}
```

## Respuesta de error [#respuestas-de-error]

HTTP 400:

```json
{
  "status": "400",
  "errors": "Please verify the data sent",
  "users_errors": [
    {
      "id": "32",
      "amount": "1000.00",
      "currency": "CRC",
      "date": "invalidDate"
    }
  ],
  "groups_errors": [
    {
      "id": "10",
      "amount": "25.00",
      "currency": null,
      "date": null
    }
  ]
}
```

[Reintentos seguros](/developers/reintentos-seguros).