Stripe

Cómo conectar

Para conectar el sistema de pago Stripe, necesitarás una clave secreta de API y una clave de webhook.

La clave secreta de API se puede copiar yendo a Developers → API keys y copiando la clave secreta.

Paso 1. Ve a Developers → API keys:

Paso 2. Encuentra y copia la clave secreta:

A continuación, debes configurar una URL de devolución de llamada. 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 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: https://chatter.mavibot.ai/stripe\\_callback/result

Paso 6. Se crearán dos endpoints: puedes revisar la configuración antes de añadirlos.

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 redirigido a la página con el webhook configurado.

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

Paso 10. Encuentra la clave de firma (Signing key) y guárdala (la necesitarás más tarde para conectar con 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".

¡Hecho! Has conectado Stripe.

Cómo conectar un callback de estado de transacción

Para recibir un callback adicional, debes añadir un segundo webhook junto al existente.

Establece la URL en: https://chatter.mavibot.ai/stripe\\_callback/\\<api_key>/charge_status

y selecciona los siguientes eventos:

charge.failed
charge.pending
charge.succeeded

Más detalles sobre cada tipo de webhook:

charge.succeeded — contiene información sobre una transacción completada con éxito (similar al callback de pago exitoso)

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

charge.failed — "transacción fallida". El webhook tendrá el formato {primeros 10 caracteres}{tipo de webhook}. Por ejemplo: sk_test_45LDPJLKT95d_charge.failed

Añade la clave de 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 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 impositiva 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 se incluirá en el monto del pago (Inclusive) o se añadirá al mismo (Exclusive).

Después de crear la tasa impositiva, copia su ID en la variable stripe_tax_id antes de declarar el monto del pago.

Para evitar errores, se recomienda establecer la variable stripe_tax_id en una cadena vacía ("") después de recibir el enlace; de esta manera puedes aplicar el impuesto solo cuando sea necesario.

Si se hace correctamente, en el caso de una tasa impositiva 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 colocarla en un botón con el texto "Pay".

El enlace se ve así:

https://checkout.stripe.com/pay/cs_test_a17mskKFFRwEuo3WgBSAUjfk7xaZZIrct9B3Ds2AdODVq1I8aRiqYEBdrU#fidkdWxOYHwnPyd1blpxYHZxWjA0TGFsVzFPVmpmMzJAbVYzUkp1Y0lLYDVgfzR2Q0NxcWZBNUNnTnRSVVRJSGFobEB1UExSczRMMTc8PWRLMGBddl8xalxyPDRoUGhnZm9xXXZANDZyaF0wNTVBVExsPHZyfycpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwcVF8dWAnPyd2bGtiaWBabHFgaCcpJ2BrZGdpYFVpZGZgbWppYWB3dic%2FcXdwYHgl

Por defecto, la moneda está configurada en USD. Para usar una moneda diferente, establece el valor de la variable currency.

También puedes establecer las siguientes variables opcionales antes de asignar el valor de payment_sum para configurar el pago.

¡Importante! Si usas ambas variables stripe_payment_method_type y stripe_additional_payment_method_type, ¡los valores en ellas deben ser diferentes!

card
acss_debit
affirm
afterpay_clearpay
alipay
au_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

Para más detalles sobre cada método y los países donde están disponibles, consulta la documentación de Stripe

Ejemplo de generación de enlace de pago

Vamos a crear un enlace de pago por 1000 AED (la moneda por defecto es USD).

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.

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 y monto.

Si pasas el parámetro de tasa impositiva (stripe_tax_id) en el bloque.

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

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 suscripción. Pasa 'day' para días, 'week' para semanas, 'month' para meses o 'year' para años. Si no se establece la variable, se usará 'month' por defecto.

¡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').

interval_count — el número de intervalos especificados: cuántos días, semanas o meses están incluidos en la suscripción por el monto dado. Por defecto es 1.

stripe_payment_method_type — el método de pago; por defecto es pago con tarjeta. Se puede reemplazar 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'

¡Importante! Si usas ambas variables stripe_payment_method_type y stripe_additional_payment_method_type, ¡los valores en ellas DEBEN ser DIFERENTES!

Para más detalles sobre cada método y los países donde están disponibles, consulta la documentación de Stripe.

¡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').

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 monto 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 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 se puede usar más tarde para verificar el estado de la suscripción.

¡La notificación (callback) solo se envía para el primer pago recurrente!

NO habrá callback para pagos posteriores. El seguimiento se realiza mediante la función y stripe_customer_id.

Configuración para volver a pagos regulares

Para volver a 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 — en caso de é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 permite verificar el resultado.

Verificació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". ”coupons”.

Al hacer clic en el botón "New", se abrirá una página donde debes especificar:

Name — el nombre del descuento;
ID — el identificador, generado automáticamente;
Type — el tipo de descuento: porcentaje o monto fijo;
Duration — la duración del descuento (único o continuo, por ejemplo, para suscripciones) y otros parámetros.

El cupón de descuento aparecerá en el "Catálogo de productos" en la sección "Coupons", y puedes 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

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 de tu panel de Stripe.

A una suscripción existente usando la función stripe_add_subscription_discount.

Establece las condiciones de activación del bloque y llama a la función especificada en la calculadora, pasando los parámetros stripe_subscription_id (ID de suscripción) y coupon_id (ID del cupón de descuento). El descuento se aplicará a los pagos de suscripción posteriores.

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 con éxito, la función devolverá un mensaje con el ID de la suscripción, el tipo de descuento, el monto o porcentaje y la fecha de vencimiento.

Cómo eliminar o cambiar un descuento para una suscripción

Un descuento adjunto a una suscripción se puede eliminar o reemplazar por otro descuento.

Para detener un descuento, establece las condiciones de activación del bloque y llama a la función stripe_remove_subscription_discount en la calculadora, pasando el parámetro stripe_subscription_id (ID de suscripción).

Si la operación es exitosa, 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 adjunto 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 establecerse en "Coincidencia exacta".

Después de un pago exitoso, la variable stripe_payment_completed también se establece en True.

Por ejemplo, puedes manejar un pago exitoso usando un bloque condicional y mostrar el mensaje apropiado al usuario.

Después de que se complete 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 requeridos se pueden extraer del diccionario resultante usando el método get.

Para procesar un pago repetido, primero debes restablecer payment_sum y el enlace generado anteriormente, y solo entonces reasignar la variable payment_sum para obtener un nuevo enlace. Puedes usar el valor anterior.

Cómo probar 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.

Luego sigue los pasos de configuración descritos al principio 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).