ES
Obtener NexCMP gratis
Aplica a NexCMP 1.6.1·Actualizado ·Ver como Markdown

Stripe ​

Ubicación en el panel de administración: Finance › Payment channels › Stripe (/payments/stripe). Interruptores y comisiones: Finance › Payment channels › Fees & limits (/payments/fees).

Qué hace ​

Stripe procesa pagos con tarjeta para recargas de saldo. Con la misma cuenta también puede ofrecer Apple Pay, Google Pay, Link y Alipay, y permitir a los clientes guardar una tarjeta para recarga automática. Utilícelo como el canal principal para clientes internacionales.

Requisitos ​

ElementoRequisito
Cuenta de StripeUna cuenta de Stripe que pueda aceptar pagos en USD. Alipay se cobra en JPY y debe ser activado por Stripe para su cuenta.
ClavesUna clave secreta (sk_live_... o sk_test_...) y una clave publicable (pk_live_... o pk_test_...). El formulario solo acepta claves con estos prefijos.
RedSu panel debe ser accesible mediante HTTPS desde Internet (Stripe llama al webhook) y debe tener acceso a api.stripe.com en el puerto 443.
Dominio (solo billeteras)El dominio accesible para los clientes debe servir /.well-known/apple-developer-merchantid-domain-association — NexCMP lo hace por usted.
DependenciasNinguno.

Cuentas compartidas de Stripe

NexCMP solo procesa eventos de webhook para pagos creados por él mismo, por lo que puede usar una cuenta de Stripe que también dé servicio a otra aplicación.

Preparar la infraestructura ​

En el lado de Stripe:

  1. Inicie sesión en el Stripe Dashboard. Active o desactive el Test mode para decidir si va a realizar una prueba o pasar a producción. Las claves de un modo nunca funcionan con el otro.
  2. Abra Developers › API keys. Copie la Publishable key y muestre y copie la Secret key. Mantenga la clave secreta en privado.
  3. (Opcional) Abra Settings › Payment methods y active Alipay si desea ofrecerlo.
  4. No es necesario crear el webhook manualmente; NexCMP puede crearlo por usted (consulte el paso 5 a continuación). Si prefiere hacerlo manualmente, cree un endpoint en Developers › Webhooks con la URL y los eventos indicados en Webhook.

Conectar en NexCMP ​

  1. Abra Finance › Payment channels › Stripe (/payments/stripe).
  2. En la tarjeta API keys elija el Mode (live o test), pegue la Secret key y la Publishable key.
  3. Haga clic en Save. Las claves se guardan en un archivo de configuración en el servidor que solo la cuenta de servicio de NexCMP puede leer. Nunca se devuelven al navegador; posteriormente, la página solo muestra los últimos 4 caracteres.
  4. Haga clic en Check. Un cuadro de diálogo informa sobre la conexión, el modo, el saldo disponible y pendiente, el ID de cuenta, si los cobros están habilitados, si existe un webhook y si Alipay está disponible. Una línea roja indica que esa parte requiere atención.
  5. En la tarjeta Webhook haga clic en Create webhook y confirme. NexCMP solicita a Stripe que cree el endpoint con todos los eventos requeridos y completa Webhook signing secret (whsec_...) automáticamente. La URL precargada en el campo es https://<your-domain>/v1/billing/stripe/webhook, por ejemplo https://cloud.example.com/v1/billing/stripe/webhook.
  6. Abra Fees & limits (/payments/fees), mantenga activado Card (Stripe), configure Stripe fee % y Stripe fixed fee (cents) con su tarifa real y haga clic en Save channels & fees. Consulte Payment channels.

Página de Stripe con el modo, la clave secreta y la clave publicable completados con valores de ejemplo

Webhook ​

El banner rojo "Missing webhook_secret" permanecerá visible hasta que se guarde un signing secret. Sin él, las recargas de Stripe no se registrarán, aunque Stripe haya cobrado el dinero.

ElementoValor
URLhttps://<your-domain>/v1/billing/stripe/webhook
Eventoscheckout.session.completed, payment_intent.succeeded, payment_intent.payment_failed, charge.refunded, charge.dispute.created, charge.dispute.closed, radar.early_fraud_warning.created, refund.updated, refund.failed
FirmaEncabezado Stripe-Signature de Stripe, HMAC-SHA256, 300 segundos de tolerancia. Las solicitudes con una firma no válida reciben HTTP 400.
IdempotenciaCada ID de evento se almacena una sola vez; un reenvío nunca acreditará dos veces.

Si actualizó desde una versión que registraba menos eventos, haga clic de nuevo en Create webhook; el endpoint anterior se conserva, por lo que deberá eliminarlo manualmente en el Stripe Dashboard después.

Las filas 24h events y Latest event de la tarjeta Webhook indican si Stripe se está comunicando con el panel. Los eventos individuales se enumeran en Payment channels › Gateway events (/payments/events, pestaña Stripe), donde cada evento puede visualizarse (Payload) o reintentarse (Replay).

  1. En la tarjeta Wallets (Apple Pay · Google Pay · Link) & Alipay, el campo Customer app Domain registered with Stripe se completa automáticamente con el nombre de host de su sitio (por ejemplo, cloud.example.com).
  2. Haga clic en Register / verify domain y confirme. NexCMP registra el dominio en los dominios de métodos de pago de Stripe y solicita a Stripe que lo valide.
  3. El resultado muestra el estado de Apple Pay, Google Pay y Link. Apple Pay solo se muestra cuando el estado es active.
  4. En Fees & limits, mantenga activado Apple Pay · Google Pay · Link.

