Stripe

Como conectar

Para conectar o sistema de pagamento Stripe, você precisará de uma chave de API secreta e uma chave de webhook.

A chave de API secreta pode ser copiada acessando Developers → API keys e copiando a Secret key.

Passo 1. Acesse Developers → API keys:

Passo 2. Encontre e copie a Secret key:

Em seguida, você precisa definir uma URL de callback. Isso permite que o bot receba notificações de pagamento.

Acesse a seção Webhooks e adicione a URL do webhook.

Um formulário será exibido.

Passo 3. Clique em "+ add destination".

Passo 4. Selecione eventos.

Passo 3. Selecione o tipo "Webhook endpoint".

Passo 4. Revise o tipo de requisição e clique em "Continue".

Passo 5. Insira um nome e especifique a URL do endpoint.

Defina a URL como: https://chatter.mavibot.ai/stripe\\_callback/result

Passo 6. Dois endpoints serão criados — você pode revisar as configurações antes de adicioná-los.

Passo 7. Clique no botão "Add destinations". Os webhooks serão salvos.

Passo 8. Clique em "Done".

Salve e você será levado à página com o webhook configurado.

Passo 9. Clique no webhook onde você selecionou todos os eventos.

Passo 10. Encontre a Signing key e salve-a (você precisará dela depois para conectar ao MaviBot).

Depois de obter as chaves, prossiga para conectar no Mavibot.

No Mavibot, abra a seção "Acquiring" e selecione Stripe.

Na página de conexão, insira as chaves que você obteve.

Clique em "Save settings".

Pronto! Você conectou o Stripe.

Como conectar um callback de status de transação

Para receber um callback adicional, você precisa adicionar um segundo webhook junto com o existente.

Defina a URL como: https://chatter.mavibot.ai/stripe\\_callback/\\<api_key>/charge_status

e selecione os seguintes eventos:

• charge.failed
• charge.pending
• charge.succeeded

Mais detalhes sobre cada tipo de webhook:

1. charge.succeeded — contém informações sobre uma transação concluída com sucesso (semelhante ao callback de pagamento bem-sucedido)
2. charge.pending — "transação em andamento", pode levar até 7 dias para ser concluída. O webhook terá o formato {primeiros 10 caracteres}{tipo de webhook} Por exemplo: sk_test_45LDPJLKT95d_charge.pending
3. charge.failed — "transação falhou". O webhook terá o formato {primeiros 10 caracteres}{tipo de webhook} Por exemplo: sk_test_45LDPJLKT95d_charge.failed

Adicione a chave do webhook obtida após salvar no campo do Mavibot — Webhook key2.

stripe_invoice_id — o identificador da transação para a qual um callback de pagamento bem-sucedido não foi recebido imediatamente após o pagamento.

Como configurar impostos

Para usar impostos nos pagamentos, você primeiro precisa criá-los no seu painel do Stripe. Para fazer isso, digite "tax rates" na barra de pesquisa:

E clique em "+ Add tax rates".

Em seguida, insira a taxa de imposto aplicável.

No menu que se abre, selecione o tipo de imposto, a região a que se aplica, a porcentagem e se o imposto será incluído no valor do pagamento (Inclusive) ou adicionado a ele (Exclusive).

Após criar a taxa de imposto, copie seu ID na variável stripe_tax_id antes de declarar o valor do pagamento.

Para evitar erros, é recomendado definir a variável stripe_tax_id como uma string vazia ("") após receber o link — assim você pode aplicar o imposto apenas quando necessário.

Se feito corretamente, no caso de uma taxa de imposto com o parâmetro exclusive, você verá o seguinte:

Como obter um link de pagamento

Para gerar um link de pagamento, defina o valor da variável payment_sum (por exemplo, 150 ou 100.55 — use um ponto, não uma vírgula!). Depois disso, a variável stripe_pay_url aparecerá. Você pode exibir essa variável como um link ou colocá-la em um botão com o texto "Pay".

O link se parece com isto:

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

Por padrão, a moeda é definida como USD. Para usar uma moeda diferente, defina o valor da variável currency.

Você também pode definir as seguintes variáveis opcionais antes de definir o valor de payment_sum para configurar o pagamento.

Importante! Se você usar ambas as variáveis stripe_payment_method_type e stripe_additional_payment_method_type, os valores nelas devem 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 mais detalhes sobre cada método e os países onde estão disponíveis, consulte a documentação do Stripe

Exemplo de geração de link de pagamento

Vamos criar um link de pagamento para 1000 AED (a moeda padrão é USD).

