Bepaid (ru)
Como conectar
Para conectar o sistema de pagamento bePaid, você precisará do ID da Loja, da chave secreta e da chave pública. Após obtê-las, vamos para as configurações no MaviBot.
No MaviBot, abrimos a seção "Adquirência", selecionamos bePaid. É necessário inserir os dados получidos.
Observe que o último campo é um seletor de hospedagem da API, dependendo do país de uso: Bielorrússia ou Rússia.
Как сформировать ссылку на оплату
Para gerar o link de pagamento, você precisa definir o valor da variável payment_sum (por exemplo, 150 ou 100.55 (com ponto!)); imediatamente depois disso a variável bepaid_pay_url aparecerá. Essa variável pode ser exibida na tela como um link ou размещена em um botão com o texto "Pagar".
O link tem a seguinte aparência: https://checkout.bepaid.by/widget/hpp.html?token=a05eabd3f9368725efbc175614c7d469da08f198cc51916b07fb75e53f9a3e1a
Além disso, antes de definir o valor da variável payment_sum, é possível configurar as seguintes variáveis opcionais para ajustar o pagamento.
Por padrão, está definido o rublo bielorrusso; se precisar de outra moeda, é necessário definir o valor da variável currency
language
idioma da página de pagamento
Por 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
tempo de validade do link de pagamento, no formato dd.mm.aaaa (por exemplo, 25.06.2025).
Por padrão, o pagamento deve ser feito em até 24 horas
Também é possível, no campo "Atribuição de variáveis ao avançar" indicar: link_expired = current_date + 2 (o link será válido por 2 dias até 00:00)
link_expired também é possível indicar uma data com horário exato, separada por espaço, no formato dd.mm.aaaa hh:mm (por exemplo: 25.06.2025 12:23). Por padrão, o pagamento deve ser feito em até 24 horas
Também é possível usar variáveis padrão, por exemplo, vamos definir o prazo de validade do link para 30 minutos:
time = current_time + 30
link_expired = "#{current_date} #{time}"
russian_host
indicador de registro da loja no host russo do bePaid. Especifique este parâmetro com o valor 1 se a sua loja estiver registrada no site bepaid.tech
Se for necessário alternar o host para o bielorrusso, especifique o parâmetro com o valor ''
test_payments
a variável é necessária para pagamentos de teste; se for necessário um pagamento de teste, adicione com qualquer valor.
bepaid_attempts
indica a quantidade de tentativas de realizar o pagamento; por padrão, é dada 1 tentativa.
сustomer_data
um array contendo first_name, last_name e email do pagador. Os dados são necessários para enviar o comprovante por e-mail ao pagador e estão disponíveis para edição na página de pagamento.
O parâmetro deve ser passado como uma lista no formato JSON, composta por pares chave-valor
por exemplo:
customer_data = ‘{“first_name”: “Vladimir”, “last_name”: “Popov”, “email”: “[email protected]” }’
bepaid_contract (condicionalmente obrigatório)
destino do pagamento por token.
Valores esperados: “recurring” (para pagamentos recorrentes com periodicidade definida) ou “card_on_file” (para pagamentos não recorrentes, por exemplo, pós-pagamento por um serviço prestado)
Após a conclusão do pagamento, será adicionada ao cliente a variável bepaid_callback_data, contendo os dados de resposta do sistema de pagamento sobre a operação realizada. Do dicionário obtido, é possível extrair os dados necessários usando o método get.
Como testar pagamentos
Para realizar um pagamento de teste antes de definir a variável payment_sum, é necessário definir a variável test_payments com qualquer valor.
Não se esqueça de removê-la ao iniciar o bot em modo de produção!
Cartões para testes:
4200000000000000 sucesso
4005550000000019 falhou
Se algo não funcionar, compare os dados com os dados do site oficial: https://docs.bepaid.by/ru/test-integration#test-card-number
Exemplo de geração do link de pagamento
Vamos criar um link de pagamento no valor de 100 rublos bielorrussos (moeda padrão)
Observe que primeiro definimos as variáveis adicionais de configuração e depois payment_sum. As variáveis também podem ser definidas anteriormente na cadeia, e não em um único bloco; este é apenas um exemplo.
Em seguida, no local desejado, exibimos a variável bepaid_pay_url, que contém o link
Gerenciamento de assinaturas
A integração com o sistema de pagamento oferece a possibilidade de criar assinaturas para seus clientes.
Antes de começar a usar a funcionalidade do MaviBot, crie um plano de assinatura na conta do bePaid.
Se o menu “Planos” e “Assinaturas” não aparecer na conta, entre em contato com seu gerente.
Criação de assinatura e obtenção do link de pagamento
Use a função get_bepaid_subscription_url, passando para ela o parâmetro plan_id, onde
plan_id
é o ID do plano no sistema bePaid.
Como resultado, a função criará uma assinatura e retornará o link para seu pagamento.
Envie o link ao cliente e aguarde a conclusão do pagamento.
Em caso de pagamento bem-sucedido, a assinatura será ativada, as variáveis bepaid_subscription_id e bepaid_subscription_status serão adicionadas à negociação, e um callback chegará ao bot (veja a seção “Как обработать результат”).
Obtenção de informações sobre a assinatura
Para obter os dados da assinatura atual do cliente, chame a função get_bepaid_subscription_info, passando para ela o parâmetro subscription_id (o valor pode ser obtido da variável bepaid_subscription_id).
Cancelamento da assinatura
Para cancelar a assinatura, use a função cancel_bepaid_subscription.
Essa função aceita um único parâmetro subscription_id (o valor pode ser obtido da variável bepaid_subscription_id).
Em caso de cancelamento bem-sucedido, a variável bepaid_subscription_status assumirá o valor “canceled”, e um callback chegará ao bot (veja a seção “Как обработать результат”).
Status das assinaturas
trial
Assinatura ativa ou cancelada do período de teste.
active
Assinatura ativa, cujo pagamento foi realizado no prazo.
failed
Assinatura com falha. O bePaid não conseguiu processar o próximo pagamento.
error
Ocorreu um erro ao tentar o bePaid processar o pagamento.
canceled
A assinatura foi cancelada e não está mais ativa.
Pagamentos recorrentes
Você também pode organizar um sistema de assinaturas sem criar um plano na conta do bePaid.
Para isso, você precisará do token do cartão do cliente.
Para obter o token do cartão, o cliente deve realizar um pagamento inicial pelo link gerado via payment_sum.
Antes de definir o valor de payment_sum, defina a variável bepaid_contract, na qual especifique a finalidade dos futuros pagamentos por token: “recurring” para pagamentos regulares com periodicidade definida ou “card_on_file” para pagamentos irregulares (por exemplo, pós-pagamento por um serviço prestado).
A opção “card_on_file” não é suportada por todos os adquirentes. Se quiser usá-la, entre em contato com seu gerente de conta.
Após o pagamento bem-sucedido, a variável bepaid_client_card_token será adicionada à negociação, e nela será salvo o token do cartão do cliente. Esse token permite debitar valores do cartão do cliente sem a participação dele.
Em seguida, configure o funil e defina a data ou a condição para o débito automático e chame a função do calculador make_bepaid_token_payment, passando para ela os parâmetros necessários.
Ordem dos parâmetros:
amount -> currency -> description -> contract
Descrição dos parâmetros:
amount (obrigatório)
valor do pagamento; o valor esperado é um número inteiro ou decimal, por exemplo 100 ou 100.5;
currency (obrigatório)
moeda do pagamento em ISO-4217 formato, por exemplo “USD”
description (obrigatório)
descrição do motivo do débito, por exemplo, “Pagamento da assinatura semanal para participação no clube de interesses”;
contract (obrigatório)
destino do pagamento por token. Valores esperados: “recurring” ou “card_on_file”.
O valor de contract deve corresponder obrigatoriamente ao valor indicado ao criar o link para o pagamento de inicialização!
Se o pagamento for realizado com sucesso, a função retornará a mensagem “Débito bem-sucedido pelo token bePaid“, você receberá um callback sobre o pagamento bem-sucedido, e a variável da negociação bepaid_token_payment_completed assumirá o valor “True”.
Se o pagamento não for bem-sucedido, a função retornará uma mensagem indicando o motivo da falha no pagamento, um callback com o sufixo “_fail” chegará ao bot, e a variável da negociação bepaid_token_payment_completed assumirá o valor “False”.
O banco pode solicitar que o cliente conclua o pagamento. Nesse caso, a função retornará um link, com solicitação de autenticação 3-D Secure.
Как обработать результат
Em resposta às ações do cliente, callbacks chegarão ao bot, compostos pelos 20 primeiros caracteres da chave secreta e por um sufixo, dependendo do tipo e do resultado da operação.
No sistema, o callback aparece como uma mensagem do usuário, porém o próprio usuário não o vê.
Para pagamentos
Como resultado de um pagamento que não esteja relacionado a uma assinatura, você receberá uma das mensagens:
numeroChave_success - em caso de pagamento bem-sucedido;
numeroChave_fail - em caso de pagamento malsucedido;
O status do último pagamento também pode ser acompanhado pelas variáveis bepaid_payment_completed (para pagamentos com participação do cliente) e bepaid_token_payment_completed (para pagamentos sem aceite por token de cartão)
Para assinaturas
Após a ativação bem-sucedida da assinatura no primeiro ou em um novo pagamento, uma mensagem chegará ao bot numeroChave_success.
Se a assinatura tiver sido cancelada, você receberá numeroChave_canceled.
Em caso de pagamento malsucedido da assinatura, você receberá uma mensagem numeroChave_fail.
Atualizado