Métodos de pago
Comprueba si la organización puede cobrar con tarjeta y guarda, lista, marca como predeterminada o retira la tarjeta de tus usuarios con Stripe Elements.
Actualizado el . 3 min de lectura
Incluido en los planes Profesional y Avanzado. Ver precios
El servicio de métodos de pago gestiona las tarjetas que tus usuarios guardan para pagar sus facturas. La tarjeta se introduce en tu web con Stripe Elements, sobre la cuenta de Stripe de tu organización; UTILIA OS la registra y te deja listarla, elegir la predeterminada y retirarla. Cada clave solo ve las tarjetas de los usuarios de su propia aplicación.
Guardar la tarjeta no autoriza cobros futuros
Con una tarjeta guardada puedes cobrar con el usuario delante. Para cobrarle sin que esté (una cuota mensual, un cobro programado) hace falta además su autorización de cobro, un consentimiento firmado que sirve de prueba legal.
Antes de empezar
| JavaScript | Python | Para qué | Scope |
|---|---|---|---|
paymentMethods.getReadiness() | payment_methods.get_readiness() | Saber si se puede cobrar con tarjeta | billing:payment-methods:read |
paymentMethods.createSetupIntent(usuario) | payment_methods.create_setup_intent(usuario) | Empezar a guardar una tarjeta | billing:payment-methods:write |
paymentMethods.list(userId) | payment_methods.list(user_id) | Tarjetas activas del usuario | billing:payment-methods:read |
paymentMethods.setDefault(pmId, userId) | payment_methods.set_default(pm_id, user_id) | Elegir la predeterminada | billing:payment-methods:write |
paymentMethods.remove(pmId, userId) | payment_methods.remove(pm_id, user_id) | Retirar una tarjeta | billing:payment-methods:write |
El plan de la organización tiene que incluir Finanzas y Pagos con tarjeta (Stripe). Si falta alguno, la respuesta es un bloqueo de plan (MODULE_NOT_ENABLED): no se arregla conectando una cuenta ni dando permisos.
Comprobar si se puede cobrar
Antes de montar el formulario de tarjeta, pregunta si la organización puede cobrar. Así no le pides la tarjeta a nadie para descubrir después que el cobro no es posible. Llámalo al abrir la pantalla de pago y al recibir un error de cobro, no en bucle: la situación cambia pocas veces.
La respuesta trae organizationCanCharge (el valor sobre el que decides), platformAvailable (si la pasarela está encendida en UTILIA OS), livemode (pagos reales o de prueba) y reason, con uno de estos motivos: READY, PLATFORM_DISABLED, NO_ACCOUNT, ONBOARDING_INCOMPLETE, CHARGES_DISABLED o ACCOUNT_DEAUTHORIZED.
const readiness = await sdk.paymentMethods.getReadiness();
if (!readiness.organizationCanCharge) {
// No montes Elements: explica que el pago en línea no está disponible.
console.log(readiness.reason);
}Guardar una tarjeta
Tu servidor pide a UTILIA OS el permiso de guardado con los datos del usuario (externalId y email obligatorios; name, taxId, billingAddress y metadata opcionales), y tu web monta con él el formulario de tarjeta de Stripe. publishableKey es la clave pública de la plataforma UTILIA OS y puede ir al navegador; lo que separa una organización de otra es stripeAccountId.
Guardar una tarjeta
Participan: Tu servidor, Tu web, UTILIA OS, Stripe.
De Tu servidor a UTILIA OS:
POST /api/external/v1/payment-methods/setup-intent
createSetupIntent con los datos del usuario.De UTILIA OS a Tu servidor:
clientSecret, publishableKey y stripeAccountId (respuesta)
De Tu servidor a Tu web:
Los tres valores para Stripe Elements
De Tu web a Stripe:
confirmSetup con la tarjeta
El usuario la introduce en el formulario de Stripe.De Stripe a UTILIA OS:
Aviso de tarjeta guardada
UTILIA OS la registra para ese usuario.De UTILIA OS a Tu servidor:
Aviso PAYMENT_METHOD_ADDED
Si tienes configurados los avisos a tu servidor.
// En tu servidor
const setup = await sdk.paymentMethods.createSetupIntent({
externalId: 'user_01HXYZ',
email: 'cliente@empresa.com',
});
// Devuelve a tu web setup.clientSecret, setup.publishableKey y setup.stripeAccountIdEn tu web, con React y Stripe Elements (igual para los dos lenguajes del servidor):
import { Elements, PaymentElement, useElements, useStripe } from '@stripe/react-stripe-js';
import { loadStripe } from '@stripe/stripe-js';
function SaveCard({ setup }: { setup: { clientSecret: string; publishableKey: string; stripeAccountId: string } }) {
const stripePromise = loadStripe(setup.publishableKey, { stripeAccount: setup.stripeAccountId });
return (
<Elements stripe={stripePromise} options={{ clientSecret: setup.clientSecret }}>
<SaveForm />
</Elements>
);
}
function SaveForm() {
const stripe = useStripe();
const elements = useElements();
async function handleSubmit(event: React.FormEvent) {
event.preventDefault();
if (!stripe || !elements) return;
const { error } = await stripe.confirmSetup({
elements,
confirmParams: { return_url: window.location.href },
redirect: 'if_required',
});
// Sin error, la tarjeta queda guardada cuando UTILIA OS recibe el aviso de Stripe.
if (error) console.error(error.message);
}
return (
<form onSubmit={handleSubmit}>
<PaymentElement />
<button type="submit">Guardar tarjeta</button>
</form>
);
}Listar, elegir la predeterminada y retirar
Cada tarjeta trae id (el identificador que usas en el resto de llamadas y al cobrar), type (CARD, SEPA_DEBIT o LINK), brand, last4, expMonth y expYear, isDefault, status (ACTIVE, EXPIRED o DETACHED) y addedVia (INTERNAL_DASHBOARD, PORTAL o EXTERNAL_APP). En Python, el modelo se llama StoredPaymentMethod y los campos van en snake_case.
setDefault marca una tarjeta como predeterminada y quita la marca a la anterior en la misma operación; los cobros sin tarjeta indicada usarán la nueva. remove la desvincula de Stripe y la deja como DETACHED.
const cards = await sdk.paymentMethods.list('user_01HXYZ');
for (const card of cards) {
console.log(`${card.brand} •••• ${card.last4} ${card.isDefault ? '(predeterminada)' : ''}`);
}
await sdk.paymentMethods.setDefault(cards[1].id, 'user_01HXYZ');
await sdk.paymentMethods.remove(cards[0].id, 'user_01HXYZ');Retirar una tarjeta afecta al cobro automático
Las autorizaciones de cobro que se apoyaban en esa tarjeta dejan de servir: las suscripciones con cobro automático y los cobros programados que dependían de ella fallarán en su próxima ejecución. Recoge una tarjeta y una autorización nuevas antes del siguiente cobro.