Stripe
Conecte a Stripe com uma chave restrita e a chave publicável. O webhook é criado automaticamente.
A Stripe recebe cartão e, em contas brasileiras, também Pix e boleto. A MinePag usa uma chave restrita da sua conta, só com as permissões necessárias, e o dinheiro cai direto no seu saldo da Stripe.
O que você vai precisar
| Campo no painel | Formato | Onde encontrar |
|---|---|---|
| Chave restrita | rk_live_… (Produção) ou rk_test_… (Sandbox) | Desenvolvedores › Chaves de API › Criar chave restrita |
| Chave publicável | pk_live_… (Produção) ou pk_test_… (Sandbox) | Desenvolvedores › Chaves de API |
As duas chaves precisam ser do mesmo modo: as duas de produção ou as duas de teste.
Prefira a chave restrita
A MinePag também aceita a chave secreta padrão (sk_…), mas ela dá acesso total à sua conta Stripe. A chave restrita limita o que a MinePag pode fazer ao mínimo necessário e pode ser revogada sem afetar outros sistemas.
Permissões da chave restrita
Ao criar a chave restrita, marque exatamente estas permissões e deixe os demais recursos como Nenhuma:
| Recurso | Permissão | Para quê |
|---|---|---|
| PaymentIntents | Gravação | Criar e consultar as cobranças do checkout. |
| Refunds | Gravação | Reembolsar pedidos pelo painel e pela API. |
| Webhook Endpoints | Gravação | Criar e remover o webhook da MinePag. |
| Charges | Leitura | Importar o histórico e conferir pagamentos. |
| Disputes | Leitura | Saber se uma contestação foi ganha e devolver os acessos do pedido. |
| Balance | Leitura | Validar a chave ao conectar. |
| Accounts | Leitura | Mostrar o nome da conta no painel e impedir que novas credenciais troquem de conta sem desconectar. |
Passo a passo
Crie a chave restrita
No Dashboard da Stripe, abra Desenvolvedores › Chaves de API e clique em Criar chave restrita. Dê um nome (por exemplo, "MinePag") e marque as permissões da tabela acima.
Para Sandbox, faça isso com o Dashboard em modo de teste.
Copie as chaves
Copie a chave restrita (rk_live_… ou rk_test_…) e a chave publicável (pk_live_… ou pk_test_…) do mesmo modo.
Ative Pix e boleto (opcional)
Para vender com Pix e boleto, ative essas formas de pagamento em Configurações › Formas de pagamento no Dashboard da Stripe. Elas só existem para contas brasileiras.
Conecte na MinePag
- No painel da loja, abra Configurações › Gateways e clique em Conectar no cartão da Stripe.
- Escolha Produção ou Sandbox e, se quiser, dê um nome à conexão. Clique em Continuar.
- Cole a Chave restrita e a Chave publicável e clique em Continuar.
- Escolha o período de importação e clique em Conectar Stripe.
Ao final, o painel mostra "Webhook registrado no gateway". No Dashboard da Stripe, em Desenvolvedores › Webhooks, aparece um endpoint com a descrição "MinePag". Não altere nem apague esse endpoint: ele é gerenciado pela MinePag.
Webhook
A MinePag cria o endpoint com estes eventos:
payment_intent.succeeded,payment_intent.payment_failed,payment_intent.processing,payment_intent.canceledepayment_intent.requires_actioncharge.refundedecharge.refund.updatedcharge.dispute.createdecharge.dispute.closed
Cada aviso é conferido pelo cabeçalho Stripe-Signature, com tolerância de 5 minutos, e a MinePag consulta o pagamento na Stripe antes de confirmar o pedido. Quando você troca as chaves, a MinePag recria o endpoint. Quando você desconecta, ela o remove assim que não houver mais pagamentos em aberto para conferir.
Limites de valor
| Forma | Valor por pagamento |
|---|---|
| Pix | De R$ 0,50 a R$ 3.000,00 |
| Boleto | De R$ 5,00 a R$ 49.999,99 |
Um pedido fora desses limites é recusado pela Stripe. Se você vende valores fora dessa faixa, use outro gateway para essa forma em Rotas de pagamento.
Reembolsos
| Forma | Reembolso pela MinePag |
|---|---|
| Cartão | Total ou parcial. |
| Pix | Total ou parcial. |
| Boleto | Não é possível. A Stripe não reembolsa boletos pagos. |
Veja Reembolsos e contestações.
Importação de histórico
A MinePag importa as cobranças da conta no período escolhido. A Stripe limita o número de consultas por conta, então a importação é feita aos poucos e pode levar mais tempo em contas com muitas vendas. Veja Importação de histórico.
Mensagens de erro
| Mensagem | Como resolver |
|---|---|
| Chave secreta da Stripe inválida. | Cole a chave completa, começando com rk_live_, rk_test_, sk_live_ ou sk_test_. |
| Chave publicável da Stripe inválida. | Cole a chave completa, começando com pk_live_ ou pk_test_. |
| A chave secreta e a chave publicável precisam ser do mesmo modo (teste ou produção). | Copie as duas com o Dashboard no mesmo modo. |
| Use chaves de produção (rk_live_ e pk_live_) para o ambiente Produção. | Você escolheu Produção, mas colou chaves de teste. |
| Use chaves de teste (rk_test_ e pk_test_) para o ambiente Sandbox. | Você escolheu Sandbox, mas colou chaves de produção. |
| A chave restrita não tem todas as permissões. … | Edite a chave restrita na Stripe e marque as permissões da tabela acima. |
| A Stripe recusou a chave secreta. | A chave foi revogada ou digitada errada. Crie outra e cole de novo. |
Mais casos em Problemas comuns.