Como Conectar

Para conectar o sistema de pagamento bePaid, você precisará de um Store ID, chave secreta e chave pública. Depois de receber essas credenciais, vá para as configurações do sistema de pagamento no MaviBot.

Para obter o Store ID, a chave secreta e a chave pública, entre em contato com o suporte técnico da bePaid.

No MaviBot, abra a seção Adquirência, selecione bePaid e insira as credenciais recebidas.

Nota: O último campo é um interruptor que seleciona o endpoint da API dependendo do país de uso: Bielorrússia ou Rússia.

Para gerar um link de pagamento, atribua um valor à variável payment_sum (por exemplo: 150 ou 100.55; use um ponto como separador decimal).

Uma vez que a variável payment_sum é definida, a variável bepaid_pay_url é criada automaticamente. Você pode exibir esta variável como um link em uma mensagem ou usá-la em um botão com o texto "Pagar".

Parâmetro da Função Descrição Mais Informações
currency Moeda do pagamento no formato ISO 4217. Por exemplo: USD
language Idioma da página de pagamento. Padrão: en. Valores permitidos:
• en — Inglês
• es — Espanhol
• tr — Turco
• de — Alemão
• it — Italiano
• ru — Russo
• zh — Chinês
• fr — Francês
• da — Dinamarquês
• sv — Sueco
• no — Norueguês
• fi — Finlandês
• pl — Polonês
• ja — Japonês
• uk — Ucraniano
• be — Bielorrusso
• ka — Georgiano
• ro — Romeno
payment_description Descrição do pagamento. —
link_expired Expiração do Link de Pagamento. Defina a data de expiração no formato dd.mm.yyyy (por exemplo: 25.06.2025). Por padrão, o pagamento deve ser concluído em até 24 horas. Você também pode usar o campo Atribuir Variáveis no Redirecionamento:

• link_expired = current_date + 2 — o link será válido por 2 dias até 00:00.

• Você pode especificar uma data e hora de expiração exatas no formato dd.mm.yyyy hh:mm (por exemplo: 25.06.2025 12:23).

Variáveis padrão também podem ser usadas. Exemplo para um link válido por 30 minutos:

python\ntime = current_time + 30\nlink_expired = "#{current_date} #{time}"\n
russian_host Indicador para uma loja registrada no host russo da bePaid. Defina este parâmetro como 1 se sua loja estiver registrada em bepaid.tech. Para alternar para o host bielorrusso, defina este parâmetro como "" (valor vazio).
test_payments Ativa pagamentos de teste. Atribua qualquer valor a esta variável antes de criar o link de pagamento. —
bepaid_attempts Especifica o número de tentativas de pagamento. Por padrão, 1 tentativa é permitida. —
customer_data Um objeto JSON contendo o first_name, last_name e email do pagador. Esta informação é necessária para enviar o recibo de pagamento e pode ser editada na página de pagamento. O parâmetro deve ser passado como um objeto formatado em JSON.

Exemplo:

