# Donaciones

> **En piloto.** Las donaciones están detrás de una bandera y todavía no están activas para todos los comercios. Si no están activas, crear un enlace con `donacion` responde `400` con `{ "error": "donacion_no_disponible" }` y no se crea nada.

Un enlace de pago puede incluir una **donación a una fundación**. Tu cliente paga **un solo débito** (lo tuyo más la donación) y nosotros le transferimos la donación completa a la fundación:

- **La donación no paga comisión.** La comisión de ePlaza se calcula sobre el monto del enlace **menos** la donación.
- **La donación no es tuya.** No entra en lo que te acreditamos ni en tu saldo: sale aparte, hacia la cuenta de la fundación, tengas o no la liquidación inmediata activa.

## Antes de empezar: la fundación

Las fundaciones las registra **ePlaza**, con su cuenta bancaria, y las habilita para tu cuenta. Escríbenos para pedirlo: te damos el **código** de la fundación (por ejemplo, `fundacion-ejemplo`). Tú nunca mandas ni ves la cuenta de la fundación: sólo su código y su nombre.

Así, aunque alguien llegara a tener tu llave, no podría mandar dinero a una cuenta suya como si fuera una donación.

## Crear un enlace con donación

Agrega `donacion` al crear el enlace (`POST /switch/v1/links`). `monto` es **el total que paga tu cliente**, con la donación incluida:

```bash
curl -s https://eplaza-qa-pay.pagaconquickpay.com/switch/v1/links \
  -H "x-switch-key: $QP_KEY" -H "content-type: application/json" \
  -d '{
    "monto": 141968.32,
    "concepto": "Entradas + donación",
    "donacion": { "donataria": "fundacion-ejemplo", "monto": 8873.02 }
  }'
```

| Campo | Qué es |
|---|---|
| `donacion.donataria` | El código de la fundación que te dimos |
| `donacion.monto` | Bs que van a la fundación: mayor que 0, con 2 decimales como máximo y **menor** que el `monto` del enlace |

La respuesta de crear trae `donacion` con la fundación y su estado (ver abajo). Si repites la creación con la misma `idempotency_key`, recibes el mismo enlace con su `donacion`; si la repites con **otra** donación (u otra fundación, o sin ella), responde `409` `idempotency_key_reutilizada` y no se crea nada. Todo queda fijo al crear: para cambiar la donación, se cancela el enlace y se crea otro.

Un enlace con donación:

- se cobra sólo en bolívares (`moneda` `VES`);
- **no lleva `split`** ([pago dividido](/developers/pago-dividido)): si mandas los dos, responde `400` `donacion_invalida`;
- no ofrece el pago con tarjeta en la página de pago (sólo débito inmediato);
- no se puede devolver desde el portal.

| HTTP | `error` | Cuándo |
|---|---|---|
| 400 | `donacion_no_disponible` | Las donaciones no están activas, esa fundación no está habilitada para tu cuenta (o la desactivamos), o la comisión de tus cobros no se descuenta del cobro: la donación sólo está disponible con la comisión descontada de lo que te liquidamos. `detail` dice cuál |
| 400 | `donacion_invalida` | Falta `donataria` o `monto`, el monto no es menor que el del enlace, trae otro campo, la moneda no es `VES` o el enlace también trae `split`. `detail` dice cuál |
| 422 | `donacion_excede_neto` | Después de la donación y la comisión no te queda nada de ese cobro |
| 503 | `donacion_no_disponible_ahora` | No pudimos revisar la fundación en ese momento. No se creó nada: intenta de nuevo en unos minutos |

## Cuánto recibe cada quien

Con una comisión del 1 %, entradas por Bs 133.095,30 y una donación de Bs 8.873,02 (tu cliente paga Bs 141.968,32):

| Quién | Cuánto |
|---|---|
| La fundación | Bs 8.873,02 (la donación completa) |
| Comisión ePlaza | Bs 1.330,95 (1 % de Bs 133.095,30) |
| Tú | Bs 131.764,35 |

Si tu cliente agrega [propina](/developers/propinas), la propina es tuya y paga comisión como siempre.

Siempre suma exacto: lo tuyo + la comisión + la donación = lo que pagó tu cliente, al céntimo.

## Cuándo le llega a la fundación

- **Sólo cuando el banco confirma** que el pago de tu cliente entró, igual que tu liquidación. Mientras tanto, la donación está `pendiente`.
- **Una sola vez:** la transferencia a la fundación tiene su propio identificador y no se repite.
- **Se revisa otra vez antes de pagar:** que la fundación siga activa y habilitada para tu cuenta, con la misma cuenta bancaria que tenía al crear el enlace, y que el pago de tu cliente no se haya devuelto. Si algo no cuadra, la donación queda **en revisión** y no se paga sola.
- **Si el banco de la fundación la rechaza después** (por ejemplo, porque la cuenta no corresponde al RIF), o si el pago de tu cliente se revierte después de transferida la donación, la donación pasa de `pagada` a `en_revision` y no se reenvía sola.
- **En revisión:** una persona de nuestro equipo la resuelve con el banco: la transfiere, la da por transferida con la referencia bancaria, sólo si aparece en nuestro estado de cuenta por el monto de la donación (esa pasa a ser su `referencia_bancaria`) o la cierra sin transferir (con una nota). Si el pago de tu cliente se revirtió después de transferida la donación, el dinero ya salió hacia la fundación: la revisión se cierra con una nota, la donación queda `pagada` y lo resolvemos contigo. Una donación que una persona dio por cerrada no vuelve a revisión sola. Si una transferencia no tiene una respuesta clara del banco, no se reintenta sola.

## Ver la donación

`GET /switch/v1/links/:id` de un enlace con donación trae, además de lo de siempre:

```json
{
  "donacion": {
    "donataria": "fundacion-ejemplo",
    "nombre": "Fundación Ejemplo",
    "monto": 8873.02,
    "estado": "pagada",
    "referencia_bancaria": "70000001"
  }
}
```

`estado` es `pendiente` (todavía no se le transfirió), `pagada` (el banco aceptó la transferencia a la fundación; si la rechaza después, pasa a `en_revision`), `en_revision` (la está revisando una persona) o `descartada` (se cerró sin transferir). `referencia_bancaria` es la de la transferencia a la fundación, sólo cuando está `pagada`.

Los avisos [`link.pagado` y `link.acreditado`](/developers/webhooks-referencia) traen el mismo `donacion`. En `link.pagado` normalmente llega `pendiente`: la transferencia sale cuando el banco confirma el pago. En `link.acreditado`, `monto_acreditado` es sólo lo tuyo (nunca incluye la donación).

## Reintegros

Si la donación ya se le transfirió (o se le está transfiriendo) a la fundación, `POST /switch/v1/reintegro` de ese pago responde **409 `cobro_con_donacion_pagada`**: devolverle todo a tu cliente sería pagar dos veces. Escríbenos y lo resolvemos. Si el reintegro se hace antes, la donación se detiene y queda en revisión.

## En modo prueba

Con una `sk_test_` la donación se simula igual que el resto del cobro: no se transfiere nada y la comisión se calcula igual que en producción. La fundación también tiene que estar habilitada para tu cuenta, así ves el mismo rechazo que verás en producción. Si cierras el pago con [`POST /links/:id/simular`](/developers/datos-de-prueba), la donación queda `pagada` con referencia `SIMULADO`.
