Cómo Conectarse

Para conectar el sistema de pago bePaid, necesitarás un ID de tienda, una clave secreta y una clave pública. Una vez que recibas estas credenciales, dirígete a la configuración del sistema de pago en MaviBot.

Para obtener el ID de tienda, la clave secreta y la clave pública, contacta al soporte técnico de bePaid.

En MaviBot, abre la sección Adquirencia, selecciona bePaid e ingresa las credenciales que recibiste.

Nota: El último campo es un interruptor que selecciona el endpoint de la API según el país de uso: Bielorrusia o Rusia.

Cómo Generar un Enlace de Pago

Para generar un enlace de pago, asigna un valor a la variable payment_sum (por ejemplo: 150 o 100.55; usa un punto como separador decimal).

Una vez que se establece la variable payment_sum, la variable bepaid_pay_url se crea automáticamente. Puedes mostrar esta variable como un enlace en un mensaje o usarla en un botón con el texto "Pagar".

Parámetro de la Función Descripción Más Información
currency Moneda de pago en formato ISO 4217. Por ejemplo: USD
language Idioma de la página de pago. Valor predeterminado: en. Valores permitidos:
• en — Inglés
• es — Español
• tr — Turco
• de — Alemán
• it — Italiano
• ru — Ruso
• zh — Chino
• fr — Francés
• da — Danés
• sv — Sueco
• no — Noruego
• fi — Finlandés
• pl — Polaco
• ja — Japonés
• uk — Ucraniano
• be — Bielorruso
• ka — Georgiano
• ro — Rumano
payment_description Descripción del pago. —
link_expired Caducidad del enlace de pago. Establece la fecha de caducidad en el formato dd.mm.yyyy (por ejemplo: 25.06.2025). Por defecto, el pago debe completarse en un plazo de 24 horas. También puedes usar el campo Asignar variables al redirigir:

• link_expired = current_date + 2 — el enlace será válido durante 2 días hasta las 00:00.

• Puedes especificar una fecha y hora de caducidad exactas en el formato dd.mm.yyyy hh:mm (por ejemplo: 25.06.2025 12:23).

También se pueden usar variables estándar. Ejemplo para un enlace válido durante 30 minutos:

python\ntime = current_time + 30\nlink_expired = "#{current_date} #{time}"\n
russian_host Indicador para una tienda registrada en el host ruso de bePaid. Establece este parámetro en 1 si tu tienda está registrada en bepaid.tech. Para cambiar al host bielorruso, establece este parámetro en "" (valor vacío).
test_payments Habilita los pagos de prueba. Asigna cualquier valor a esta variable antes de crear el enlace de pago. —
bepaid_attempts Especifica el número de intentos de pago. Por defecto, se permite 1 intento. —
customer_data Un objeto JSON que contiene el nombre, apellido y correo electrónico del pagador. Esta información es necesaria para enviar el recibo de pago y se puede editar en la página de pago. El parámetro debe pasarse como un objeto en formato JSON.

Ejemplo:

