Autorizaciones de cobro

Una autorización de cobro es el consentimiento firmado con el que tu usuario te permite cargar en su tarjeta sin que esté delante. Sin ella no hay cuota que se cobre sola ni cobro programado: un cargo sin autorización es un cargo no autorizado. UTILIA OS guarda la aceptación como prueba legal y la usan las suscripciones con cobro automático, los cobros programados y invoices.charge. Funciona con la clave de tu aplicación externa, siempre desde tu servidor.

Guardar la tarjeta y autorizar el cobro son dos pasos distintos y hacen falta los dos, en ese orden: la tarjeta guardada permite cobrar con el usuario delante; la autorización, cobrarle sin él.

Antes de empezar

• El plan necesita Finanzas y Pagos con tarjeta (Stripe), con la capacidad «Cobro automático de facturas».
• Scopes: billing:payment-authorizations:read para consultar, :write para registrar y :revoke para retirar. El de registrar es crítico: solo lo concede un Super Administrador, con motivo.
• El servicio se llamaba mandates hasta la versión 3.0.0. El nombre antiguo sigue funcionando como alias en desuso (devuelve el mismo servicio y avisa una vez por proceso).

Dos alcances, dos autorizaciones

Si usas la de un alcance para lo otro, el servidor responde 409 PAYMENT_AUTHORIZATION_NOT_ACTIVE con un mensaje que dice qué alcance hace falta. Las autorizaciones de un solo uso las crea el propio motor de cobro; no se pueden pedir desde fuera.

Recoger la autorización

Pide el texto justo antes de mostrarlo: no lo guardes de una sesión anterior ni lo compartas entre organizaciones. La tarjeta va como setupIntentId si el usuario la acaba de introducir, o como paymentMethodId si reutiliza una guardada; hace falta una de las dos.

La IP y el navegador los mandas tú porque es tu servidor quien sabe desde dónde aceptó; UTILIA OS guarda la prueba sin posibilidad de cambio.

const consentimiento = await sdk.paymentAuthorizations.getConsentText({ scope: 'RECURRING' });
// Muestra consentimiento.text; consentimiento.companyName es quien cobrará
 
const autorizacion = await sdk.paymentAuthorizations.create({
  userId: 'user_01HXYZ',
  setupIntentId: 'seti_1OabcDEF',
  consentText: consentimiento.text,
  consentVersion: consentimiento.version,
  acceptedAt: new Date().toISOString(),
  acceptedIp: req.ip,
  acceptedUserAgent: req.headers['user-agent'],
  scope: 'RECURRING',
});

Si el texto o la versión no son los vigentes, la llamada falla con un 422 PAYMENT_AUTHORIZATION_CONSENT_MISMATCH sin gastar la intención de guardado de la tarjeta: vuelve a pedir el texto y enséñaselo otra vez al usuario. create hace un único intento, sin reintentos automáticos.

Consultar y retirar

list filtra por userId y por active. Ninguna respuesta incluye el número de la tarjeta ni el texto íntegro del consentimiento: solo la marca, los cuatro últimos dígitos y la caducidad.

const pagina = await sdk.paymentAuthorizations.list({ userId: 'user_01HXYZ', active: true });
 
await sdk.paymentAuthorizations.revoke(autorizacion.id, {
  userId: 'user_01HXYZ',
  reason: 'El usuario la retiró desde su perfil.',
});

Errores y avisos

Los bloqueos de plan (MODULE_NOT_ENABLED, CAPABILITY_NOT_ENABLED) y la falta de scope (INSUFFICIENT_SCOPE) llegan como 403 y no se reintentan.

Avisos que recibe tu servidor: PAYMENT_AUTHORIZATION_GRANTED (el usuario ha autorizado), PAYMENT_AUTHORIZATION_CONSUMED (una de un solo uso se gastó al cobrar), PAYMENT_AUTHORIZATION_REVOKED (retirada por el usuario o por el equipo) y PAYMENT_METHOD_EXPIRING (la tarjeta caduca pronto: pide otra antes de que falle la renovación).

Siguiente paso

• SuscripcionesMonta la cuota que se cobrará con esta autorización.
• Endpoints de autorizaciones de cobroEl contrato REST completo, campo a campo.