python\ncustomer_data = {\n \"first_name\": \"Sam\",\n \"last_name\": \"Smith\",\n \"email\": \"[email protected]\"\n}\n
bepaid_contract (condicionalmente obrigatório) Finalidade do pagamento para pagamentos baseados em token. Valores permitidos:

• recurring — para pagamentos recorrentes com um cronograma fixo.
• card_on_file — para pagamentos únicos ou irregulares, por exemplo, cobrando o cliente após a prestação de um serviço.

Exemplo de link de pagamento:

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

Antes de atribuir um valor a payment_sum, você pode definir variáveis opcionais adicionais para personalizar o pagamento.

Por padrão, a moeda do pagamento é o rublo bielorrusso (BYN). Se você quiser usar outra moeda, atribua um valor à variável currency.

Após a conclusão do pagamento, a variável bepaid_callback_data é adicionada ao cliente. Ela contém a resposta do sistema de pagamento para a transação concluída.

Você pode recuperar os valores necessários deste dicionário usando a função get().

Como Testar Pagamentos

Para realizar um pagamento de teste, atribua qualquer valor à variável test_payments antes de definir a variável payment_sum.

Importante: Remova a variável test_payments antes de colocar seu bot em modo de produção.

Cartões de Teste

Número do Cartão Resultado
4200000000000000 Pagamento bem-sucedido
4005550000000019 Pagamento falhou

O exemplo a seguir gera um link de pagamento para 100 rublos bielorrussos (moeda padrão).

Nota: Primeiro atribua quaisquer variáveis de configuração adicionais, depois atribua o valor a payment_sum. Essas variáveis também podem ser atribuídas anteriormente em seu fluxo de trabalho — elas não precisam estar no mesmo bloco.

Finalmente, exiba a variável bepaid_pay_url onde necessário. Ela contém o link de pagamento gerado.

Gerenciamento de Assinaturas

A integração bePaid permite criar assinaturas para seus clientes.

Antes de usar esta funcionalidade no MaviBot, crie um plano de assinatura em sua conta bePaid.

Se as seções Planos e Assinaturas não estiverem disponíveis em sua conta, entre em contato com seu gerente de conta.

Use a função get_bepaid_subscription_url e passe o parâmetro plan_id.

A função cria uma assinatura e retorna um link de pagamento.

Envie o link gerado para o cliente e aguarde a conclusão do pagamento.

Após um pagamento bem-sucedido:

  • a assinatura é ativada;
  • o negócio recebe as variáveis:
    • bepaid_subscription_id;
    • bepaid_subscription_status;
  • um callback é enviado para o bot (consulte Como Lidar com o Resultado).

Recuperando Informações da Assinatura

Para recuperar as informações atuais da assinatura, use a função get_bepaid_subscription_info.

Passe o parâmetro subscription_id. Seu valor pode ser obtido da variável bepaid_subscription_id.

Cancelando uma Assinatura

Para cancelar uma assinatura, use a função cancel_bepaid_subscription.

A função aceita um único parâmetro:

  • subscription_id — o valor pode ser obtido da variável bepaid_subscription_id.

Após um cancelamento bem-sucedido:

  • a variável bepaid_subscription_status é definida como "canceled";
  • um callback é enviado para o bot (consulte Como Lidar com o Resultado).

Status das Assinaturas

Status Descrição
trial Assinatura de período de teste ativa ou cancelada.
active Assinatura ativa com pagamento feito em dia.
failed Assinatura falhou. bePaid não conseguiu processar o próximo pagamento.
error Ocorreu um erro enquanto bePaid tentava processar o pagamento.
canceled Assinatura foi cancelada e não está mais ativa.

Pagamentos Recorrentes

Você também pode configurar pagamentos recorrentes sem criar um plano de assinatura em sua conta bePaid.

Para isso, você precisa do token do cartão do cliente.

Obtendo um Token de Cartão

Para obter o token do cartão do cliente, o cliente deve concluir um pagamento inicial usando um link de pagamento gerado com a variável payment_sum.

Antes de atribuir um valor a payment_sum, defina a variável bepaid_contract para definir a finalidade de futuros pagamentos baseados em token.

Valores suportados:

  • recurring — para pagamentos recorrentes com um cronograma predefinido.
  • card_on_file — para pagamentos únicos ou irregulares, por exemplo, cobrando o cliente após a prestação de um serviço.

Nota: A opção card_on_file não é suportada por todos os bancos adquirentes. Entre em contato com seu gerente de conta se planeja usar esta opção.

Após um pagamento bem-sucedido, a variável bepaid_client_card_token é adicionada ao negócio. Ela armazena o token do cartão do cliente, que pode ser usado para pagamentos futuros sem interação do cliente.

Em seguida, configure seu fluxo de trabalho, defina a data ou condição necessária para cobrar o cliente e chame a função make_bepaid_token_payment.

Os parâmetros devem ser passados na seguinte ordem:

amount → currency → description → contract

Descrições dos Parâmetros

O valor do parâmetro contract deve corresponder exatamente ao valor especificado ao gerar o link de pagamento inicial.

Parâmetro Descrição
amount (obrigatório) Valor do pagamento. O valor deve ser um número inteiro ou decimal, por exemplo: 100 ou 100.5.
currency (obrigatório) Moeda do pagamento no formato ISO 4217, por exemplo: USD.
description (obrigatório) Descrição do pagamento, por exemplo: "Pagamento semanal de assinatura para participação no clube de hobby".
contract (obrigatório) Finalidade do pagamento por token. Valores permitidos: recurring ou card_on_file.

Se o pagamento for bem-sucedido:

  • a função retorna a mensagem "Cobrança bem-sucedida via token bePaid";
  • o bot recebe um callback de pagamento bem-sucedido;
  • a variável bepaid_token_payment_completed é definida como True.

Se o pagamento falhar:

  • a função retorna uma mensagem descrevendo o motivo da falha;
  • o bot recebe um callback com o sufixo _fail;
  • a variável bepaid_token_payment_completed é definida como False.

Se o banco exigir verificação adicional do cliente, a função retorna um link onde o cliente pode concluir a autenticação 3-D Secure.

Como Lidar com o Resultado

Em resposta às ações do cliente, o bot recebe callbacks que consistem nos primeiros 20 caracteres da chave secreta seguidos por um sufixo indicando o tipo de operação e resultado.

O callback aparece no sistema como uma mensagem de usuário, mas não é visível para o cliente.

Callbacks de Pagamento

Para pagamentos únicos, o bot recebe um dos seguintes callbacks:

  • keyNumber_success — pagamento bem-sucedido.
  • keyNumber_fail — pagamento falhou.

Você também pode acompanhar o resultado do pagamento usando as seguintes variáveis:

  • bepaid_payment_completed — pagamento concluído pelo cliente.
  • bepaid_token_payment_completed — pagamento automático concluído usando o token do cartão do cliente.

Callbacks de Assinatura

Após uma assinatura ser ativada com sucesso, seja durante o pagamento inicial ou um pagamento recorrente, o bot recebe:

keyNumber_success

Se a assinatura for cancelada, o bot recebe:

keyNumber_canceled

Se um pagamento de assinatura falhar, o bot recebe:

keyNumber_fail