Tarjeta Wallet que muestra el dominio registrado y los estados de Apple Pay, Google Pay y Link

Apple Pay permanece inactivo

Apple Pay necesita que el archivo de asociación de dominio responda HTTP 200 en su dominio público. Si coloca Cloudflare u otro proxy delante, no bloquee /.well-known/.

Alipay ​

Alipay es opcional. Actívelo en Stripe Dashboard › Settings › Payment methods, haga clic en Check y espere hasta que el cuadro de diálogo muestre que Alipay está disponible; luego active Alipay (Stripe, JPY display) en Fees & limits. Configure Alipay fee %, Alipay fixed fee, la tasa ¥/USD rate (50–500) y el margen FX spread % (0–20). Actualice la tasa ¥/USD periódicamente; la página advierte si tiene más de 7 días.

Verificación ​

  1. En modo de prueba, inicie sesión en el portal como cliente de prueba, abra Billing, haga clic en Deposit, seleccione Card y pague el mínimo con la tarjeta de prueba de Stripe 4242 4242 4242 4242 (cualquier fecha futura, cualquier CVC).
  2. El saldo aumenta en cuestión de segundos y el pago aparece en Finance › Billing › Top-ups con el estado Completed.
  3. Abra Payment channels › Gateway events › Stripe: debería ver checkout.session.completed o payment_intent.succeeded con una hora de procesamiento.
  4. De vuelta en la página de Stripe, 24h events es superior a 0.

Antes de pasar a producción, cambie Mode a live, pegue las claves de producción y haga clic en Create webhook nuevamente (los webhooks de los modos test y live son independientes).

Límites y notas ​

  • Importes y moneda. Los monederos están en USD. Los pagos con tarjeta, monedero digital y Link se cobran en USD; Alipay se muestra al cliente en JPY y se convierte según su tasa.
  • Comisiones. La comisión real de Stripe no se vuelve a leer automáticamente; el porcentaje de comisión que configure determina lo que ve el cliente y lo que se acredita en el monedero. Seleccione Customer pays top-up fee en Fees & limits para cobrar la comisión adicionalmente.
  • Tarjetas guardadas. Cuando el cliente marca Save card for auto top-up, la tarjeta se almacena en Stripe, no en su servidor. Consulte Saved payment methods.
  • Reembolsos. El reembolso a la tarjeta es un proceso de dos pasos: un administrador crea una solicitud de reembolso para un pago completado (Finance › Billing › Top-ups, acción de reembolso en el pago) y luego la aprueba en Finance › Payouts › Card refunds (/billing/payouts). Los reembolsos de Alipay son asíncronos; si uno falla (refund.failed), se devuelve el importe retenido al monedero.
  • Disputas. Ante charge.dispute.created, NexCMP bloquea la cuenta del cliente, detiene sus servicios prepagos (no se elimina nada) y envía una alerta al administrador. Si usted gana (charge.dispute.closed), el importe se vuelve a acreditar en el monedero.
  • Pagos en espera. Si un webhook nunca llega, NexCMP verifica por sí mismo en Stripe los pagos que hayan permanecido pendientes durante más de 10 minutos y los completa. Los pagos con más de 7 días de antigüedad se ignoran.
  • Los Resellers pueden conectar su propia cuenta de Stripe (webhook https://<their-domain>/v1/billing/stripe/webhook/r/<id>); consulte Resellers.

Resolución de problemas ​

SíntomaCausaSolución
"La clave secreta debe comenzar con sk_live_/sk_test_"Se pegó una clave incorrectaPegue la clave secreta desde Developers › API keys.
"La clave secreta no coincide con el modo live/test"El modo y la clave no coincidenHaga que el Mode coincida con el prefijo de la clave.
"La clave publicable debe comenzar con pk_"Clave incorrectaUtilice la clave publicable.
La comprobación indica que la conexión fallóClave incorrecta, clave revocada o el servidor no puede comunicarse con api.stripe.comVuelva a pegar la clave; pruebe con curl -I https://api.stripe.com desde el servidor.
Banner rojo "Missing webhook_secret"El secreto de firma no está guardadoHaga clic en Create webhook o pegue el secreto whsec_... desde el Stripe Dashboard y pulse Save.
Se cobró el dinero pero el saldo no cambióWebhook no entregado o firma incorrectaCompruebe que la URL termine en /v1/billing/stripe/webhook, que el secreto coincida con el endpoint y reenvíe el evento en Gateway events. En Stripe, abra el endpoint y revise los intentos de entrega (HTTP 400 indica un secreto de firma incorrecto).
Falla "Create webhook"La URL no es HTTPS o no es accesibleUtilice su dominio público https://.
El estado de Apple Pay no está activoDominio no validadoHaga clic nuevamente en Register / verify domain después de que el archivo de asociación de dominio responda 200.
Alipay no está disponible en el cuadro de diálogo CheckNo está activado en StripeActívelo en el Stripe Dashboard y luego haga clic en Check.
El cliente no ve el formulario de tarjetaCard (Stripe) está desactivado o no hay clave secretaActívelo en Fees & limits y guarde las claves.