A API Payment Intents

Use a API Payment Intents para criar uma integração de pagamentos capaz de gerenciar fluxos de pagamento complexos que mude ao longo do ciclo de vida do PaymentIntent. Essa API rastreia um pagamento, da criação até o checkout, e aciona autenticações adicionais quando necessário.

Estas são algumas vantagens do uso da API Payment Intents:

• Administrar autenticação automática
• Sem cobranças duplicadas
• Sem problemas com a chave de idempotência
• Compatibilidade com Autenticação Forte de Cliente (SCA) e mudanças regulatórias similares

Um conjunto completo de APIs

Use a API Payment Intents junto com as API Setup Intents e Payment Methods. Essas APIs ajudam a gerenciar pagamentos dinâmicos (por exemplo, autenticação adicional como 3D Secure) e a preparar sua expansão para outros países, permitindo que você aceite novos regulamentos e formas de pagamento regionais.

A integração com a API Payment Intents tem duas etapas: criar e confirmar um PaymentIntent. Cada PaymentIntent normalmente está vinculado a um único carrinho de compras ou sessão do cliente no seu aplicativo. O PaymentIntent encapsula os detalhes da transação, como formas de pagamento aceitas, o valor a ser cobrado e a moeda desejada.

Criar um PaymentIntent

Para começar, consulte o guia sobre como aceitar pagamentos. Ele descreve como criar um PaymentIntent no servidor e passar o segredo do cliente ao cliente em vez de passar todo o objeto PaymentIntent.

Ao criar o PaymentIntent, é possível especificar opções como o valor e a moeda:

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd

Práticas recomendadas

• Recomendamos criar um PaymentIntent assim que o valor for conhecido (por exemplo, quando o cliente inicia o processo de checkout) para ajuda a rastrear o funil de vendas. Se o valor mudar, você pode atualizar o valor. Por exemplo, se o cliente volta ao processo de checkout e adiciona novos itens ao carrinho, pode ser preciso atualizar o valor quando o processo de checkout for reiniciado.

• Se o processo de checkout for interrompido e depois retomado, tente reaproveitar o PaymentIntent em vez de criar outro. Cada PaymentIntent tem um ID único que você pode usar para recuperação se precisar dele novamente. No modelo de dados do seu aplicativo, é possível armazenar o ID do PaymentIntent no carrinho de compras ou sessão do cliente para facilitar a recuperação. A vantagem de reaproveitar o PaymentIntent é que o estado do objeto ajuda a rastrear tentativas de pagamento malsucedidas de um determinado carrinho ou sessão.

• Lembre-se de fornecer uma chave de idempotência para evitar a criação de PaymentIntents duplicados para a mesma compra. Normalmente, essa chave é criada com base no ID associado ao carrinho ou sessão do cliente no aplicativo.

Passar o segredo do cliente para o lado do cliente

O PaymentIntent contém um segredo do cliente, uma chave que é única para cada PaymentIntent. No lado do cliente do seu aplicativo, o segredo do cliente é usado pelo Stripe.js como parâmetro para invocar funções (como stripe.confirmCardPayment ou stripe.handleCardAction) e finalizar o pagamento.

Recuperar o segredo do cliente

O PaymentIntent inclui um segredo do cliente que o lado do cliente usa para concluir com segurança o processo de pagamento. Você pode usar abordagens diferentes para enviar a senha do cliente ao lado do cliente.

get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Após o pagamento

Depois que o cliente confirma o pagamento, é uma prática recomendada do seu servidor monitorar webhooks para detectar quando o pagamento é concluído corretamente ou falha.

Um PaymentIntent pode ter mais de um objeto Charge associado a ele se houver várias tentativas de pagamento, por exemplo, repetições. Para cada cobrança, você pode inspecionar o resultado e detalhes da forma de pagamento utilizados.

Otimização de formas de pagamento para pagamentos futuros

O parâmetro setup_future_usage salva formas de pagamento para uso no futuro. Para cartões, ele também otimiza as taxas de autorização, cumprindo regras de rede e legislações regionais, como a SCA. Para saber qual valor utilizar, considere a frequência de uso dessa forma de pagamento no futuro.

Você pode continuar a aceitar pagamentos fora da sessão com cartões configurados para pagamentos na sessão, mas a probabilidade de o banco recusar o pagamento fora da sessão e exigir autenticação do titular do cartão aumenta.

O exemplo a seguir mostra como criar um PaymentIntent e especificar setup_future_usage:

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd \
  -d setup_future_usage=off_session

Descrição dinâmica no extrato

Por padrão, a descrição no extrato da sua conta Stripe aparece nos extratos do cliente sempre que você cobra o cartão. Para fornecer uma descrição diferente com base em pagamento feito, inclua o parâmetro statement_descriptor.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]"=card \
  -d statement_descriptor="Custom descriptor"

As descrições no extrato são limitadas a 22 caracteres, não podem usar os caracteres especiais <, >, ', " ou * e não podem ter apenas números. Quando usar descrições dinâmicas no extrato, o texto dinâmico é vinculado ao prefixo da descrição no extrato definido no Stripe Dashboard. Um asterisco (*) e um espaço em branco também são adicionados para separar a descrição no extrato padrão da parte dinâmica. Esses dois caracteres contam para o limite de 22 caracteres.

Armazenar informações em metadados

A Stripe aceita metadados nas solicitações mais comuns, como processamento de pagamentos. Os metadados não aparecem para o cliente nem são usados como referência para a recusa ou bloqueio de um pagamento no nosso sistema de prevenção de fraudes.

Por meio de metadados, você pode associar a atividade da Stripe às informações que considera relevantes.

Todos os metadados incluídos podem ser visualizados no Dashboard (por exemplo, ao consultar a página de um pagamento individual) e também estão disponíveis em relatórios comuns. Como exemplo, você pode anexar o ID do pedido da sua loja ao PaymentIntent desse pedido. Isso permite que você reconcilie facilmente os pagamentos na Stripe com os pedidos no seu sistema.

Se estiver usando o Radar for Fraud Teams, considere a possibilidade de enviar outros dados do cliente e do pedido como metadados. Assim, você pode gravar regras do Radar com atributos de metadados e ter mais informações disponíveis no Dashboard para agilizar seu processo de revisão.

Quando cria uma cobrança, o PaymentIntent copia os metadados para a cobrança. Atualizações posteriores nos metadados do PaymentIntent não modificam os metadados de cobranças criadas anteriormente pelo PaymentIntent.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]"=card \
  -d "metadata[order_id]"=6735