> ## 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.

# Generar link de domiciliación

> Genera un link firmado para que un cliente suscriba su método de pago al débito automático de facturas.

Genera una URL firmada con tiempo de expiración que redirige al checkout de domiciliación. El cliente podrá registrar su método de pago (tarjeta o cuenta) para el cobro automático de sus facturas.

<Warning>
  La compañía debe tener al menos un servicio de facturación (`BillService`) habilitado para poder generar el link.
</Warning>

***

### Body

<ParamField body="reference" type="string" required>
  Referencia de la factura o servicio a domiciliar. Mínimo 1 carácter, máximo 60.
</ParamField>

<ParamField body="phone" type="string" placeholder="+573001234567">
  Número de teléfono del cliente en formato E.164. Si se envía, el checkout lo pre-llenará.
</ParamField>

<ParamField body="approx_amount" type="number">
  Monto aproximado del cobro (en pesos). Se muestra al cliente como referencia. Mínimo `0`.
</ParamField>

<ParamField body="expiration_minutes" type="integer">
  Minutos de validez del link. Mínimo `60`, máximo `43200` (30 días). Por defecto `4320` (3 días).
</ParamField>

### Ejemplos de uso

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://api.onepay.la/v1/utilities/direct-debits/link \
      -X POST \
      -H "Authorization: Bearer sk_test_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "reference": "3167591038",
        "phone": "+573001234567",
        "approx_amount": 45000,
        "expiration_minutes": 4320
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```ts theme={null}
    const response = await fetch('https://api.onepay.la/v1/utilities/direct-debits/link', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_test_xxx',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        reference: '3167591038',
        phone: '+573001234567',
        approx_amount: 45000,
        expiration_minutes: 4320,
      }),
    });

    const data = await response.json();
    console.log(data.url);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post(
        'https://api.onepay.la/v1/utilities/direct-debits/link',
        headers={
            'Authorization': 'Bearer sk_test_xxx',
            'Content-Type': 'application/json',
        },
        json={
            'reference': '3167591038',
            'phone': '+573001234567',
            'approx_amount': 45000,
            'expiration_minutes': 4320,
        },
    )

    data = response.json()
    print(data['url'])
    ```
  </Tab>
</Tabs>

### Response

<ResponseField name="url" type="string">
  URL corta que redirige al checkout de domiciliación. Este link es público y puede compartirse con el cliente.
</ResponseField>

<ResponseField name="reference" type="string">
  La referencia enviada en el request.
</ResponseField>

<ResponseField name="expires_at" type="string">
  Fecha y hora de expiración del link en formato ISO 8601.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "url": "https://onepay.la/s/abc123",
    "reference": "3167591038",
    "expires_at": "2026-02-16T15:55:00.000000-05:00"
  }
  ```
</ResponseExample>

***

## Notas importantes

* El link generado es una **URL firmada** con expiración. Una vez vencido, el cliente verá un error 403.
* Se genera automáticamente una **URL corta** para facilitar el envío por WhatsApp o SMS.
* El cliente podrá registrar una **tarjeta** o **cuenta bancaria** como método de pago automático.