Stripe, Twilio & Padrões de SDK

Q: Capturas parciais?

PaymentIntent capture_method: manual para autorizar e depois capturar um valor menor posteriormente.

Q: Módulo NestJS Stripe?

Módulo comunitário @nestjs/stripe ou um serviço wrapper fino - mesmas regras de idempotência.

Stripe e Twilio são os SDKs pagos mais comuns em APIs B2B Node. Esta página cobre timeouts, idempotência, modos de teste e pareamento de webhooks.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import Stripe from "stripe";
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2024-11-20.acacia",
  timeout: 10_000,
  maxNetworkRetries: 0,
});
 
const intent = await stripe.paymentIntents.create(
  { amount: 2500, currency: "usd", automatic_payment_methods: { enabled: true } },
  { idempotencyKey: req.header("Idempotency-Key") ?? undefined }
);

Quando usar isso:

Cobrança, assinaturas, OTP por SMS, alertas de voz
Você precisa de comportamento de cliente HTTP testado pelo fornecedor e erros tipados

Exemplo de Trabalho

// src/integrations/payments-service.ts
import Stripe from "stripe";
import twilio from "twilio";
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2024-11-20.acacia",
  timeout: 10_000,
  maxNetworkRetries: 0,
});
 
const twilioClient = twilio(process.env.TWILIO_ACCOUNT_SID!, process.env.TWILIO_AUTH_TOKEN!);
 
export async function createPaymentIntent(
  amountCents: number,
  currency: string,
  idempotencyKey: string
) {
  return stripe.paymentIntents.create(
    { amount: amountCents, currency, automatic_payment_methods: { enabled: true } },
    { idempotencyKey }
  );
}
 
export async function sendOtpSms(to: string, code: string) {
  return twilioClient.messages.create({
    to,
    from: process.env.TWILIO_FROM_NUMBER!,
    body: `Seu código é ${code}`,
    statusCallback: `${process.env.PUBLIC_API_URL}/webhooks/twilio/sms`,
  });
}
 
// Rota Express
app.post("/payments/intent", async (req, res, next) => {
  try {
    const key = req.header("Idempotency-Key");
    if (!key) return res.status(400).json({ error: "missing_idempotency_key" });
    const pi = await createPaymentIntent(req.body.amountCents, "usd", key);
    res.status(201).json({ clientSecret: pi.client_secret, id: pi.id });
  } catch (err) {
    next(mapStripeError(err));
  }
});

O que isso demonstra:

Idempotência do Stripe na criação
Twilio de saída com URL de callback de status
Erros mapeados antes do manipulador de erros do Express

Mergulho Profundo

Padrões do Stripe

Operação	Padrão
Cobrança única	PaymentIntent
Cobrança SaaS	Customer + Subscription + Prices
Marketplace Connect	cabeçalho `stripeAccount` nas requisições
Reembolsos	Idempotente na criação de `refund` com chave

// Recuperar com expand - usar com moderação
const sub = await stripe.subscriptions.retrieve(id, { expand: ["customer", "latest_invoice"] });

Prefira retrieves separados ou webhooks em vez de árvores de expand profundas

Pareamento de Webhooks do Stripe

Ouça por payment_intent.succeeded, invoice.paid, customer.subscription.updated
Fulfillment idempotente em event.id - veja Verificação de Webhook

Padrões do Twilio

// Verificar chamador em chamadas recebidas - webhook TwiML
app.post("/voice/inbound", express.urlencoded({ extended: false }), (req, res) => {
  const twiml = new twilio.twiml.VoiceResponse();
  twiml.say("Hello");
  res.type("text/xml").send(twiml.toString());
});

Webhooks de voz/SMS de entrada precisam de validação de assinatura
Use o SID do serviço de mensagens para escala e pool de remetentes

Modos de Teste

# Cartão de teste Stripe 4242 4242 4242 4242
STRIPE_SECRET_KEY=sk_test_...
 
# Números mágicos do Twilio para teste de SMS

CI executa apenas com credenciais de teste
Relógio de teste do Stripe para viagem no tempo de assinatura

Timeouts e Retentativas

Stripe: passe idempotencyKey ao habilitar maxNetworkRetries do SDK
Twilio: trate 21610 (desinscrito) como erro de negócio, não retentativa

Armadilhas

