---
title: Stripe
description: Conecte Stripe a NexCMP: pagos con tarjeta, Apple Pay, Google Pay, Link y Alipay: claves API, webhook, registro de dominio y pago de prueba.
url: https://nexcmp.com/es/docs/billing/stripe/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# 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 {#what-it-does}

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](https://nexcmp.com/es/docs/billing/auto-top-up/). Utilícelo como el canal principal para clientes internacionales.

## Requisitos {#requirements}

| Elemento | Requisito |
|---|---|
| Cuenta de Stripe | Una cuenta de Stripe que pueda aceptar pagos en **USD**. Alipay se cobra en JPY y debe ser activado por Stripe para su cuenta. |
| Claves | Una clave secreta (`sk_live_...` o `sk_test_...`) y una clave publicable (`pk_live_...` o `pk_test_...`). El formulario solo acepta claves con estos prefijos. |
| Red | Su 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. |
| Dependencias | Ninguno. |

::: info 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 {#prepare-the-infrastructure}

En el lado de Stripe:

1. Inicie sesión en el [Stripe Dashboard](https://dashboard.stripe.com). 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](#webhook).

## Conectar en NexCMP {#connect-in-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](https://nexcmp.com/es/docs/billing/payment-channels/#switches-and-fees-fees-limits).

![Página de Stripe con el modo, la clave secreta y la clave publicable completados con valores de ejemplo](https://nexcmp.com/es/docs/images/billing/stripe-01-keys.webp)


### Webhook {#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.

| Elemento | Valor |
|---|---|
| URL | `https://<your-domain>/v1/billing/stripe/webhook` |
| Eventos | `checkout.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` |
| Firma | Encabezado `Stripe-Signature` de Stripe, HMAC-SHA256, 300 segundos de tolerancia. Las solicitudes con una firma no válida reciben HTTP 400. |
| Idempotencia | Cada 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**).

### Apple Pay, Google Pay y Link {#apple-pay-google-pay-and-link}

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](https://nexcmp.com/es/docs/images/billing/stripe-03-wallets.webp)

::: tip 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}

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 {#verify}

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 {#limits-notes}

- **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](https://nexcmp.com/es/docs/billing/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](https://nexcmp.com/es/docs/customers/resellers/).

## Resolución de problemas {#troubleshooting}

| Síntoma | Causa | Solución |
|---|---|---|
| "La clave secreta debe comenzar con sk_live_/sk_test_" | Se pegó una clave incorrecta | Pegue la clave secreta desde **Developers › API keys**. |
| "La clave secreta no coincide con el modo live/test" | El modo y la clave no coinciden | Haga que el **Mode** coincida con el prefijo de la clave. |
| "La clave publicable debe comenzar con pk_" | Clave incorrecta | Utilice 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.com` | Vuelva 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á guardado | Haga 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 incorrecta | Compruebe 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 accesible | Utilice su dominio público `https://`. |
| El estado de Apple Pay no está activo | Dominio no validado | Haga 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 Check | No está activado en Stripe | Actívelo en el Stripe Dashboard y luego haga clic en **Check**. |
| El cliente no ve el formulario de tarjeta | **Card (Stripe)** está desactivado o no hay clave secreta | Actívelo en **Fees & limits** y guarde las claves. |