python\ncustomer_data = {\n \"first_name\": \"Sam\",\n \"last_name\": \"Smith\",\n \"email\": \"[email protected]\"\n}\n
bepaid_contract (condicionalmente requerido) Propósito del pago para pagos basados en token. Valores permitidos:

• recurring — para pagos recurrentes con un cronograma fijo.
• card_on_file — para pagos únicos o irregulares, por ejemplo, cobrar al cliente después de que se haya prestado un servicio.

Ejemplo de enlace de pago:

https://checkout.bepaid.by/widget/hpp.html?token=a05eabd3f9368725efbc175614c7d469da08f198cc51916b07fb75e53f9a3e1a

Antes de asignar un valor a payment_sum, puedes definir variables opcionales adicionales para personalizar el pago.

Por defecto, la moneda de pago es el rublo bielorruso (BYN). Si deseas usar otra moneda, asigna un valor a la variable currency.

Después de que se complete el pago, la variable bepaid_callback_data se agrega al cliente. Contiene la respuesta del sistema de pago para la transacción completada.

Puedes recuperar los valores requeridos de este diccionario usando la función get().

Cómo Probar Pagos

Para realizar un pago de prueba, asigna cualquier valor a la variable test_payments antes de establecer la variable payment_sum.

Importante: Elimina la variable test_payments antes de cambiar tu bot al modo en vivo.

Tarjetas de Prueba

Número de Tarjeta Resultado
4200000000000000 Pago exitoso
4005550000000019 Pago fallido

Ejemplo de Generación de un Enlace de Pago

El siguiente ejemplo genera un enlace de pago por 100 rublos bielorrusos (moneda predeterminada).

Nota: Primero asigna cualquier variable de configuración adicional, luego asigna el valor a payment_sum. Estas variables también se pueden asignar antes en tu flujo de trabajo; no tienen que estar en el mismo bloque.

Finalmente, muestra la variable bepaid_pay_url donde sea necesario. Contiene el enlace de pago generado.

Gestión de Suscripciones

La integración de bePaid te permite crear suscripciones para tus clientes.

Antes de usar esta funcionalidad en MaviBot, crea un plan de suscripción en tu cuenta de bePaid.

Si las secciones Planes y Suscripciones no están disponibles en tu cuenta, contacta a tu administrador de cuenta.

Creación de una Suscripción y Generación de un Enlace de Pago

Usa la función get_bepaid_subscription_url y pasa el parámetro plan_id.

La función crea una suscripción y devuelve un enlace de pago.

Envía el enlace generado al cliente y espera a que se complete el pago.

Después de un pago exitoso:

  • la suscripción se activa;
  • el trato recibe las variables:
    • bepaid_subscription_id;
    • bepaid_subscription_status;
  • se envía un callback al bot (consulta Cómo Manejar el Resultado).

Obtención de Información de la Suscripción

Para recuperar la información actual de la suscripción, usa la función get_bepaid_subscription_info.

Pasa el parámetro subscription_id. Su valor se puede tomar de la variable bepaid_subscription_id.

Cancelación de una Suscripción

Para cancelar una suscripción, usa la función cancel_bepaid_subscription.

La función acepta un solo parámetro:

  • subscription_id — el valor se puede tomar de la variable bepaid_subscription_id.

Después de una cancelación exitosa:

  • la variable bepaid_subscription_status se establece en "canceled";
  • se envía un callback al bot (consulta Cómo Manejar el Resultado).

Estados de la Suscripción

Estado Descripción
trial Suscripción de período de prueba activa o cancelada.
active Suscripción activa con pago realizado a tiempo.
failed Suscripción fallida. bePaid no pudo procesar el siguiente pago.
error Ocurrió un error mientras bePaid intentaba procesar el pago.
canceled La suscripción ha sido cancelada y ya no está activa.

Pagos Recurrentes

También puedes configurar pagos recurrentes sin crear un plan de suscripción en tu cuenta de bePaid.

Para hacerlo, necesitas el token de tarjeta del cliente.

Obtención de un Token de Tarjeta

Para obtener el token de tarjeta del cliente, el cliente debe completar un pago inicial usando un enlace de pago generado con la variable payment_sum.

Antes de asignar un valor a payment_sum, establece la variable bepaid_contract para definir el propósito de los futuros pagos basados en token.

Valores admitidos:

  • recurring — para pagos recurrentes con un cronograma predefinido.
  • card_on_file — para pagos únicos o irregulares, por ejemplo, cobrar al cliente después de que se haya prestado un servicio.

Nota: La opción card_on_file no es compatible con todos los bancos adquirentes. Contacta a tu administrador de cuenta si planeas usar esta opción.

Después de un pago exitoso, la variable bepaid_client_card_token se agrega al trato. Almacena el token de tarjeta del cliente, que se puede usar para pagos futuros sin interacción del cliente.

A continuación, configura tu flujo de trabajo, define la fecha o condición requerida para cobrar al cliente y llama a la función make_bepaid_token_payment.

Los parámetros deben pasarse en el siguiente orden:

amount → currency → description → contract

Descripciones de Parámetros

El valor del parámetro contract debe coincidir exactamente con el valor especificado al generar el enlace de pago inicial.

Parámetro Descripción
amount (requerido) Monto del pago. El valor debe ser un número entero o decimal, por ejemplo: 100 o 100.5.
currency (requerido) Moneda del pago en formato ISO 4217, por ejemplo: USD.
description (requerido) Descripción del pago, por ejemplo: "Pago de suscripción semanal para participar en el club de pasatiempos".
contract (requerido) Propósito del pago por token. Valores permitidos: recurring o card_on_file.

Si el pago es exitoso:

  • la función devuelve el mensaje "Cobro exitoso mediante token de bePaid";
  • el bot recibe un callback de pago exitoso;
  • la variable bepaid_token_payment_completed se establece en True.

Si el pago falla:

  • la función devuelve un mensaje que describe el motivo del fallo;
  • el bot recibe un callback con el sufijo _fail;
  • la variable bepaid_token_payment_completed se establece en False.

Si el banco requiere verificación adicional del cliente, la función devuelve un enlace donde el cliente puede completar la autenticación 3-D Secure.

Cómo Manejar el Resultado

En respuesta a las acciones del cliente, el bot recibe callbacks que consisten en los primeros 20 caracteres de la clave secreta seguidos de un sufijo que indica el tipo de operación y el resultado.

El callback aparece en el sistema como un mensaje de usuario, pero no es visible para el cliente.

Callbacks de Pago

Para pagos únicos, el bot recibe uno de los siguientes callbacks:

  • keyNumber_success — pago exitoso.
  • keyNumber_fail — pago fallido.

También puedes rastrear el resultado del pago usando las siguientes variables:

  • bepaid_payment_completed — pago completado por el cliente.
  • bepaid_token_payment_completed — pago automático completado usando el token de tarjeta del cliente.

Callbacks de Suscripción

Después de que una suscripción se active exitosamente, ya sea durante el pago inicial o un pago recurrente, el bot recibe:

keyNumber_success

Si la suscripción se cancela, el bot recibe:

keyNumber_canceled

Si un pago de suscripción falla, el bot recibe:

keyNumber_fail