Sem idempotência na criação de PaymentIntent - risco de cobrança dupla em retentativa do cliente. Correção: exigir chave.
Chave ativa em ambiente de preview - cobranças reais. Correção: caminhos de gerenciador de segredos segregados por ambiente.
Callback HTTP do Twilio - deve ser HTTPS público. Correção: ngrok para dev, URL real para prod.
Registrar client_secret - vazamento de pagamento nos logs. Correção: registrar apenas o ID do pagamento.
Derivação da versão da API Stripe - alterações de quebra na configuração padrão do painel. Correção: fixar apiVersion no código.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Paddle/Lemon Squeezy	Comerciante do registro	Marketplace Connect personalizado
MessageBird/Vonage	Preços/recursos do Twilio	Já padronizado no Twilio
Adyen/Braintree	Mix de pagamentos corporativos	Equipe conhece Stripe
Resend + OTP por e-mail	Apenas códigos por e-mail	Requeribilidade de entrega de SMS

FAQs

Stripe Elements vs Checkout?

Checkout hospedado com escopo PCI mais rápido. Elementos UI personalizada - ainda use PaymentIntent no lado do servidor.

Produto Twilio Verify?

A API Verify gerencia o ciclo de vida do OTP - menos código SMS personalizado do que a API de Mensagens bruta.

Onboarding do Stripe Connect?

API Account Links para contas conectadas Express/Standard - manipuladores de webhook separados.

Capturas parciais?

PaymentIntent capture_method: manual para autorizar e depois capturar um valor menor posteriormente.

Ordem dos webhooks?

Não assuma a ordem. Use uma máquina de estados idempotente no status do pagamento.

Autenticação Forte do Cliente?

Stripe lida com o fluxo 3DS no lado do cliente; ouça eventos requires_action.

Limites de taxa do Twilio?

Enfileire envios de SMS; backoff exponencial em 429; serviço de mensagens ajuda no roteamento.

SDK apenas em worker?

Bom padrão - API enfileira, worker chama Stripe para fulfillment após webhook.

Tipos TypeScript?

Stripe fornece tipos; tipos Twilio incluídos - fixe versões para consistência.

Módulo NestJS Stripe?

Módulo comunitário @nestjs/stripe ou um serviço wrapper fino - mesmas regras de idempotência.

Relacionado

Verificação de Webhook - eventos de entrada
Chaves de Idempotência - chaves HTTP
Noções Básicas de Integrações - limites
Resiliência de Retentativa e Saída - backoff
Melhores Práticas de Integrações - checklist

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import Stripe from "stripe";
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2024-11-20.acacia",
  timeout: 10_000,
  maxNetworkRetries: 0,
});
 
const intent = await stripe.paymentIntents.create(
  { amount: 2500, currency: "usd", automatic_payment_methods: { enabled: true } },
  { idempotencyKey: req.header("Idempotency-Key") ?? undefined }
);

Quando usar isso:

Cobrança, assinaturas, OTP por SMS, alertas de voz
Você precisa de comportamento de cliente HTTP testado pelo fornecedor e erros tipados

Exemplo de Trabalho

// src/integrations/payments-service.ts
import Stripe from "stripe";
import twilio from "twilio";
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2024-11-20.acacia",
  timeout: 10_000,
  maxNetworkRetries: 0,
});
 
const twilioClient = twilio(process.env.TWILIO_ACCOUNT_SID!, process.env.TWILIO_AUTH_TOKEN!);
 
export async function createPaymentIntent(
  amountCents: number,
  currency: string,
  idempotencyKey: string
) {
  return stripe.paymentIntents.create(
    { amount: amountCents, currency, automatic_payment_methods: { enabled: true } },
    { idempotencyKey }
  );
}
 
export async function sendOtpSms(to: string, code: string) {
  return twilioClient.messages.create({
    to,
    from: process.env.TWILIO_FROM_NUMBER!,
    body: `Seu código é ${code}`,
    statusCallback: `${process.env.PUBLIC_API_URL}/webhooks/twilio/sms`,
  });
}
 
// Rota Express
app.post("/payments/intent", async (req, res, next) => {
  try {
    const key = req.header("Idempotency-Key");
    if (!key) return res.status(400).json({ error: "missing_idempotency_key" });
    const pi = await createPaymentIntent(req.body.amountCents, "usd", key);
    res.status(201).json({ clientSecret: pi.client_secret, id: pi.id });
  } catch (err) {
    next(mapStripeError(err));
  }
});

O que isso demonstra:

