Desde tu sistema · Donaciones (piloto)
Docs · Desde tu sistema Descargar .md

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 }
  }'
CampoQué es
donacion.donatariaEl código de la fundación que te dimos
donacion.montoBs 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): 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.
HTTPerrorCuándo
400donacion_no_disponibleLas 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
400donacion_invalidaFalta 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
422donacion_excede_netoDespués de la donación y la comisión no te queda nada de ese cobro
503donacion_no_disponible_ahoraNo 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énCuánto
La fundaciónBs 8.873,02 (la donación completa)
Comisión ePlazaBs 1.330,95 (1 % de Bs 133.095,30)
TúBs 131.764,35

Si tu cliente agrega propina, 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 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, la donación queda pagada con referencia SIMULADO.