@pandait.tech/payment-bank-transfer
v3.0.0
Published
Transferencia bancaria con comprobante para panda-commerce-kit. Implementa PaymentMethod sin red: datos de cuentas + validación de comprobante + aprobación manual del admin.
Maintainers
Readme
@pandait.tech/payment-bank-transfer
Adapter de transferencia bancaria con comprobante para panda-commerce-kit. Implementa
PaymentMethod sin red: no llama a ninguna API externa, no recibe webhooks de un banco, no sube ni
almacena el archivo del comprobante (solo su metadata).
Trabaja sobre el pedido del modelo común (model.Order de @pandait.tech/commerce-core,
docs/SCHEMA.md §2): el pedido se identifica por code y espera el comprobante en pending.
Canales
Un solo método de pago ("transferencia"), con canales habilitables por cliente en
config.channels. Cada canal es de dos tipos:
bank— una cuenta bancaria (account: BankAccount).wallet-qr— el QR estático del comercio para DeUna o peiGo (wallet,qrImageUrl,holder,phone?). Ninguno de los dos tiene aquí una API de comercio: el QR es fijo y no lleva monto ni orden, por eso el comprobante sigue siendo obligatorio.
Un canal se apaga con enabled: false sin borrarlo de la configuración. Los id deben ser únicos:
toBankTransferPaymentMethod lanza al construirse si hay dos canales con el mismo id.
Flujo
prepare(order)— devuelve los canales habilitados (config.channelsfiltrados porenabled !== false), la referencia (order.code), el monto y unwhatsappUrlopcional para que el cliente avise por WhatsApp. La orden espera enpending. Si no queda ningún canal habilitado, lanza un error en vez de devolver un checkout sin formas de pagar.- El cliente transfiere y la app (fuera de este package) sube el archivo del comprobante a
almacenamiento y llama a
submitProof(input)con su metadata (channelId,url,mimeType,sizeBytes,referenceNumber,declaredAmount).submitProofbusca la orden y valida si la referencia ya se usó (víaports), correvalidateProof— puro y síncrono — y, solo si es válido, invocaports.onProofAccepted. - Un admin revisa el comprobante y aprueba o rechaza. Esa decisión llega como
handleWebhook({ orderRef, decision })— aquí "el webhook" es la decisión del admin, no un banco. confirm(ref)consultaports.getDecisionpara el estado de pago: sin decisión →pending, nuncapaidsin revisión explícita.
Contrato de handleWebhook
En todos los adapters del kit, { handled: true, orderId } significa "esta orden se pagó,
finalízala". Un rechazo no puede devolver eso, pero tampoco puede volverse indistinguible de un
payload corrupto devolviendo { handled: false } a secas. Contrato exacto:
| Payload | Resultado |
|---|---|
| { orderRef, decision: "approved" } | { handled: true, orderId, decision: "approved" } |
| { orderRef, decision: "rejected" } | { handled: false, orderId, decision: "rejected" } ← rechazo nombrado, no silencioso |
| null / sin orderRef / decision desconocida | { handled: false } |
handleWebhook no es idempotente y no pretende serlo: la misma decisión aprobada dos veces
devuelve {handled:true, ...} las dos veces. La deduplicación es responsabilidad del finalizador,
que debe descartar transiciones ya aplicadas contra el estado durable de la orden antes de cobrar,
enviar el correo o disparar fulfillment (referencia viva en el repo: payment-nuvei/src/handlers/webhook.ts).
validateProof — los 5 rechazos
Función pura y síncrona (las búsquedas las hace el llamador vía ports, así la puerta se prueba
sin mocks async):
| reason | Cuándo |
|---|---|
| order-not-found | La orden no existe |
| order-not-awaiting-proof | La orden no está en pending (ya paid, cancelled, …) — bloquea re-envío y replay sobre una orden ya cobrada |
| unknown-channel | channelId no corresponde a ningún canal habilitado — el mensaje lista los id habilitados |
| unsupported-file | mimeType fuera del allowlist, o sizeBytes fuera de rango |
| amount-below-total | declaredAmount < order.total (pagar de más se acepta) |
| duplicate-reference | El mismo número de referencia ya se usó en otra orden — el fraude real de este método |
Cada rechazo trae un message accionable en español.
Uso
import { toBankTransferPaymentMethod } from "@pandait.tech/payment-bank-transfer";
const bankTransfer = toBankTransferPaymentMethod(
{
channels: [
{
id: "banco-pichincha",
kind: "bank",
label: "Banco Pichincha — corriente",
account: { bank: "Banco Pichincha", holder: "Mi Tienda SAS", accountNumber: "123", accountType: "corriente", taxId: "099..." },
},
{
id: "qr-deuna",
kind: "wallet-qr",
label: "QR DeUna",
wallet: "deuna",
qrImageUrl: "https://storage.mitienda.com/qr-deuna.png",
holder: "Mi Tienda SAS",
},
],
whatsapp: "593999999999",
},
{
findOrder: (orderRef) => db.orders.findById(orderRef),
isReferenceUsed: (ref) => db.proofs.existsByReference(ref),
onProofAccepted: (input, order) => db.orders.update(order.code, { status: "proof-submitted", proof: input }),
getDecision: (orderRef) => db.proofs.getDecision(orderRef),
},
);Qué NO hace este package
- No sube ni almacena el archivo del comprobante (solo su metadata).
- No tiene componentes React ni plantillas de correo — eso vive en la capa de UI/
email-kit. - No genera QR ni parsea PDFs.
- Sin dependencias de runtime.
