Stripe

Como conectar

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

Você pode copiar a chave secreta de API acessando a seção Developers -> API key e copiando a Secret key.

Passo 1. Vá para a seção Developers -> API key:

Passo 2. Encontre e copie a Secret key:

Em seguida, você precisa definir a URL para callbacks. Isso é necessário para que o bot receba notificações de pagamento.

Vá para a seção Webhooks e adicione o endereço para os webhooks.

O formulário é aberto:

Passo 1. Clique em "+add destination".

Passo 2. Selecione os eventos:

Passo 3. Selecione o tipo de "Webhook endpoint":

Passo 4. Conhecemos o tipo de solicitação e clicamos em "Continue":

Passo 5. Inserimos o nome e especificamos a URL do endpoint:

Especificar URL - https://chatter.salebot.pro/stripe_callback/result

Passo 6. Dois endpoints serão criados; você pode visualizar as configurações antes de adicionar:

Passo 7. Em seguida, clique no botão "Add destinations". Depois disso, os webhooks serão salvos.

Passo 8. Clique no botão "Done".

Salvamos e vamos para a página com o webhook instalado:

Passo 9. Em seguida, clique no webhook em que você selecionou todos os eventos:

Passo 10. Encontramos a Signig key e a salvamos para nós (no futuro precisaremos dela para conectar ao Salebot):

Depois de receber as chaves, prosseguimos para a conexão com o Mavibot.

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

Na página de conexão, você precisa inserir as chaves recebidas:

Clique em "Save Settings".

Pronto!

Isso conclui a conexão do sistema de pagamento!

Como conectar um callback sobre o status da transação

Para obter um callback adicional, precisaremos conectar um webhook em além do existente.

Especificar URL - https://chatter.salebot.pro/stripe_callback/<api_key>/charge_status

e selecione os eventos:

charge.failed
charge.pending
charge.succeeded

Saiba mais sobre cada tipo de webhook:

charge.succeeded - contém informações sobre a conclusão bem-sucedida da transação (semelhante a um callback sobre um pagamento bem-sucedido)
charge.pending - "a transação está em andamento", ela pode levar até 7 dias para ser concluída. O webhook ficará como {primeiros 10 caracteres}{tipo de webhook} Por exemplo: sk_test_45LDPJLKT95d_charge.pending
charge.failed - "a transação falhou." O webhook ficará como {primeiros 10 caracteres}{tipo de webhook} Por exemplo: sk_test_45LDPJLKT95d_charge.failed

Adicionamos o webhook recebido após salvar no campo do Mavibot - Webhook key2:

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

Como conectar impostos

Para usar impostos nos pagamentos, primeiro você precisa criá-los na conta pessoal do Stripe. Para isso, digite tax rates na barra de pesquisa:

E clique em "+ Add tax rates":

Em seguida, especifique a taxa de imposto aplicável:

No menu aberto, selecione o tipo de imposto, a região em que ele se aplica, a taxa de imposto e a opção indicando se esse imposto deve ser incluído no valor do pagamento como 'Inclusive' ou se será adicionado ao valor como extra - exclusive:

Após criar a taxa de imposto, copie o ID dela para a stripe_tax_id variável antes de definir o valor do pagamento.

Para evitar erros, coloque uma string vazia ("") na variável stripe_tax_id após receber o link, para que você possa aplicar o imposto apenas quando necessário.

Se tudo for feito corretamente, então, no caso da taxa de imposto com o parâmetro exclusive, você verá o seguinte

Como obter o link de pagamento

Para gerar um link de pagamento, você precisa definir o valor da payment_sum variável (por exemplo, 150 ou 100,55 (separado por ponto!)), e depois disso a variável stripe_pay_url aparecerá. Essa variável pode ser exibida com um link ou colocada em um botão com o texto "Pagar".

O link se parece com:

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

Por padrão, USD (dólar) está definido; se precisar de outra moeda, você precisa definir o valor da currency variável.

Além disso, antes de definir o valor da payment_sum variável, você pode definir as seguintes variáveis opcionais para configurar o pagamento.

Parâmetros da função

Descrição dos parâmetros

currency

é a moeda do pedido. Valores aceitos -https://stripe.com/docs/currencies

payment_description

descrição do pedido

stripe_tax_id

Este é o ID da taxa de imposto, configurado na conta pessoal do Stripe. Como configurá-lo está descrito na seção "Como configurar impostos" ссылка "Como conectar impostos"

stripe_invoice_enable

Este parâmetro indica a necessidade de salvar faturas (invoices, receipts). Insira qualquer valor — todos os documentos necessários ficarão então disponíveis na sua conta pessoal do Stripe.

stripe_locale

define o idioma do link de pagamento: en, ru, de. Todos os idiomas disponíveis estão aqui: https://stripe.com/docs/api/checkout/sessions/create#create_checkout_session-locale Se o stripe_local se nenhum valor for fornecido, o idioma do navegador do cliente será usado por padrão.

stripe_payment_method_type

é o método de pagamento; por padrão, o pagamento é feito por cartão. Você pode substituí-lo por outros métodos de pagamento disponíveis no Stripe. Os métodos disponíveis estão listados abaixo