Nota:

— Primeiro, especifique os parâmetros opcionais como first_name, payment_description, etc.

— Em seguida, atribua o valor à variável payment_sum por último.

As variáveis também podem ser definidas anteriormente na cadeia, não necessariamente no mesmo bloco — isso é apenas um exemplo.

Em seguida, exiba a variável stripe_pay_url, que contém o link, no ponto desejado — seja em um bloco de mensagem ou em um botão:

Exemplo 1. Exibir o link de pagamento diretamente em uma mensagem:

Exemplo 2. Adicionar o link de pagamento a um botão.

Quando o botão for clicado ou o link for seguido, seu pagador será redirecionado para a página de pagamento.

O exemplo mostra que os parâmetros que especificamos na calculadora nas configurações do bloco foram aplicados: descrição do pedido, moeda e valor.

Se você passar o parâmetro da taxa de imposto (stripe_tax_id) no bloco.

A taxa de imposto também será exibida no formulário de pagamento.

payment_description = "test payment"

currency = 'AED'

stripe_tax_id = 'enter_your_stripe_id_tax'

payment_sum = 1000

Onde encontrar o ID do imposto.

Como configurar pagamentos recorrentes

Para pagamentos recorrentes (assinaturas), declare a variável stripe_subscription antes da variável payment_sum e atribua a ela o nome da assinatura.

Você também pode adicionar as seguintes variáveis: interval — a duração do intervalo da assinatura. Passe 'day' para dias, 'week' para semanas, 'month' para meses ou 'year' para anos. Se a variável não for definida, 'month' será usado por padrão.

Importante!

A duração de um ciclo de assinatura não pode exceder 1 ano (para o parâmetro 'year'), 12 meses (para o parâmetro 'month') ou 52 semanas (para o parâmetro 'week').

interval_count — o número de intervalos especificados: quantos dias, semanas ou meses estão incluídos na assinatura para o valor determinado. O padrão é 1.

stripe_payment_method_type — o método de pagamento; o padrão é pagamento com cartão. Pode ser substituído por outros métodos de pagamento disponíveis no Stripe. Os métodos disponíveis estão listados abaixo.

Por exemplo, stripe_payment_method_type = 'customer_balance'

stripe_additional_payment_method_type — adicione um método de pagamento adicional. Os métodos disponíveis estão listados abaixo.

Por exemplo, stripe_additional_payment_method_type = 'sepa_debit'

Importante! Se você usar ambas as variáveis stripe_payment_method_type e stripe_additional_payment_method_type, os valores nelas DEVEM 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 mais detalhes sobre cada método e os países onde estão disponíveis, consulte a documentação do Stripe.

Importante!

A duração de um ciclo de assinatura não pode exceder 1 ano (para o parâmetro 'year'), 12 meses (para o parâmetro 'month') ou 52 semanas (para o parâmetro 'week').

Neste exemplo, uma assinatura chamada 'My_subscription' será criada com um preço de 1000 AED por 1 mês, e um pagamento recorrente do mesmo valor será cobrado após 1 mês.

Copiar exemplo:

stripe_subscription = 'My_subscription' interval = 'month' payment_sum = 90

Para cobrar o pagamento da assinatura uma vez a cada dois, três ou quatro meses, passe o parâmetro interval_count:

stripe_subscription = 'My_subscription'

interval = 'month'

interval_count = 3

payment_sum = 90

Para alterar o intervalo de pagamento da assinatura de mensal para semanal, passe a palavra week no parâmetro interval:

stripe_subscription = 'My_subscription'

interval = 'week'

interval_count = 3

payment_sum = 90

Após o pagamento, as variáveis de transação do cliente incluirão stripe_subscription_id, que é necessário para configurar o cancelamento da assinatura, e stripe_customer_id, que pode ser usado posteriormente para verificar o status da assinatura.

A notificação (callback) é enviada apenas para o primeiro pagamento recorrente!

NÃO haverá callback para pagamentos subsequentes. O rastreamento é feito através da função e stripe_customer_id.

Configurações para retornar a pagamentos regulares

Para retornar a pagamentos regulares, atribua uma string vazia à variável de assinatura: stripe_subscription = ''. Neste caso, as variáveis interval e interval_count não afetarão a geração do link.

Configurações para cancelar uma assinatura

Para cancelar uma assinatura na calculadora, use o método stripe_remove_subscription(stripe_subscription_id), onde stripe_subscription_id é o identificador salvo nas variáveis de transação após o pagamento.

