PT
Obtenha o NexCMP grátis
Aplica-se ao NexCMP 1.6.1·Atualizado ·Ver como Markdown

Stripe ​

Onde no admin: Finance › Payment channels › Stripe (/payments/stripe). Chaves e taxas: Finance › Payment channels › Fees & limits (/payments/fees).

O que faz ​

O Stripe aceita pagamentos com cartão para recargas de carteira. Com a mesma conta, você também pode oferecer Apple Pay, Google Pay, Link e Alipay, e permitir que os clientes salvem um cartão para recarga automática. Use-o como o canal principal para clientes internacionais.

Requisitos ​

ItemRequisito
Conta do StripeUma conta do Stripe que aceite pagamentos em USD. O Alipay é cobrado em JPY e precisa ser ativado pelo Stripe na sua conta.
ChavesUma chave secreta (sk_live_... ou sk_test_...) e uma chave publicável (pk_live_... ou pk_test_...). O formulário aceita apenas chaves com esses prefixos.
RedeSeu painel deve estar acessível via HTTPS a partir da internet (o Stripe chama o webhook) e deve conseguir acessar api.stripe.com na porta 443.
Domínio (apenas carteiras)O domínio voltado para o cliente precisa atender em /.well-known/apple-developer-merchantid-domain-association — o NexCMP faz isso para você.
DependênciasNenhum.

Contas do Stripe compartilhadas

O NexCMP processa apenas eventos de webhook para pagamentos criados por ele mesmo, portanto você pode usar uma conta do Stripe que também atenda a outra aplicação.

Preparar a infraestrutura ​

No lado do Stripe:

  1. Faça login no Stripe Dashboard. Ative ou desative Test mode para decidir se você está fazendo um teste ou em produção. Chaves de um modo nunca funcionam no outro.
  2. Abra Developers › API keys. Copie a Publishable key, e revele e copie a Secret key. Mantenha a chave secreta em sigilo.
  3. (Opcional) Abra Settings › Payment methods e ative Alipay se desejar oferecê-lo.
  4. Você não precisa criar o webhook manualmente — o NexCMP pode criá-lo para você (consulte a etapa 5 abaixo). Se preferir fazer isso manualmente, crie um endpoint em Developers › Webhooks com a URL e os eventos listados em Webhook.

Conectar no NexCMP ​

  1. Abra Finance › Payment channels › Stripe (/payments/stripe).
  2. No cartão API keys, escolha o Mode (live ou test), cole a Secret key e a Publishable key.
  3. Clique em Save. As chaves são gravadas em um arquivo de configuração no servidor que apenas a conta de serviço do NexCMP pode ler. Elas nunca são enviadas de volta ao navegador; depois disso, a página exibe apenas os últimos 4 caracteres.
  4. Clique em Check. Uma caixa de diálogo informa a conexão, o modo, o saldo disponível e pendente, o ID da conta, se as cobranças estão ativadas, se um webhook existe e se o Alipay está disponível. Uma linha vermelha indica que essa parte precisa de atenção.
  5. No cartão Webhook, clique em Create webhook e confirme. O NexCMP solicita que o Stripe crie o endpoint com todos os eventos necessários e preenche o campo Webhook signing secret (whsec_...) automaticamente. A URL preenchida previamente no campo é https://<your-domain>/v1/billing/stripe/webhook, por exemplo https://cloud.example.com/v1/billing/stripe/webhook.
  6. Abra Fees & limits (/payments/fees), mantenha Card (Stripe) ativado, defina a porcentagem em Stripe fee % e Stripe fixed fee (cents) para a sua tarifa real e clique em Save channels & fees. Consulte Payment channels.

Página do Stripe com o modo, a chave secreta e a chave publicável preenchidas com valores de exemplo

Webhook ​

O banner vermelho "Missing webhook_secret" permanece até que um segredo de assinatura seja salvo. Sem ele, as recargas pelo Stripe não são registradas, mesmo que o Stripe tenha cobrado o valor.

ItemValor
URLhttps://<your-domain>/v1/billing/stripe/webhook
Eventoscheckout.session.completed, payment_intent.succeeded, payment_intent.payment_failed, charge.refunded, charge.dispute.created, charge.dispute.closed, radar.early_fraud_warning.created, refund.updated, refund.failed
AssinaturaCabeçalho Stripe Stripe-Signature, HMAC-SHA256, tolerância de 300 segundos. Solicitações com assinatura inválida recebem HTTP 400.
IdempotênciaCada ID de evento é armazenado uma única vez; uma entrega repetida nunca credita duas vezes.

Se você atualizou a partir de uma versão que registrava menos eventos, clique em Create webhook novamente — o endpoint antigo é mantido, portanto exclua-o manualmente no Stripe Dashboard depois.

As linhas 24h events e Latest event no cartão Webhook indicam se o Stripe está alcançando o painel. Os eventos individuais são listados em Payment channels › Gateway events (/payments/events, aba Stripe), onde cada evento pode ser visualizado (Payload) ou reproduzido novamente (Replay).

  1. No cartão Wallets (Apple Pay · Google Pay · Link) & Alipay, o campo Customer app Domain registered with Stripe vem preenchido com o nome de host do seu site (por exemplo, cloud.example.com).
  2. Clique em Register / verify domain e confirme. O NexCMP registra o domínio nos domínios de métodos de pagamento do Stripe e solicita que o Stripe o valide.
  3. O resultado mostra o status de Apple Pay, Google Pay e Link. O Apple Pay é exibido apenas quando o status é active.
  4. Em Fees & limits, mantenha Apple Pay · Google Pay · Link ativado.