client_id = 1202020202 stripe_payment_method_type = "customer_balance"

stripe_additional_payment_method_type

serve para adicionar um método de pagamento adicional. Os métodos disponíveis estão listados abaixo, por exemplo, stripe_additional_payment_method_type = "sepa_debit"

coupon_id

ID do cupom de desconto

stripe_expired

é o tempo de validade do link de pagamento. Especificado em segundos. O tempo mínimo é 30 minutos, o máximo é 24 horas. O padrão é 24 horas

stripe_automatic_tax

habilita o cálculo e a cobrança automática de impostos durante o pagamento. Para ativá-lo, passe "1". Informações detalhadas sobre essa configuração podem ser encontradas na documentação do Stripe. ссылка na documentação do Stripe

Atenção! Se você usar ambas stripe_payment_method_type e stripe_additional_payment_method_type variáveis, então os valores nelas DEVEM ser DIFERENTES!

Lista de valores para stripe_payment_method_type e stripe_additional_payment_method_type

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

Mais detalhes sobre cada um dos métodos e para quais países eles estão disponíveis podem ser encontrados na documentação do Stripe: ver no site

Exemplo de geração do link de pagamento

Vamos criar um link de pagamento no valor de 1000 rublos (por padrão, dólar)

Atenção: - Primeiro você define parâmetros opcionais first_name, payment_description e assim por diante. - E por último atribuímos o valor à variável payment_sum

As variáveis também podem ser definidas antes na sequência, e não em um único bloco; este é apenas um exemplo.

Em seguida, no local desejado, exibimos a variável stripe_pay_url, que contém o link no bloco ou no botão:

Exemplo 1. Exibimos o link de pagamento diretamente na mensagem:

Teste no bot:

Exemplo 2. Adicionamos o link de pagamento em um botão:

Exemplo 3. Adicionamos o link como anexo à mensagem:

Teste no bot:

Todos os três formatos são permitidos para enviar o link de pagamento no bot.

Ao clicar no botão ou ao acessar o link, o pagador será redirecionado para a página de pagamento:

No exemplo, é видно que os parâmetros que indicamos na calculadora nas configurações do bloco foram aplicados: descrição do pedido, moeda e valor.

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

Então a taxa de imposto também será exibida no formulário de pagamento:

Exemplo de código para copiar

payment_description = 'Pagamento de teste no Stripe' currency = 'RUB' stripe_tax_id = 'copie aqui o seu tax ID' payment_sum = 1000

Onde encontrar o tax ID:

Como configurar pagamentos recorrentes

Para pagamentos recorrentes (assinaturas), é necessário, antes de declarar a variável payment_sum declarar a variável stripe_subscription e atribuir a ela o nome da assinatura.

Também é possível adicionar as seguintes variáveis: interval – duração do intervalo da assinatura; nessa variável é preciso passar o valor ‘day’ - para dias, ‘week’ - semanas, ‘month’ - meses, ‘year’ - anos. Se a variável não for declarada, então por padrão será passado o parâmetro ‘month’.

Importante! A duração de um ciclo de assinatura não pode ser superior a 1 ano (para o parâmetro ‘year’), mais de 12 meses (para o parâmetro ‘month’) e mais de 52 semanas (para o parâmetro ‘week’).

interval_count – quantidade de intervalos especificados; quantos dias, semanas ou meses haverá na assinatura pelo valor indicado. Por padrão será passado o parâmetro igual a um (1);

stripe_payment_method_type - método de pagamento; por padrão, o pagamento é feito por cartão (card). Você pode substituí-lo por outros métodos de pagamento disponíveis no Stripe. Abaixo estão listados os métodos disponíveis.

Por exemplo, stripe_payment_method_type = 'customer_balance'

stripe_additional_payment_method_type - adicionar um método de pagamento adicional. Abaixo estão listados os métodos disponíveis

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, então os valores nelas DEVEM ser DIFERENTES!

Lista de valores para stripe_payment_method_type e stripe_additional_payment_method_type:

Para mais informações sobre cada um dos métodos e para quais países eles estão disponíveis, consulte a documentação do Stripe: veja o site ссылка ver no site

Atenção! A duração da assinatura não pode exceder 1 ano (para o parâmetro ‘year’), mais de 12 meses (para o parâmetro ‘month’) e mais de 52 semanas (para o parâmetro ‘week’).

Neste exemplo, será criada uma assinatura chamada 'My_subscription' com o valor de 90 USD por 3 meses, e um pagamento recorrente será feito com o mesmo valor após esse 1 mês:

Um exemplo para copiar:

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

Após o pagamento, o cliente terá stripe_subscription_id variáveis nas variáveis do negócio, que serão necessárias para configurar o cancelamento da assinatura, e stripe_customer_id, que depois poderá ser usado para verificar o status da assinatura.

A notificação (callback) é recebida apenas no primeiro pagamento recorrente!

NÃO HAVERÁ callback para chamadas repetidas. O controle ocorre pela função e pelo stripe_customer_id. por meio da função ссылка

Retornando às configurações de pagamentos regulares