Isso manterá a assinatura paga ativa até o final do período de cobrança atual, mas nenhuma cobrança adicional ocorrerá, e a assinatura será cancelada quando o período expirar.

answer = stripe_remove_subscription('#{stripe_subscription_id}')

stripe_remove_subscription — em caso de sucesso, retorna uma resposta com informações sobre a data até a qual a assinatura cancelada permanecerá ativa.

Neste exemplo, o resultado da função será armazenado na variável answer, permitindo que você verifique o resultado.

Verificando o status da assinatura

stripe_check_subscription(subscription_id, customer_id), onde

stripe_subscription_id — identificador da assinatura stripe_customer_id — identificador do cliente no Stripe (parâmetro opcional)

Como criar um cupom e obter um ID de desconto

Para obter um identificador de desconto, crie um cupom no seu painel na seção "Coupons". ”coupons”.

Clicar no botão "New" abrirá uma página onde você precisa especificar:

1. Name — o nome do desconto;
2. ID — o identificador, gerado automaticamente;
3. Type — o tipo de desconto: percentual ou valor fixo;
4. Duration — a duração do desconto (único ou contínuo, por exemplo, para assinaturas) e outros parâmetros.

O cupom de desconto aparecerá no "Product catalogue" na seção "Coupons", e você pode visualizar o ID do desconto abrindo o menu do cupom.

Clique no cupom para copiar o ID do cupom.

Como aplicar um desconto a um pedido

1. Ao gerar um link de pagamento (funciona tanto para assinaturas quanto para pagamentos únicos).

Na calculadora do bloco, antes de declarar a variável payment_sum, defina a variável coupon_id e passe o identificador de desconto do seu painel do Stripe.

2. Para uma assinatura existente usando a função stripe_add_subscription_discount.

Defina as condições de acionamento do bloco e chame a função especificada na calculadora, passando os parâmetros stripe_subscription_id (ID da assinatura) e coupon_id (ID do cupom de desconto). O desconto será aplicado aos pagamentos subsequentes da assinatura.

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

Se o desconto for aplicado com sucesso, a função retornará uma mensagem com o ID da assinatura, tipo de desconto, valor ou porcentagem e data de expiração.

Como remover ou alterar um desconto para uma assinatura

Um desconto anexado a uma assinatura pode ser removido ou substituído por outro desconto.

Para interromper um desconto, defina as condições de acionamento do bloco e chame a função stripe_remove_subscription_discount na calculadora, passando o parâmetro stripe_subscription_id (ID da assinatura).

Se a operação for bem-sucedida, a função retornará uma mensagem contendo o ID da assinatura e a data de cancelamento do desconto.

Substituir um desconto, assim como adicionar um novo, é feito usando a função stripe_add_subscription_discount. Certifique-se de passar os parâmetros stripe_subscription_id e coupon_id. Uma solicitação bem-sucedida atualizará o cupom anexado à assinatura e retornará uma mensagem com os detalhes atualizados.

Como lidar com o resultado

Após um pagamento bem-sucedido, o bot receberá callbacks que indicam uma transação bem-sucedida. No sistema, esses callbacks aparecem como mensagens do usuário. Para evitar que os usuários os enviem manualmente, eles consistem nos primeiros 20 caracteres da chave secreta seguidos por _success, por exemplo: sk_live_d35gky6d8ers_success

Esses callbacks NÃO são visíveis para o usuário — eles são visíveis apenas para o operador.

O tipo de comparação deve ser definido como "Exact match".

Após um pagamento bem-sucedido, a variável stripe_payment_completed também é definida como True.

Por exemplo, você pode lidar com um pagamento bem-sucedido usando um bloco condicional e exibir a mensagem apropriada para o usuário.

Após a conclusão do pagamento, a variável stripe_callback_data será adicionada aos dados do cliente, contendo a resposta do sistema de pagamento para a transação concluída. Os dados necessários podem ser extraídos do dicionário resultante usando o método get.

Para processar um pagamento repetido, você deve primeiro redefinir payment_sum e o link gerado anteriormente, e só então reatribuir a variável payment_sum para obter um novo link. Você pode usar o valor anterior.

Como testar pagamentos

Para testar a integração, você pode usar a chave secreta do ambiente de teste. Para fazer isso, mude para o ambiente de teste no painel do Stripe usando o menu à direita.

Em seguida, siga as etapas de configuração descritas no início deste guia. Insira a chave secreta de teste e adicione a URL do webhook no ambiente de teste.

Para teste, use um número de cartão de pagamento de teste (você pode encontrar o número do cartão para o seu país no site oficial do Stripe).