Práticas recomendadas para uso do SourcesObsoleto

A flexibilidade da API Sources ajuda a reduzir as mudanças necessárias para aceitar as formas de pagamento que você for adicionando.

Fluxo típico dos pagamentos com cartão

Em um fluxo de checkout normal de pagamentos com cartão (exceto o 3D Secure), sua integração coleta os dados do cartão, cria uma fonte e a usa para fazer uma solicitação de cobrança. Como o cliente não precisa fazer mais nada e os pagamentos com cartão oferecem confirmação síncrona, podemos confirmar imediatamente se o pagamento foi bem-sucedido e os fundos foram garantidos. Não é preciso usar webhooks.

O uso obrigatório de webhooks

Outras formas de pagamento podem exigir outras ações do cliente (por exemplo, um redirecionamento) antes que a fonte se torne chargeable (cobrável) e possa ser usada na criação de uma solicitação de cobrança (por exemplo, o iDEAL). Normalmente, essa transição ocorre de forma assíncrona e pode até acontecer depois que o cliente saiu do seu site. Por esses motivos, a integração precisa de webhooks para determinar quando uma fonte se torna cobrável antes de criar a cobrança.

A Stripe envia os seguintes eventos de webhook para notificar mudanças no status da fonte:

Da mesma forma, ao criar uma cobrança, determinadas formas de pagamento assíncronas podem levar dias para cobrar e confirmar os fundos, exigindo que os webhooks saibam quando confirmar e, por fim, executar os pedidos.

A Stripe envia os seguintes eventos de webhook para notificar mudanças no status de uma cobrança:

Criar uma integração flexível

Para garantir a flexibilidade do processo de checkout e aceitar várias formas de pagamento, recomendamos a seguinte abordagem:

Criar a fonte

Quando criar Sources, registre o ID da fonte na representação interna do pedido para poder recuperá-lo quando receber e processar webhooks source.chargeable. Não se esqueça de indexar seus objetos de pedido pelo atributo source, para facilitar as buscas.

Criar a cobrança

A fonte é cobrada depois da entrega do evento source.chargeable. Quando receber o webhook, recupere a representação interna do pedido, localizando-a pelo ID de fonte recebido e verifique se o pedido está aguardando um pagamento.

Quando fizer uma solicitação de cobrança, use o ID do pedido interno como chave de idempotência para evitar qualquer possível condição de corrida. Além disso, se a fonte for reutilizável e você quiser usá-la novamente, anexe-a a um objeto Customer antes de cobrá-la. Consulte os guias Uso avulso ou recorrente e Sources e Customers para saber mais sobre como lidar com Sources de uso único e recorrente e como eles interagem com os objetos Customer.

De forma semelhante à criação da fonte, registro o ID da cobrança na representação interna do pedido para poder recuperá-lo quando receber e processar webhooks charge.succeeded.

Página de confirmação

Depois que o cliente realiza as ações necessárias para autorizar um pagamento (por exemplo, seguiu um redirecionamento), você deve apresentar uma página de confirmação que mostra o estado do pedido. Isso pode ser feito sondando internamente o pedido.

Como a latência de entrega dos webhooks não é garantida, se você quiser otimizar ainda mais a página de confirmação, sonde o status da fonte associada no código do lado do cliente. Quando você detectar que a fonte se tornou chargeable, poderá iniciar a criação de uma Charge usando essa fonte sem precisar aguardar a chegada do webhook source.chargeable.

Alguns tipos de fontes podem levar minutos (ou até dias) para se tornarem chargeable. Se você decidir sondar a fonte, recomendamos que estabeleça um tempo limite e informe ao cliente que o pedido está aguardando confirmação de pagamento e depois envie um e-mail de confirmação de pagamento de forma assíncrona. Veja na tabela baixo nossas recomendações de mensagens para o cliente para cada status de fonte.

A sondagem do lado do cliente será interrompida se o cliente sair da página. Isso significa que sua integração também precisa considerar o webhook source.chargeable para garantir que você continue acompanhando o pedido do cliente.

Se você está usando o Stripe.js, pode implementar a sua própria sondagem com stripe.retrieveSource():

// In order-confirmation-page.js

const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

// After some amount of time, we should stop trying to resolve the order synchronously:
const MAX_POLL_COUNT = 10;
let pollCount = 0;

const pollForSourceStatus = async () => {
  const {source} = await stripe.retrieveSource({id: SOURCE_ID, client_secret: CLIENT_SECRET})
  if (source.status === 'chargeable') {
    // Make a request to your server to charge the Source.
    // Depending on the Charge status, show your customer the relevant message.
  } else if (source.status === 'pending' && pollCount < MAX_POLL_COUNT) {
    // Try again in a second, if the Source is still `pending`:
    pollCount += 1;
    setTimeout(pollForSourceStatus, 1000);
  } else {
    // Depending on the Source status, show your customer the relevant message.
  }
};

pollForSourceStatus();

A tabela abaixo contém recomendações de possíveis mensagens que podem ser mostradas ao cliente conforme o status da fonte.

Após criar uma Charge (e se o usuário permanecer na página de confirmação), você poderá mostrar as seguintes mensagens de acordo com o status da Charge:

Confirmação do pedido

Confirme o pedido só depois que receber o webhook charge.succeeded (isso pode ocorrer imediatamente, mas também pode demorar). Envie um e-mail ao cliente neste ponto porque a confirmação do pagamento pode levar dias no caso de pagamentos assíncronos.

Cancelamentos e falhas

Ouça os webhooks source.canceled e source.failed e cancele o pedido associado à fonte envolvida. Se seguir as práticas recomendadas acima, você não deve receber o webhook source.canceled para fontes previamente chargeable (pois o gerenciador de source.chargeable criar imediatamente uma cobrança para evitar o cancelamento da fonte). Você continuará recebendo os webhooks source.canceled para fontes pending que nunca se tornaram chargeable. Normalmente, isso indica que o cliente saiu do fluxo de checkout antes de concluí-lo. Você também pode receber um webhook source.failed quando o cliente recusar o pagamento ou ocorrer um problema técnico no esquema de pagamentos.

Você também deve escutar os webhooks charge.failed, para assegurar o cancelamento do pedido associado à cobrança recebida.

Para cada um desses eventos, recomendamos que você notifique o cliente que o pedido falhou e, se quiser, convide-o para voltar ao fluxo de pagamento.