Para voltar aos pagamentos regulares, atribua à variável de assinatura uma string vazia stripe_subscription = ". Nesse caso, as variáveis interval e interval_count não afetarão a criação do link.

Cancelando as configurações da assinatura

Para cancelar uma assinatura na calculadora, use o stripe_remove_subscription(stripe_subscription_id) método, onde stripe_subscription_id é o identificador que foi salvo nas informações do negócio após o pagamento.

Isso permitirá que você mantenha sua assinatura paga ativa até o fim do período pago atual, mas não haverá mais cobranças, e a assinatura será cancelada após a data de expiração:

answer = stripe_remove_subscription('#{stripe_subscription_id}')

stripe_remove_subscription - Em caso de sucesso, você receberá uma resposta com informações sobre a data até a qual a assinatura cancelada permanece válida.

Neste exemplo, o resultado da execução da função será colocado na variável answer e será possível verificar o resultado da execução.

Verificando o status da assinatura

stripe_check_subscription(subscription_id, customer_id), onde

stripe_subscription_id - ID da assinatura stripe_customer_id - ID do cliente no Stripe (parâmetro opcional)

Como criar um cupom e obter um ID de desconto

Para receber o ID do desconto, crie um cupom na sua conta pessoal na seção “coupons”. ссылка ”coupons”.

Depois de clicar no botão “New”, abre-se uma página onde você precisa especificar:

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

O cupom de desconto aparecerá no “Catálogo de produtos” na seção “Coupons”, e você poderá ver o ID do desconto acessando o menu do cupom:

Clique no cupom para copiar o ID do cupom:

Como adicionar um desconto ao pedido

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

Na calculadora do bloco, antes de declarar a payment_sum defina a variável coupon_id variável, atribuindo a ela o ID do desconto da conta pessoal do Stripe.

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

Defina as condições para acionar o bloco e chame a função especificada na calculadora, passando a ela 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.

Exemplo de código para copiar

stripe_subscription = 'Assinatura premium' interval = 'month' payment_description = 'Pagamento de teste no Stripe' currency = 'USD' coupon_id = 'ID do seu cupom' stripe_add_subscription_discount(stripe_subscription_id, coupon_id) stripe_tax_id = 'ID do imposto' payment_sum = 90

Após a adição bem-sucedida, a função retorna uma mensagem indicando o ID da assinatura, o tipo, o valor ou percentual do desconto e também sua data de expiração.

Para mais informações sobre como criar uma assinatura, consulte a seção "Como configurar pagamentos recorrentes" ссылка "Como configurar pagamentos recorrentes"

Como excluir/alterar o desconto da assinatura

O desconto vinculado à assinatura pode ser excluído ou substituído por outro desconto.

Se você quiser encerrar o desconto, defina uma condição para acionar o bloco e chame a stripe_remove_subscription_discount função na calculadora, passando a ela o stripe_subscrition_id parâmetro (ID da assinatura).

Após a conclusão bem-sucedida da operação, a função retorna uma mensagem contendo o ID da assinatura e a data de cancelamento do desconto.

A substituição do desconto, assim como a adição de um novo, é feita usando stripe_add_subscription_discount função. Não se esqueça de passar os stripe_subscription_id e coupon_id parâmetros a ela. Uma solicitação bem-sucedida atualizará o cupom vinculado à assinatura e retornará uma mensagem com as informações atuais.

Você pode ler como obter um ID de desconto na seção "Como criar um cupom e obter um ID de desconto". ссылка "Como criar um cupom e obter um ID de desconto".

Como processar o resultado

Após um pagamento bem-sucedido, callbacks serão enviados ao bot, o que permitirá que você saiba que o pagamento foi realizado com sucesso. Você vê esses callbacks no sistema como mensagens do usuário; para que o usuário não possa enviá-las, eles consistem nos primeiros 20 caracteres da chave secreta e no sufixo de sucesso, por exemplo: sk_live_d35gky6d8ers_success

Esses callbacks NÃO SÃO VISÍVEIS PARA o usuário, eles são exibidos apenas para o operador.

O tipo de comparação deve ser "Correspondência exata"

Além disso, após o pagamento bem-sucedido, a stripe_payment_completed variável é definida como True.

Por exemplo, você pode processar um pagamento bem-sucedido em um bloco condicional e exibir a mensagem correspondente ao usuário:

Após a conclusão do pagamento, a variável stripe_callback_data variável será adicionada ao cliente, contendo os dados da resposta do sistema de pagamento para a transação concluída. Você pode extrair os dados necessários do dicionário resultante usando o get .

Para fazer um pagamento repetido, você precisa redefinir o payment_sum, o link gerado anteriormente e, então, reatribuir a variável payment_sum para obter um novo link. Você pode especificar o valor anterior.

Como testar pagamentos

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

Em seguida, faça a configuração descrita no início deste guia. Insira a chave secreta de teste e adicione o endereço do webhook ao ambiente de testes.

O número do cartão de teste

4242 4242 4242 4242 qualquer data no futuro CVC - quaisquer três números

Se algo não funcionar, compare os dados com os dados no site oficial. ссылка no site oficial.

Atualizado há 4 meses