---
title: Stripe
description: Conecte o Stripe ao NexCMP para cartões, Apple Pay, Google Pay, Link e Alipay — chaves de API, webhook, registro de domínio e pagamento de teste.
url: https://nexcmp.com/pt/docs/billing/stripe/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Stripe

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

## O que faz {#what-it-does}

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](https://nexcmp.com/pt/docs/billing/auto-top-up/). Use-o como o canal principal para clientes internacionais.

## Requisitos {#requirements}

| Item | Requisito |
|---|---|
| Conta do Stripe | Uma conta do Stripe que aceite pagamentos em **USD**. O Alipay é cobrado em JPY e precisa ser ativado pelo Stripe na sua conta. |
| Chaves | Uma 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. |
| Rede | Seu 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ências | Nenhum. |

::: info 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 {#prepare-the-infrastructure}

No lado do Stripe:

1. Faça login no [Stripe Dashboard](https://dashboard.stripe.com). 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](#webhook).

## Conectar no NexCMP {#connect-in-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](https://nexcmp.com/pt/docs/billing/payment-channels/#switches-and-fees-fees-limits).

![Página do Stripe com o modo, a chave secreta e a chave publicável preenchidas com valores de exemplo](https://nexcmp.com/pt/docs/images/billing/stripe-01-keys.webp)


### Webhook {#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.

| Item | Valor |
|---|---|
| URL | `https://<your-domain>/v1/billing/stripe/webhook` |
| Eventos | `checkout.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` |
| Assinatura | Cabeçalho Stripe `Stripe-Signature`, HMAC-SHA256, tolerância de 300 segundos. Solicitações com assinatura inválida recebem HTTP 400. |
| Idempotência | Cada 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**).

### Apple Pay, Google Pay e Link {#apple-pay-google-pay-and-link}

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](https://nexcmp.com/pt/docs/images/billing/stripe-03-wallets.webp)

::: tip 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 {#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 {#verify}

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 {#limits-notes}

- **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](https://nexcmp.com/pt/docs/billing/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](https://nexcmp.com/pt/docs/customers/resellers/).

## Resolução de problemas {#troubleshooting}

| Sintoma | Causa | Correção |
|---|---|---|
| "A chave secreta deve começar com sk_live_/sk_test_" | Chave incorreta colada | Cole a chave secreta de **Developers › API keys**. |
| "A chave secreta não corresponde ao modo live/test" | A modo e a chave divergem | Faça com que **Mode** corresponda ao prefixo da chave. |
| "A chave publicável deve começar com pk_" | Wrong key | Use a chave publicável. |
| A verificação indica que a conexão falhou | Chave incorreta, chave revogada ou o servidor não consegue alcançar `api.stripe.com` | Cole 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á salvo | Clique 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 mudou | Webhook não entregue ou falha na assinatura | Verifique 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" fails | A URL não usa HTTPS ou não é alcançável | Use o seu domínio `https://` público. |
| Status do Apple Pay inativo | Domain not validated | Clique 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ção | Not activated at Stripe | Ative-o no painel do Stripe e clique em **Check**. |
| O cliente não vê o formulário de cartão | **Card (Stripe)** está desativado ou falta a chave secreta | Ative-o em **Fees & limits** e salve as chaves. |