Cartão da carteira mostrando o domínio registrado e os status do Apple Pay, Google Pay e Link

Apple Pay permanece inativo

O Apple Pay exige que o arquivo de associação de domínio responda com HTTP 200 no seu domínio público. Se você usar o Cloudflare ou outro proxy na frente, não bloqueie /.well-known/.

Alipay ​

O Alipay é opcional. Ative-o em Stripe Dashboard › Settings › Payment methods, clique em Check e aguarde até que a caixa de diálogo mostre que o Alipay está disponível. Em seguida, ative Alipay (Stripe, JPY display) em Fees & limits. Defina Alipay fee %, Alipay fixed fee, a ¥/USD rate (50–500) e o FX spread % (0–20). Atualize a taxa ¥/USD regularmente; a página avisa quando ela tiver mais de 7 dias.

Verificar ​

  1. No modo de teste, faça login no portal como um cliente de teste, abra Billing, clique em Deposit, escolha Card e pague o valor mínimo com o cartão de teste do Stripe 4242 4242 4242 4242 (qualquer data futura, qualquer CVC).
  2. O saldo aumenta em segundos e o pagamento aparece em Finance › Billing › Top-ups com o status Completed.
  3. Abra Payment channels › Gateway events › Stripe: você deverá ver checkout.session.completed ou payment_intent.succeeded com o horário de processamento.
  4. De volta à página do Stripe, 24h events estará acima de 0.

Antes de entrar em produção, altere Mode para live, cole as chaves de produção e clique em Create webhook novamente (os webhooks do modo de teste e de produção são separados).

Limites e notas ​

  • Valores e moeda. As carteiras usam USD. Os pagamentos com cartão, carteira e link são cobrados em USD; o Alipay é exibido ao cliente em JPY e convertido à sua taxa.
  • Taxas. A taxa real do Stripe não é lida de volta automaticamente; a porcentagem de taxa definida por você determina o que o cliente visualiza e o valor creditado na carteira. Escolha Customer pays top-up fee em Fees & limits para cobrar a taxa adicionalmente.
  • Cartões salvos. Quando o cliente marca a opção Save card for auto top-up, o cartão é armazenado no Stripe, e não no seu servidor. Consulte Saved payment methods.
  • Reembolsos. O reembolso para o cartão é um processo em duas etapas: um administrador cria uma solicitação de reembolso para um pagamento concluído (Finance › Billing › Top-ups, ação de reembolso no pagamento) e depois a aprova em Finance › Payouts › Card refunds (/billing/payouts). Os reembolsos do Alipay são assíncronos; uma falha (refund.failed) devolve o valor retido para a carteira.
  • Disputas. Em charge.dispute.created, o NexCMP bloqueia a conta do cliente, interrompe seus serviços pré-pagos (nada é excluído) e envia um alerta ao administrador. Se você vencer (charge.dispute.closed), o valor é creditado de volta à carteira.
  • Pagamentos em espera. Se um webhook nunca chegar, o NexCMP verifica por conta própria os pagamentos que permaneceram pendentes por mais de 10 minutos junto ao Stripe e os conclui. Pagamentos com mais de 7 dias são ignorados.
  • Resellers podem conectar suas próprias contas do Stripe (webhook https://<their-domain>/v1/billing/stripe/webhook/r/<id>); consulte Resellers.

Resolução de problemas ​

SintomaCausaCorreção
"A chave secreta deve começar com sk_live_/sk_test_"Chave incorreta coladaCole a chave secreta de Developers › API keys.
"A chave secreta não corresponde ao modo live/test"A modo e a chave divergemFaça com que Mode corresponda ao prefixo da chave.
"A chave publicável deve começar com pk_"Wrong keyUse a chave publicável.
A verificação indica que a conexão falhouChave incorreta, chave revogada ou o servidor não consegue alcançar api.stripe.comCole a chave novamente; teste com curl -I https://api.stripe.com a partir do servidor.
Banner vermelho "Missing webhook_secret"O segredo de assinatura não está salvoClique em Create webhook ou cole o segredo whsec_... do painel do Stripe e clique em Save.
O pagamento foi debitado, mas o saldo não mudouWebhook não entregue ou falha na assinaturaVerifique se a URL termina com /v1/billing/stripe/webhook, se o segredo corresponde ao endpoint e repita o evento em Gateway events. No Stripe, abra o endpoint e verifique as tentativas de entrega (HTTP 400 indica um segredo de assinatura incorreto).
"Create webhook" failsA URL não usa HTTPS ou não é alcançávelUse o seu domínio https:// público.
Status do Apple Pay inativoDomain not validatedClique em Register / verify domain novamente após o arquivo de associação de domínio retornar 200.
Alipay não disponível no diálogo de verificaçãoNot activated at StripeAtive-o no painel do Stripe e clique em Check.
O cliente não vê o formulário de cartãoCard (Stripe) está desativado ou falta a chave secretaAtive-o em Fees & limits e salve as chaves.