> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Cobrar con link de pago

> Envía un cobro por WhatsApp, email, portal de pagos o comparte un link directo.

## ¿Qué vas a lograr?

Al terminar esta guía podrás crear cobros y enviarlos a tus clientes por múltiples canales. Todo se hace con un solo endpoint (`POST /payments`), y el canal de entrega depende de los campos que envíes.

## Prerrequisitos

* Cuenta de OnePay creada y verificada
* Llaves de API generadas ([ver cómo](/docs/introduction/quick-start))
* Webhooks configurados ([ver cómo](/client/webhooks/index))

## ¿Qué canal necesitas?

| Quiero...                                 | Campo clave                     | ¿Qué sucede?                            |
| ----------------------------------------- | ------------------------------- | --------------------------------------- |
| Cobrar por **WhatsApp**                   | `phone`                         | El cliente recibe el link por WhatsApp  |
| Cobrar por **Email**                      | `email`                         | El cliente recibe el link por correo    |
| Crear un **link de pago** (monto fijo)    | `amount`                        | Se genera un link con monto predefinido |
| Crear un **link de pago** (monto abierto) | Sin `amount`                    | El cliente ingresa el monto             |
| Crear una **referencia** para el portal   | `reference`                     | El cliente busca su cobro en el portal  |
| **Todos los canales**                     | `phone` + `email` + `reference` | Se envía por todos los canales          |

<Note>
  Para ver ejemplos detallados de cada caso, consulta los [Casos de uso de cobros](/client/use-cases/payments).
</Note>

## Diagrama de flujo

```mermaid theme={null}
sequenceDiagram
    participant Tu App
    participant OnePay API
    participant Cliente
    participant Webhook

    Tu App->>OnePay API: POST /payments
    OnePay API-->>Tu App: payment_link
    OnePay API->>Cliente: WhatsApp / Email (si aplica)
    Cliente->>OnePay API: Abre link y paga
    OnePay API->>Webhook: payment.approved
    Webhook->>Tu App: Notificación de pago exitoso
```

## Paso a paso

<Steps>
  <Step title="Crear la solicitud de cobro">
    Usa `POST /payments` con los campos que necesites según el canal de entrega:

    <Tabs>
      <Tab title="WhatsApp">
        ```bash theme={null}
        curl https://api.onepay.la/v1/payments \
          -X POST \
          -H "Authorization: Bearer sk_test_xxx" \
          -H "Content-Type: application/json" \
          -H "x-idempotency: pago-whatsapp-001" \
          -d '{
            "amount": 150000,
            "title": "Factura #1234",
            "phone": "+573201112233",
            "currency": "COP"
          }'
        ```
      </Tab>

      <Tab title="Email">
        ```bash theme={null}
        curl https://api.onepay.la/v1/payments \
          -X POST \
          -H "Authorization: Bearer sk_test_xxx" \
          -H "Content-Type: application/json" \
          -H "x-idempotency: pago-email-001" \
          -d '{
            "amount": 150000,
            "title": "Factura #1234",
            "email": "cliente@ejemplo.com",
            "currency": "COP"
          }'
        ```
      </Tab>

      <Tab title="Link manual">
        ```bash theme={null}
        curl https://api.onepay.la/v1/payments \
          -X POST \
          -H "Authorization: Bearer sk_test_xxx" \
          -H "Content-Type: application/json" \
          -H "x-idempotency: pago-link-001" \
          -d '{
            "amount": 150000,
            "title": "Factura #1234",
            "currency": "COP"
          }'
        ```
      </Tab>

      <Tab title="Monto abierto">
        ```bash theme={null}
        curl https://api.onepay.la/v1/payments \
          -X POST \
          -H "Authorization: Bearer sk_test_xxx" \
          -H "Content-Type: application/json" \
          -H "x-idempotency: pago-abierto-001" \
          -d '{
            "title": "Donación Fundación ABC",
            "currency": "COP"
          }'
        ```
      </Tab>

      <Tab title="Portal de pagos">
        ```bash theme={null}
        curl https://api.onepay.la/v1/payments \
          -X POST \
          -H "Authorization: Bearer sk_test_xxx" \
          -H "Content-Type: application/json" \
          -H "x-idempotency: pago-portal-001" \
          -d '{
            "amount": 250000,
            "title": "Cuota Apartamento 401",
            "reference": "APTO-401-ENE-2025",
            "currency": "COP"
          }'
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Obtener el link de pago">
    En la respuesta recibirás un objeto con el `payment_link`:

    ```json theme={null}
    {
      "id": "9e5ccd4a-d2f0-49dd-87fc-a0da752bd166",
      "amount": 150000,
      "status": "pending",
      "payment_link": "https://pagos.onepay.la/payment/9e5ccd4a-d2f0-49dd-87fc-a0da752bd166",
      ...
    }
    ```

    * Si enviaste `phone`: el cliente recibe el link automáticamente por WhatsApp.
    * Si enviaste `email`: el cliente recibe el link por correo electrónico.
    * Si enviaste `reference`: el cliente puede buscar el cobro en el [portal de pagos](/docs/config/portal).
    * Si no enviaste ninguno: copia `payment_link` y compártelo manualmente.
  </Step>

  <Step title="El cliente completa el pago">
    Al abrir el link, el cliente verá una página de pago con los métodos habilitados. Si el link es de monto abierto, el cliente ingresará el monto antes de pagar.
  </Step>

  <Step title="Recibe la notificación por webhook">
    Cuando el pago se complete, recibirás un webhook `payment.approved`:

    ```json theme={null}
    {
      "payment": {
        "id": "9e5ccd4a-d2f0-49dd-87fc-a0da752bd166",
        "status": "succeeded",
        "amount": 150000
      },
      "event": {
        "type": "payment.approved",
        "timestamp": 1689262934,
        "environment": "test"
      }
    }
    ```
  </Step>
</Steps>

## Opciones adicionales

### Configurar métodos de pago

Usa el campo `allows` para controlar qué métodos de pago estarán disponibles en el link:

```json theme={null}
{
  "allows": {
    "cards": true,
    "pse": true,
    "accounts": false,
    "wallets": true,
    "breb": true
  }
}
```

### Establecer fecha de expiración

```json theme={null}
{
  "expiration_date": "2025-12-31 23:59:59"
}
```

### Redireccionar después del pago

```json theme={null}
{
  "redirect_url": "https://tuapp.com/pago-exitoso"
}
```

## Errores comunes

| Error                       | Causa                           | Solución                                       |
| --------------------------- | ------------------------------- | ---------------------------------------------- |
| `validation_error` (10001)  | Falta el campo `title`          | Asegúrate de enviar al menos el `title`        |
| `idempotency_error` (10003) | Falta el header `x-idempotency` | Agrega un token de idempotencia único          |
| Pago expirado               | El cliente no pagó a tiempo     | Crea un nuevo cobro o ajusta `expiration_date` |

## Siguiente paso

<CardGroup cols={2}>
  <Card title="Todos los casos de uso" icon="list" href="/client/use-cases/payments">
    Revisa la referencia completa de cada caso de uso de cobros.
  </Card>

  <Card title="Cobrar con débito directo" icon="credit-card" href="/guides/cobrar-debito">
    Debita automáticamente tarjetas o cuentas bancarias autorizadas.
  </Card>
</CardGroup>