Idempotência do Stripe na criação
Twilio de saída com URL de callback de status
Erros mapeados antes do manipulador de erros do Express

Mergulho Profundo

Padrões do Stripe

Operação	Padrão
Cobrança única	PaymentIntent
Cobrança SaaS	Customer + Subscription + Prices
Marketplace Connect	cabeçalho `stripeAccount` nas requisições
Reembolsos	Idempotente na criação de `refund` com chave

// Recuperar com expand - usar com moderação
const sub = await stripe.subscriptions.retrieve(id, { expand: ["customer", "latest_invoice"] });

Prefira retrieves separados ou webhooks em vez de árvores de expand profundas

Pareamento de Webhooks do Stripe

Ouça por payment_intent.succeeded, invoice.paid, customer.subscription.updated
Fulfillment idempotente em event.id - veja Verificação de Webhook

Padrões do Twilio

// Verificar chamador em chamadas recebidas - webhook TwiML
app.post("/voice/inbound", express.urlencoded({ extended: false }), (req, res) => {
  const twiml = new twilio.twiml.VoiceResponse();
  twiml.say("Hello");
  res.type("text/xml").send(twiml.toString());
});

Webhooks de voz/SMS de entrada precisam de validação de assinatura
Use o SID do serviço de mensagens para escala e pool de remetentes

Modos de Teste

# Cartão de teste Stripe 4242 4242 4242 4242
STRIPE_SECRET_KEY=sk_test_...
 
# Números mágicos do Twilio para teste de SMS

CI executa apenas com credenciais de teste
Relógio de teste do Stripe para viagem no tempo de assinatura

Timeouts e Retentativas

Stripe: passe idempotencyKey ao habilitar maxNetworkRetries do SDK
Twilio: trate 21610 (desinscrito) como erro de negócio, não retentativa

Armadilhas

Sem idempotência na criação de PaymentIntent - risco de cobrança dupla em retentativa do cliente. Correção: exigir chave.
Chave ativa em ambiente de preview - cobranças reais. Correção: caminhos de gerenciador de segredos segregados por ambiente.
Callback HTTP do Twilio - deve ser HTTPS público. Correção: ngrok para dev, URL real para prod.
Registrar client_secret - vazamento de pagamento nos logs. Correção: registrar apenas o ID do pagamento.
Derivação da versão da API Stripe - alterações de quebra na configuração padrão do painel. Correção: fixar apiVersion no código.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Paddle/Lemon Squeezy	Comerciante do registro	Marketplace Connect personalizado
MessageBird/Vonage	Preços/recursos do Twilio	Já padronizado no Twilio
Adyen/Braintree	Mix de pagamentos corporativos	Equipe conhece Stripe
Resend + OTP por e-mail	Apenas códigos por e-mail	Requeribilidade de entrega de SMS

FAQs

Stripe Elements vs Checkout?

Checkout hospedado com escopo PCI mais rápido. Elementos UI personalizada - ainda use PaymentIntent no lado do servidor.

Produto Twilio Verify?

A API Verify gerencia o ciclo de vida do OTP - menos código SMS personalizado do que a API de Mensagens bruta.

Onboarding do Stripe Connect?

API Account Links para contas conectadas Express/Standard - manipuladores de webhook separados.

Capturas parciais?

PaymentIntent capture_method: manual para autorizar e depois capturar um valor menor posteriormente.

Ordem dos webhooks?

Não assuma a ordem. Use uma máquina de estados idempotente no status do pagamento.

Autenticação Forte do Cliente?

Stripe lida com o fluxo 3DS no lado do cliente; ouça eventos requires_action.

Limites de taxa do Twilio?

Enfileire envios de SMS; backoff exponencial em 429; serviço de mensagens ajuda no roteamento.

SDK apenas em worker?

Bom padrão - API enfileira, worker chama Stripe para fulfillment após webhook.

Tipos TypeScript?

Stripe fornece tipos; tipos Twilio incluídos - fixe versões para consistência.

Módulo NestJS Stripe?

Módulo comunitário @nestjs/stripe ou um serviço wrapper fino - mesmas regras de idempotência.

Relacionado

Verificação de Webhook - eventos de entrada
Chaves de Idempotência - chaves HTTP
Noções Básicas de Integrações - limites
Resiliência de Retentativa e Saída - backoff
Melhores Práticas de Integrações - checklist

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.

Stripe, Twilio & Padrões de SDK

Buscar na documentação

Stripe, Twilio & Padrões de SDK