> For the complete documentation index, see [llms.txt](https://docs.mavibot.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mavibot.ai/doc/es/integrations/payment/stripe.md). # Stripe ## Cómo conectar Para conectar el sistema de pago Stripe, necesitarás una clave API secreta y una clave de webhook. La clave API secreta se puede copiar yendo a Developers → API keys y copiando la Secret key. Paso 1. Ve a Developers → API keys:

Fig. 1. Cómo encontrar la sección api keys

Paso 2. Encuentra y copia la Secret key:

A continuación, debes configurar una URL de callback. Esto permite que el bot reciba notificaciones de pago. Ve a la sección Webhooks y añade la URL del webhook.

Aparecerá un formulario.

Paso 3. Haz clic en "+add destination". Paso 4. Selecciona los eventos.

Paso 3. Selecciona el tipo "Webhook endpoint".

Paso 4. Revisa el tipo de solicitud y haz clic en "Continue".

Paso 5. Introduce un nombre y especifica la URL del endpoint.

Establece la URL en: Paso 6. Se crearán dos endpoints — puedes revisar la configuración antes de agregarlos.

Paso 7. Haz clic en el botón "Add destinations". Los webhooks se guardarán. Paso 8. Haz clic en "Done".

Guarda y serás llevado a la página con el webhook configurado.

Paso 9. Haz clic en el webhook en el que seleccionaste todos los eventos.

Paso 10. Encuentra la Signing key y guárdala (la necesitarás más adelante para conectarte a MaviBot).

Una vez que tengas las claves, procede a conectar en Mavibot. En Mavibot, abre la sección "Acquiring" y selecciona Stripe.

En la página de conexión, introduce las claves que obtuviste.

Haz clic en "Save settings". {% hint style="success" %} ¡Listo! Has conectado Stripe. {% endhint %} ## Cómo conectar un callback del estado de la transacción Para recibir un callback adicional, debes añadir un segundo webhook junto con el existente. Establece la URL en: \/charge\_status y selecciona los siguientes eventos: * `charge.failed` * `charge.pending` * `charge.succeeded`

{% hint style="success" %} Más detalles sobre cada tipo de webhook: 1. `charge.succeeded` — contiene información sobre una transacción completada correctamente (similar al callback de pago exitoso) 2. `charge.pending` — "transacción en curso", puede tardar hasta 7 días en completarse. El webhook tendrá el formato {primeros 10 caracteres}{tipo de webhook} Por ejemplo: sk\_test\_45LDPJLKT95d\_charge.pending 3. `charge.failed` — "transacción fallida". El webhook tendrá el formato {primeros 10 caracteres}{tipo de webhook} Por ejemplo: sk\_test\_45LDPJLKT95d\_charge.failed {% endhint %} Añade la clave del webhook obtenida después de guardar en el campo de Mavibot — Webhook key2.

**stripe\_invoice\_id** — el identificador de la transacción para la cual no se recibió un callback de pago exitoso inmediatamente después del pago. ## Cómo configurar los impuestos Para usar impuestos en los pagos, primero debes crearlos en tu panel de Stripe. Para ello, escribe "tax rates" en la barra de búsqueda:

Y haz clic en "+ Add tax rates".

Luego introduce la tasa de impuesto aplicable.

En el menú que se abre, selecciona el tipo de impuesto, la región a la que se aplica, el porcentaje y si el impuesto estará incluido en el importe del pago (Inclusive) o añadido encima de él (Exclusive).

Después de crear la tasa de impuesto, copia su ID en la variable stripe\_tax\_id antes de declarar el importe del pago.

Para evitar errores, se recomienda establecer la variable stripe\_tax\_id como una cadena vacía ("") después de recibir el enlace — así podrás aplicar el impuesto solo cuando sea necesario. Si se hace correctamente, en el caso de una tasa de impuesto con el parámetro exclusive, verás lo siguiente:

Cómo obtener un enlace de pago Para generar un enlace de pago, establece el valor de la variable payment\_sum (por ejemplo, 150 o 100.55 — ¡usa un punto, no una coma!). Después de eso, aparecerá la variable stripe\_pay\_url. Puedes mostrar esta variable como un enlace o ponerla en un botón con el texto "Pay". El enlace se ve así: `https://checkout.stripe.com/pay/cs_test_a17mskKFFRwEuo3WgBSAUjfk7xaZZIrct9B3Ds2AdODVq1I8aRiqYEBdrU#fidkdWxOYHwnPyd1blpxYHZxWjA0TGFsVzFPVmpmMzJAbVYzUkp1Y0lLYDVgfzR2Q0NxcWZBNUNnTnRSVVRJSGFobEB1UExSczRMMTc8PWRLMGBddl8xalxyPDRoUGhnZm9xXXZANDZyaF0wNTVBVExsPHZyfycpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwcVF8dWAnPyd2bGtiaWBabHFgaCcpJ2BrZGdpYFVpZGZgbWppYWB3dic%2FcXdwYHgl` {% hint style="warning" %} Por defecto, la moneda está establecida en USD. Para usar una moneda diferente, establece el valor de la variable currency. {% endhint %} También puedes establecer las siguientes variables opcionales antes de definir el valor de payment\_sum para configurar el pago.

Параметры функции	Описание паараметра
currency	moneda del pedido. Los valores permitidos están aquí —https://stripe.com/docs/currencies
payment_description	descripción del pago
stripe_tax_id	identificador de la tasa de impuesto configurada en tu panel de Stripe. Las instrucciones de configuración se proporcionan en la sección "Cómo configurar los impuestos".
stripe_invoice_enable	bandera para habilitar el guardado de facturas (recibos). Establece cualquier valor para habilitar esto — todos los documentos relevantes estarán disponibles en tu panel de Stripe.
stripe_locale	establece el idioma de la página de pago: en, de, etc. Todas las opciones disponibles: https://stripe.com/docs/api/checkout/sessions/create#create_checkout_session-locale Si stripe_locale no está configurado, se usará el idioma del navegador del cliente.
stripe_payment_method_type	método de pago; por defecto es pago con tarjeta. Puede reemplazarse con otros métodos de pago disponibles en Stripe. Los métodos disponibles se enumeran a continuación. Por ejemplo, `stripe_payment_method_type = "customer_balance"`
stripe_additional_payment_method_type	añade un método de pago adicional. Los métodos disponibles se enumeran a continuación. Por ejemplo, `stripe_additional_payment_method_type = "sepa_debit"`
coupon_id	identificador del cupón de descuento
stripe_expired	tiempo de expiración del enlace de pago. Se especifica en segundos. El mínimo es 30 minutos, el máximo es 24 horas. El valor predeterminado es 24 horas.
stripe_automatic_tax	habilita el cálculo y la recaudación automáticos de impuestos al finalizar la compra. Envía "1" para habilitarlo. Para más detalles, consulta los artículos de Stripe.

{% hint style="warning" %} ¡Importante! Si usas ambas variables stripe\_payment\_method\_type y stripe\_additional\_payment\_method\_type, ¡los valores en ellas deben ser diferentes! {% endhint %}

Lista de valores para stripe_payment_method_type y stripe_additional_payment_method_type

card\ acss\_debit\ affirm \ afterpay\_clearpay \ alipay\ eau\_becs\_debit \ bacs\_debit \ bancontact \ blik \ boleto \ cashapp \ customer\_balance \ eps \ fpx \ giropay \ grabpay \ ideal \ klarna \ konbini \ link \ oxxo \ p24 \ paynow \ paypal \ pix \ promptpay \ sepa\_debit \ sofort \ us\_bank\_account \ wechat\_pay zip

{% hint style="info" %} [Para más detalles sobre cada método y los países en los que están disponibles, consulta la documentación de Stripe](https://stripe.com/docs/api/payment_methods/object#payment_method_object-type) {% endhint %} ### Ejemplo de generación de enlace de pago Vamos a crear un enlace de pago para 1000 AED (la moneda predeterminada es USD).

{% hint style="warning" %} Nota: — Primero, especifica los parámetros opcionales como first\_name, payment\_description, etc. — Luego, asigna el valor a la variable payment\_sum al final. Las variables también se pueden establecer antes en la cadena, no necesariamente en el mismo bloque — esto es solo un ejemplo. {% endhint %} Luego muestra la variable stripe\_pay\_url, que contiene el enlace, en el punto deseado — ya sea en un bloque de mensaje o en un botón: Ejemplo 1. Mostrar el enlace de pago directamente en un mensaje:

Ejemplo 2. Añadir el enlace de pago a un botón.

Cuando se hace clic en el botón o se sigue el enlace, tu pagador será redirigido a la página de pago.

El ejemplo muestra que se aplicaron los parámetros que especificamos en la calculadora en la configuración del bloque: descripción del pedido, moneda e importe. Si pasas el parámetro de tasa de impuesto (stripe\_tax\_id) en el bloque.

La tasa de impuesto también se mostrará en el formulario de pago.

Ejemplo de código para copiar

payment\_description = "test payment" currency = 'AED' stripe\_tax\_id = 'enter\_your\_stripe\_id\_tax' payment\_sum = 1000

Dónde encontrar el ID del impuesto.

## Cómo configurar pagos recurrentes Para pagos recurrentes (suscripciones), declara la variable stripe\_subscription antes de la variable payment\_sum y asígnale el nombre de la suscripción. También puedes añadir las siguientes variables: interval — la duración del intervalo de la suscripción. Envía 'day' para días, 'week' para semanas, 'month' para meses, o 'year' para años. Si la variable no está configurada, se usará 'month' por defecto. {% hint style="warning" %} ¡Importante! La duración de un ciclo de suscripción no puede exceder 1 año (para el parámetro 'year'), 12 meses (para el parámetro 'month') o 52 semanas (para el parámetro 'week'). {% endhint %}

interval\_count — el número de intervalos especificados: cuántos días, semanas o meses están incluidos en la suscripción para el importe dado. El valor predeterminado es 1. stripe\_payment\_method\_type — el método de pago; por defecto es pago con tarjeta. Puede reemplazarse con otros métodos de pago disponibles en Stripe. Los métodos disponibles se enumeran a continuación. Por ejemplo, `stripe_payment_method_type = 'customer_balance'` stripe\_additional\_payment\_method\_type — añade un método de pago adicional. Los métodos disponibles se enumeran a continuación. Por ejemplo, `stripe_additional_payment_method_type = 'sepa_debit'` {% hint style="warning" %} ¡Importante! Si usas ambas variables stripe\_payment\_method\_type y stripe\_additional\_payment\_method\_type, ¡los valores en ellas DEBEN ser DIFERENTES! {% endhint %}

Lista de valores para stripe_payment_method_type y stripe_additional_payment_method_type:

{% hint style="info" %} [Para más detalles sobre cada método y los países en los que están disponibles, consulta la documentación de Stripe](https://stripe.com/docs/api/payment_methods/object#payment_method_object-type). {% endhint %} {% hint style="warning" %} ¡Importante! La duración de un ciclo de suscripción no puede exceder 1 año (para el parámetro 'year'), 12 meses (para el parámetro 'month') o 52 semanas (para el parámetro 'week'). {% endhint %} En este ejemplo, se creará una suscripción llamada 'My\_subscription' con un precio de 1000 AED por 1 mes, y se cobrará un pago recurrente del mismo importe después de 1 mes.

Ejemplo para copiar: `stripe_subscription = 'My_subscription' interval = 'month' payment_sum = 90` Para cobrar el pago de la suscripción una vez cada dos, tres o cuatro meses, pasa el parámetro interval\_count: `stripe_subscription = 'My_subscription'` `interval = 'month'` `interval_count = 3` `payment_sum = 90` Para cambiar el intervalo de pago de la suscripción de mensual a semanal, pasa la palabra week en el parámetro interval: `stripe_subscription = 'My_subscription'` `interval = 'week'` `interval_count = 3` `payment_sum = 90` Después del pago, las variables de transacción del cliente incluirán stripe\_subscription\_id, que se necesita para configurar la cancelación de la suscripción, y stripe\_customer\_id, que luego se puede usar para comprobar el estado de la suscripción. {% hint style="warning" %} ¡La notificación (callback) solo se envía para el primer pago recurrente! NO habrá callback para los pagos posteriores. El seguimiento se realiza mediante la función y stripe\_customer\_id. {% endhint %}

## Configuración para volver a los pagos regulares Para volver a los pagos regulares, asigna una cadena vacía a la variable de suscripción: stripe\_subscription = ''. En este caso, las variables interval e interval\_count no afectarán la generación del enlace.

## Configuración para cancelar una suscripción Para cancelar una suscripción en la calculadora, usa el método stripe\_remove\_subscription(stripe\_subscription\_id), donde stripe\_subscription\_id es el identificador guardado en las variables de transacción después del pago. Esto mantendrá la suscripción pagada activa hasta el final del período de facturación actual, pero no se realizarán más cargos, y la suscripción se cancelará una vez que expire el período.

answer = stripe\_remove\_subscription('#{stripe\_subscription\_id}') stripe\_remove\_subscription — si tiene éxito, devuelve una respuesta con información sobre la fecha hasta la cual la suscripción cancelada permanecerá activa. En este ejemplo, el resultado de la función se almacenará en la variable answer, lo que te permitirá verificar el resultado. ## Comprobación del estado de la suscripción stripe\_check\_subscription(subscription\_id, customer\_id), donde stripe\_subscription\_id — identificador de la suscripción stripe\_customer\_id — identificador del cliente en Stripe (parámetro opcional)

## Cómo crear un cupón y obtener un ID de descuento Para obtener un identificador de descuento, crea un cupón en tu panel en la sección "Coupons". ”[cupones](https://dashboard.stripe.com/coupons)”.

Al hacer clic en el botón "New" se abrirá una página donde debes especificar: 1. Nombre — el nombre del descuento; 2. ID — el identificador, generado automáticamente; 3. Tipo — el tipo de descuento: porcentaje o importe fijo; 4. Duración — la duración del descuento (único o continuo, por ejemplo para suscripciones) y otros parámetros.

El cupón de descuento aparecerá en el "Product catalogue" dentro de la sección "Coupons", y podrás ver el ID del descuento abriendo el menú del cupón.

Haz clic en el cupón para copiar el ID del cupón.

## Cómo aplicar un descuento a un pedido 1. Al generar un enlace de pago (funciona tanto para suscripciones como para pagos únicos). En la calculadora del bloque, antes de declarar la variable payment\_sum, establece la variable coupon\_id y pasa el identificador del descuento desde tu panel de Stripe.

2. A una suscripción existente usando la función stripe\_add\_subscription\_discount. Establece las condiciones de activación para el bloque y llama a la función especificada en la calculadora, pasando los parámetros stripe\_subscription\_id (ID de la suscripción) y coupon\_id (ID del descuento del cupón). El descuento se aplicará a los pagos posteriores de la suscripción.

Ejemplo de código para copiar

stripe\_subscription = 'test subscription' interval = 'month' payment\_description = 'test payment' currency = 'AED' coupon\_id = 'BD8VIwi8' stripe\_add\_subscription\_discount(stripe\_subscription\_id, coupon\_id) stripe\_tax\_id = 'Qfkiwiki29jcs' payment\_sum = 90

Si el descuento se aplica correctamente, la función devolverá un mensaje con el ID de la suscripción, el tipo de descuento, el importe o porcentaje, y la fecha de expiración.

## Cómo eliminar o cambiar un descuento para una suscripción Un descuento vinculado a una suscripción puede eliminarse o reemplazarse por otro descuento. Para detener un descuento, establece las condiciones de activación para el bloque y llama a la función stripe\_remove\_subscription\_discount en la calculadora, pasando el parámetro stripe\_subscription\_id (ID de la suscripción).

Si la operación tiene éxito, la función devolverá un mensaje que contiene el ID de la suscripción y la fecha de cancelación del descuento. Reemplazar un descuento, al igual que añadir uno nuevo, se hace usando la función stripe\_add\_subscription\_discount. Asegúrate de pasar los parámetros stripe\_subscription\_id y coupon\_id. Una solicitud exitosa actualizará el cupón vinculado a la suscripción y devolverá un mensaje con los detalles actualizados. ## Cómo manejar el resultado Después de un pago exitoso, el bot recibirá callbacks que indican una transacción exitosa. En el sistema, estos callbacks aparecen como mensajes del usuario. Para evitar que los usuarios los envíen manualmente, consisten en los primeros 20 caracteres de la clave secreta seguidos de \_success, por ejemplo: sk\_live\_d35gky6d8ers\_success

Estos callbacks NO son visibles para el usuario — solo son visibles para el operador. El tipo de comparación debe configurarse como "Exact match". Después de un pago exitoso, la variable stripe\_payment\_completed también se establece en True. Por ejemplo, puedes gestionar un pago exitoso usando un bloque condicional y mostrar el mensaje apropiado al usuario.

Después de completar el pago, la variable stripe\_callback\_data se añadirá a los datos del cliente, conteniendo la respuesta del sistema de pago para la transacción completada. Los datos necesarios se pueden extraer del diccionario resultante usando el método get. {% hint style="warning" %} Para procesar un pago repetido, primero debes restablecer payment\_sum y el enlace generado previamente, y solo entonces reasignar la variable payment\_sum para obtener un nuevo enlace. Puedes usar el valor anterior. {% endhint %} ## Cómo probar los pagos Para probar la integración, puedes usar la clave secreta del entorno de prueba. Para ello, cambia al entorno de prueba en el panel de Stripe usando el menú de la derecha. ![](https://lh5.googleusercontent.com/r-tuJboMES8alkTUpKwA4HKrmL_epNtSXdENrv12EyR9dGCtvRLBK6qw4UGcr59GA3unxc1cV1otCu80nqHEw9VhbEK05ovPQ1Ad8chBv50LAWPO16nEPC2hFhCAsCe3khtBJrob=s0) Luego sigue los pasos de configuración descritos al comienzo de esta guía. Introduce la clave secreta de prueba y añade la URL del webhook en el entorno de prueba. Para las pruebas, usa un número de tarjeta de pago de prueba ([puedes encontrar el número de tarjeta para tu país en el sitio web oficial de Stripe](https://stripe.com/docs/testing#regulatory-cards)). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.mavibot.ai/doc/es/integrations/payment/stripe.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.