> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# v1.97.6 (7 de maio de 2026)

> Lançamento de Entitlements com cinco novas integrações de entrega (Discord, GitHub, Telegram, Framer, Notion), motivos de cancelamento de assinatura no portal do cliente, configuração de valor mínimo para e-mandato em INR, configuração de taxas inclusivas para moedas adaptativas, aplicativo Desktop Dodo Payments para macOS/Windows/Linux, pagamentos com stablecoin (USDC/USDP/USDG), importação de chaves de licença existentes, require_phone_number para sessões de checkout e correções de bugs

## Novos Recursos

### 1. **Entitlements**

O Dodo Payments agora vem com **Entitlements** unificados — uma camada única que alimenta a entrega automática para cada integração de cumprimento. Um único produto pode entregar múltiplos entitlements em cada compra bem-sucedida ou assinatura ativa.

![Painel de Entitlements com a lista de entitlements à esquerda e atividade de concessão à direita](https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/list.png?fit=max\&auto=format\&n=do-W-dMDGVB_xzr_\&q=85\&s=12a326205f64d1e71485bce46114d296)

**Cinco novas integrações de plataforma**

Até agora, o Dodo Payments entregava **chaves de licença** e **arquivos digitais** automaticamente ao comprar. Entitlements expandem esse escopo para cinco plataformas adicionais — para que clientes pagantes possam obter acesso à sua comunidade, seu código ou seu conteúdo assim que o pagamento for concluído, sem necessidade de cumprimento manual por parte de sua equipe:

| Integração | O que entrega | Comportamento de revogação |
| - | - | - |
| **Discord** | Atribui um papel escolhido no seu servidor Discord após o cliente completar o OAuth | Papel removido em cancelamento/reembolso |
| **GitHub** | Adiciona o cliente como colaborador a um repositório privado no nível de permissão que você escolher | Colaborador removido em cancelamento/reembolso |
| **Telegram** | Emite um link de convite de solicitação única para um chat ou canal privado através do seu bot do Telegram | Cliente removido do chat em cancelamento/reembolso |
| **Framer** | Desbloqueia um link de remix de template do Framer protegido por um código de acesso | Código de acesso desativado em cancelamento/reembolso |
| **Notion** | Duplica uma página de template Notion no espaço de trabalho do cliente após a autorização via OAuth | Página entregue arquivada em cancelamento/reembolso |

Estas se juntam às integrações existentes de **Chaves de Licença** (chaves únicas com limites de ativação e expiração) e **Arquivos Digitais** (URLs de download pré-assinados para e-books, templates, mídias), todas agora geridas através do mesmo ciclo de vida de concessão.

**O que vem pronto para uso**

| Capacidade | Descrição |
| - | - |
| **Modelos reutilizáveis** | Defina um entitlement uma vez (limites de ativação, pacotes de arquivos, papel no Discord, permissão de repositório, etc.) e anexe a qualquer produto |
| **Concessões automáticas** | Emitidas em `payment.succeeded` e `subscription.active`, idempotentes em renovações e reativações |
| **Revogação consciente do ciclo de vida** | Revogado em `subscription.cancelled`, `subscription.on_hold`, `subscription.expired`, `refund.succeeded`, `subscription.plan_changed`, ou revogação manual via API/painel — com um `revocation_reason` preenchido |
| **OAuth + fluxos diretos da plataforma** | OAuth para consentimento do assinante no Discord, GitHub e Notion; chamadas diretas para Telegram, Framer e Arquivos Digitais |
| **Detecção de deriva** | Detecta quando um papel no Discord, colaborador no GitHub, ou página no Notion fica fora de sincronia ao nível da plataforma e revoga com `revocation_reason: platform_external` |
| **Criptografia em repouso** | Todos os tokens de plataforma (OAuth, bot, instalações de app) armazenados com AES-256-GCM |

**Webhooks**

Quatro novos eventos de ciclo de vida ocorrem para cada concessão:

| Evento | Ocorre quando |
| - | - |
| `entitlement_grant.created` | Uma nova concessão é criada para um cliente |
| `entitlement_grant.delivered` | Acesso do cliente provisionado |
| `entitlement_grant.failed` | A entrega não pôde ser concluída; inspecione `error_code` e `error_message` |
| `entitlement_grant.revoked` | Acesso retirado; inspecione `revocation_reason` |

> [!TIP]
>
> Para novas integrações, ouça `entitlement_grant.delivered` em vez de `payment.succeeded`. O sucesso do pagamento não significa que a entrega foi concluída, especialmente para integrações baseadas em OAuth.

Saiba mais: [Entitlements](https://docs.dodopayments.com/features/entitlements/introduction.md) | [Webhooks de Concessão de Entitlement](https://docs.dodopayments.com/developer-resources/webhooks/intents/entitlement-grant.md)

### 2. **Motivos de Cancelamento de Assinatura no Portal do Cliente**

Quando os clientes cancelam uma assinatura através do Portal do Cliente, agora eles são solicitados a compartilhar **por que estão cancelando** antes de confirmar. O motivo capturado é armazenado na assinatura como `cancellation_feedback`, mostrado na API e nos payloads de webhook, e disponível no painel para que você possa identificar padrões de churn de relance.

![Modal de cancelamento do Portal do Cliente com o campo suspenso 'Por que você está cancelando?' mostrando motivos como Muito caro, Faltam recursos, e Outros](https://mintcdn.com/dodopayments/RlXcM7JO-E_w40Np/images/customer-portal/cancellation-reasons.png?fit=max\&auto=format\&n=RlXcM7JO-E_w40Np\&q=85\&s=979394da2a9aa3907cbf9f4e225f9a4b)

**Opções de motivo**

| Valor | Rótulo para o cliente |
| - | - |
| `too_expensive` | Muito caro |
| `missing_features` | Faltam recursos |
| `switched_service` | Mudou para outro serviço |
| `unused` | Não está usando o suficiente |
| `customer_service` | Atendimento ao cliente precário |
| `low_quality` | Baixa qualidade |
| `too_complex` | Muito complexo |
| `other` | Outros |

**Onde aparece**

* **Objeto de assinatura**: Novo campo `cancellation_feedback` (um dos valores acima) e `cancellation_comment` (texto livre opcional), preenchidos quando o cliente cancela
* **Webhook `subscription.cancelled`**: Ambos os campos são incluídos no payload
* **API**: Passe `cancellation_feedback` e `cancellation_comment` para `PATCH /subscriptions/{subscription_id}` ao agendar ou executar um cancelamento programaticamente

```typescript theme={null}
// Reading the captured feedback
const subscription = await client.subscriptions.retrieve('sub_123');
console.log(subscription.cancellation_feedback); // e.g., "too_expensive"
console.log(subscription.cancellation_comment);  // e.g., "Switching to a competitor"
```

> [!TIP]
>
> Combine `cancellation_feedback` com [Subscription Dunning](https://docs.dodopayments.com/features/recovery/subscription-dunning.md) para personalizar seus e-mails de reconquista — por exemplo, envie um código de desconto para canceladores `too_expensive` e uma pesquisa "o que está faltando?" para canceladores `missing_features`.

Saiba mais: [Portal do Cliente](https://docs.dodopayments.com/features/customer-portal.md#cancelling-a-subscription) | [Webhooks de Assinatura](https://docs.dodopayments.com/developer-resources/webhooks/intents/subscription.md)

### 3. **Valor Mínimo de Mandato Configurável para E-Mandatos em INR**

Agora você pode configurar o **mínimo mandatário** para e-mandatos em INR em assinaturas recorrentes com cartão indiano. Anteriormente, toda assinatura com cartão indiano abaixo de ₹15.000 usava um mandato fixo de ₹15.000 sob demanda. Agora você pode substituir esse mínimo a nível de comerciante — e por sessão de checkout ou assinatura, se necessário.

O valor do mandato registrado com o banco do cliente é `max(mandate_min_amount_inr_paise, billing_amount)`, portanto este valor atua como o **teto de autorização** para o cliente sempre que a cobrança for menor que o mínimo.

```typescript theme={null}
// Per-subscription override
const subscription = await client.subscriptions.create({
  product_id: 'pdt_inr_monthly',
  customer: { email: 'customer@example.in' },
  billing: { country: 'IN' /* ... */ },
  mandate_min_amount_inr_paise: 2_000_000 // ₹20,000 ceiling for this subscription
});

// Or via a checkout session
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_inr_monthly', quantity: 1 }],
  mandate_min_amount_inr_paise: 2_000_000,
  return_url: 'https://yoursite.com/return'
});
```

**Prioridade de resolução**

1. Substituição por solicitação (`mandate_min_amount_inr_paise` na sessão de checkout, pagamento ou assinatura)
2. Configuração a nível de comerciante nas configurações de negócios
3. Padrão do sistema de **₹15.000** (1.500.000 paise)

| Campo | Tipo | Intervalo | Aplica-se a |
| - | - | - | - |
| `mandate_min_amount_inr_paise` | `integer` (paise INR) | `>= 1` | Assinaturas INR com cartão indiano em conectores não-Airwallex |

> [!NOTE]
>
> Esta configuração só afeta e-mandatos registrados para cartões emitidos na Índia (Visa, Mastercard, RuPay) em assinaturas INR. Assinaturas UPI seguem seu próprio fluxo de AutoPay e não são afetadas.

Saiba mais: [Métodos de Pagamento na Índia](https://docs.dodopayments.com/features/payment-methods/india.md#mandate-types) | [Assinaturas com Mandatos RBI](https://docs.dodopayments.com/features/subscription.md#subscriptions-with-rbi-compliant-mandates)

### 4. **Configuração de Negócios com Taxas Inclusivas para Moeda Adaptativa**

Moeda Adaptativa é o recurso que permite cobrar dos clientes em sua moeda local. Por padrão, a **taxa de 2–4% de moeda adaptativa** é suportada pelo cliente e adicionada ao preço exibido. Com a nova configuração **Taxas Inclusivas**, você pode alterar isso: mantenha o preço exibido inalterado para o cliente e absorva a taxa você mesmo.

**Onde configurar**

Vá para **Configurações → Negócios**, certifique-se de que **Preço Adaptativo** está habilitado e alterne **Taxas Inclusivas** na seção Moeda Adaptativa.

**Substituição por solicitação**

Você também pode substituir o padrão do merchant para pagamentos individuais, cobranças de assinatura sob demanda e alterações de plano usando o booleano `adaptive_currency_fees_inclusive`:

```typescript theme={null}
const payment = await client.payments.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  adaptive_currency_fees_inclusive: true, // override business default
  return_url: 'https://yoursite.com/return'
});
```

| Modo | O cliente vê | O comerciante liquida |
| - | - | - |
| Exclusivo (padrão) | Preço local + taxa de 2–4% | Preço base total |
| Inclusivo | Preço local (inalterado) | Preço base menos a taxa de 2–4% |

> [!NOTE]
>
> Transações INR → INR são sempre tratadas como inclusivas independentemente da configuração do negócio ou substituição por solicitação.

Saiba mais: [Moeda Adaptativa](https://docs.dodopayments.com/features/adaptive-currency.md)

### 5. **Aplicativo Desktop Dodo Payments**

O aplicativo oficial **Dodo Payments Desktop** agora está disponível para **macOS, Windows e Linux**. Execute seu painel de pagamentos como um aplicativo nativo rápido — sem precisar de aba de navegador.

| Plataforma | Download |
| - | - |
| macOS (Apple Silicon) | `Dodo.Payments_<version>_aarch64.dmg` |
| macOS (Intel) | `Dodo.Payments_<version>_x64.dmg` |
| Windows | `Dodo.Payments_<version>_x64-setup.exe` (ou `.msi`) |
| Linux (Debian/Ubuntu) | `Dodo.Payments_<version>_amd64.deb` |
| Linux (Fedora/RHEL) | `Dodo.Payments-<version>-1.x86_64.rpm` |
| Linux (AppImage, autoatualização) | `Dodo.Payments_<version>_amd64.AppImage` |

**O que está dentro**

* **Binário nativo pequeno** — construído com Tauri no webview nativo do sistema, total de \~5 MB (sem Chromium incluído)
* **Assinado e notariado** — as versões para macOS são assinadas com ID de Desenvolvedor Apple e notariadas, sem alertas do Gatekeeper
* **Autoatualização** — verifica a cada 4 horas e aplica atualizações assinadas automaticamente do GitHub Releases (funciona em macOS, Windows e Linux AppImage)
* **Bandeja do sistema + menu de barra** — esconder na bandeja no macOS, menus completos Arquivo/Editar/Visualizar/Ajuda com atalhos de teclado (`⌘⇧H` vá para o painel, `⌘L` copie a URL atual, `⌘⌥I` ferramentas de desenvolvimento)
* **Suporte a deep-link** — links de autenticação mágicos abrem diretamente no app
* **Multi-janela** — abra múltiplos painéis lado a lado

> [!TIP]
>
> Baixe o instalador mais recente para sua plataforma na [página de lançamentos do aplicativo Desktop](https://github.com/dodopayments/dodo-desktop/releases/latest). O repositório é totalmente open source.

### 6. **Pagamentos Stablecoin (USDC, USDP, USDG)**

Aceite **pagamentos em stablecoin globalmente** com liquidação em USD. Os clientes pagam de sua carteira de stablecoin preferida na rede de sua escolha; você recebe USD fiduciário sem exposição à volatilidade do cripto, sem estornos e sem infraestrutura bancária necessária no lado do cliente.

**Moedas e redes suportadas**

| Stablecoin | Redes |
| - | - |
| **USDC** | Ethereum, Solana, Polygon, Base |
| **USDP** | Ethereum, Solana |
| **USDG** | Ethereum |

**Cobertura**

| Detalhe | Valor |
| - | - |
| Moeda de cobrança | USD |
| Países compatíveis | Global (exceto Índia) |
| Assinaturas | Não compatíveis (apenas pagamentos avulsos) |
| Valor mínimo | \$0.50 |
| Liquidação | USD |

**Configuração**

Passe `crypto_currency` em `allowed_payment_method_types` ao criar uma sessão de checkout:

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['crypto_currency', 'credit', 'debit'],
  return_url: 'https://example.com/success'
});
```

O cliente vê um endereço de carteira e um código QR com a quantidade de stablecoin calculada na taxa de câmbio em tempo real; assim que a blockchain confirma a transação, seu webhook `payment.succeeded` é acionado e o cliente é redirecionado para sua página de sucesso.

> [!NOTE]
>
> Pagamentos em stablecoin são irreversíveis por design — não há estornos. Recomendamos sempre oferecer `credit` e `debit` como métodos de apoio para clientes sem uma carteira de stablecoin.

Saiba mais: [Pagamentos Stablecoin](https://docs.dodopayments.com/features/payment-methods/stablecoins.md)

### 7. **Importar Chaves de Licença Existentes**

Agora você pode **importar chaves de licença de outro sistema** para o Dodo Payments usando a [API de Criação de Chave de Licença](https://docs.dodopayments.com/api-reference/licenses/create-license-key.md). Isso permite migração sem interrupções de qualquer fornecedor externo de chaves de licença, para que seus clientes existentes possam continuar ativando, validando e desativando suas chaves no Dodo Payments sem necessidade de reemissão.

```typescript theme={null}
const licenseKey = await client.licenseKeys.create({
  customer_id: 'cus_abc123',
  product_id: 'pdt_456',
  key: 'YOUR-EXISTING-LICENSE-KEY',
  activations_limit: 5,
  expires_at: '2026-12-31T23:59:59Z',
});
```

Chaves importadas são marcadas com `source: "import"` (vs. `source: "auto"` para chaves geradas automaticamente no pagamento), de modo que você pode distinguir o inventário migrado de chaves emitidas organicamente ao consultar `GET /license_keys`. O `payment_id` em chaves importadas é `null` porque elas não estão vinculadas a uma transação do Dodo Payments.

> [!WARNING]
>
> Chaves de licença criadas ou atualizadas através da API não acionam notificações por e-mail para clientes. Se você precisar notificar os clientes sobre uma chave importada, faça isso separadamente em seu aplicativo.

> [!TIP]
>
> Migrando do Polar.sh ou Lemon Squeezy? O [`dodo-migrate` CLI](https://docs.dodopayments.com/migrate-to-dodo) automatiza importações em massa de produtos, clientes, descontos e chaves de licença em um único comando.

Saiba mais: [Chaves de Licença](https://docs.dodopayments.com/features/license-keys.md#import-existing-license-keys-via-api) | [API de Criação de Chave de Licença](https://docs.dodopayments.com/api-reference/licenses/create-license-key.md)

### 8. **`require_phone_number` para Sessões de Checkout**

Force os clientes a fornecer um número de telefone durante o checkout configurando `feature_flags.require_phone_number: true` ao criar uma sessão de checkout. O número de telefone se torna um campo obrigatório no formulário de checkout, com validação de formulário indicando "Número de telefone é obrigatório" se o cliente o deixar em branco.

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  feature_flags: {
    allow_phone_number_collection: true,
    require_phone_number: true
  },
  return_url: 'https://yoursite.com/return'
});
```

| Flag | Padrão | Comportamento |
| - | - | - |
| `allow_phone_number_collection` | `true` | Mostra o campo de número de telefone no checkout |
| `require_phone_number` | `false` | Torna o campo de número de telefone obrigatório |

> [!WARNING]
>
> `require_phone_number: true` requer `allow_phone_number_collection: true`. A API rejeita sessões onde `require_phone_number` é verdadeiro enquanto a coleta de telefone está desabilitada.

> [!TIP]
>
> Útil para SaaS B2B, indústrias regulamentadas, ou qualquer fluxo onde você precise de um canal de contato verificado para suporte, revisão de fraude, ou conformidade.

Saiba mais: [Funcionalidades de Checkout](https://docs.dodopayments.com/features/checkout.md) | [API de Criação de Sessão de Checkout](https://docs.dodopayments.com/api-reference/checkout-sessions/create.md)

## Correções de Bugs e Melhorias

* Correções de bugs menores e melhorias de estabilidade em toda a plataforma


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.