Aceitar um pagamento OXXO

Veja como aceitar OXXO, uma forma de pagamento comum no México.

Web

Dispositivos móveis

Cuidado

Esta seção trata de um produto herdado. Use o guia Aceitar um pagamento para ver o caminho de integração mais recente. Embora a Stripe ainda ofereça suporte a esse produto, ele pode terminar se o produto for descontinuado.

Usuários da Stripe no México podem aceitar pagamentos OXXO de clientes no México ao usar as APIs Payment Intents e Payment Methods. Os clientes pagam ao fornecer uma guia de pagamento OXXO com um número gerado e pagamento em espécie em uma loja de conveniência OXXO. Você é notificado pela Stripe após a conclusão do pagamento.

O que você está criando

Nome

E-mail

Configurar a Stripe
Lado do servidor

Primeiro, você precisa de uma conta da Stripe. Inscreva-se aqui.

Use nossas bibliotecas oficiais para acessar a API da Stripe no seu aplicativo:

Crie um PaymentIntent
Lado do servidor

A Stripe usa um objeto PaymentIntent para representar sua intenção de coletar o pagamento de um cliente, acompanhando mudanças de estado desde a criação da guia OXXO até seu pagamento.

Crie uma PaymentIntent no seu servidor com um valor e a moeda mxn (OXXO não aceita outras moedas). Se você já tiver uma integração usando a API Payment Intents, adicione oxxo à lista de tipos de forma de pagamento para seu PaymentIntent.

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.

Recupere o segredo do cliente de um endpoint do servidor usando a função fetch do navegador. Essa abordagem é melhor quando o lado do cliente é um aplicativo com uma única página, principalmente se criado com uma estrutura de front-end moderna como o React. Crie o endpoint do servidor que envia o segredo do cliente:

Em seguida, obtenha o segredo do cliente com JavaScript no lado do cliente:

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

Outras opções da forma de pagamento

Você pode especificar um parâmetro opcional expires_after_days nas opções da forma de pagamento para o PaymentIntent, definindo os dias corridos até o vencimento de uma guia OXXO. Por exemplo, se você criar uma guia OXXO na segunda-feira e a configuração de expires_after_days for 2, a guia vencerá na quarta-feira, às 23h59, horário da América/Mexico_City (UTC-6). O parâmetro expires_after_days pode ser de 1 a 7 dias. O padrão é 3 dias.

Coletar dados da forma de pagamento
Do lado do cliente

Crie um formulário de pagamento no cliente para obter os dados necessários para a cobrança:

Campo	Valor
`name`	Nome completo (nome e sobrenome) do cliente. O nome e o sobrenome precisam ter pelo menos dois caracteres cada um.
`email`	Endereço de e-mail completo do cliente.

checkout.html
<form id="payment-form">
  <div class="form-row">
    <label for="name">
      Name
    </label>
    <input id="name" name="name" required>
  </div>

  <div class="form-row">
    <label for="email">
      Email
    </label>
    <input id="email" name="email" required>
  </div>

  <!-- Used to display form errors. -->
  <div id="error-message" role="alert"></div>

  <button id="submit-button">Pay with OXXO</button>
</form>

Enviar o pagamento para a Stripe
Do lado do cliente

Quando o cliente optar por pagar com OXXO, use Stripe.js para enviar o pagamento à Stripe. Stripe.js é a nossa biblioteca principal de JavaScript para criação de fluxos de pagamento.

Inclua Stripe.js na sua página de checkout, adicionando o script ao head do seu arquivo HTML.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>

Crie uma instância de Stripe.js com o JavaScript a seguir em sua página de checkout.

client.js
// Set your publishable key. Remember to switch to your live publishable key in production!
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Use stripe.confirmOxxoPayment e o segredo do cliente do objeto PaymentIntent criado na etapa 2 para enviar os dados de cobrança do cliente.

Depois da confirmação, a Stripe abre automaticamente um modal que mostra a guia de pagamento OXXO ao cliente.

client.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const result = await stripe.confirmOxxoPayment(
    '{{PAYMENT_INTENT_CLIENT_SECRET}}',
    {
      payment_method: {
        billing_details: {
          name: document.getElementById('name').value,
          email: document.getElementById('email').value,
        },
      },
    });
  // Stripe.js will open a modal to display the OXXO voucher to your customer
  // This async function finishes when the customer closes the modal

  if (result.error) {
    // Display error to your customer
    const errorMsg = document.getElementById('error-message');
    errorMsg.innerText = result.error.message;
  }
});

Observação

stripe.confirmOxxoPayment pode levar vários segundos para finalizar. Nesse período, previna que o formulário seja reenviado e apresente um indicador de espera, como um spinnner. Se receber um erro, mostre-o ao cliente, reative o formulário e oculte o spinner.

Quando a guia de pagamento OXXO é criada, o valor da propriedade status do PaymentIntent indica requires_action. Verifique o status de um PaymentIntent no Dashboard ou inspecione a propriedade do status do objeto. Se a guia OXXO não for criada corretamente, inspecione o erro (error) recebido para entender o motivo (um e-mail com formato inválido, por exemplo).

Opcional: envie e-mail ao cliente com um link para a guia de pagamento

A Stripe envia um evento payment_intent.requires_action quando uma guia OXXO é criada. Se precisar enviar um e-mail ao cliente com o link para a guia, acesse o PaymentIntent para obter o link, após receber o evento. O campo hosted_voucher_url em payment_intent.next_action.oxxo_display_details contém o link para a guia.

Opcional: personalizar a guia

A Stripe permite personalizar as IUs exibidas para seus clientes na página Configurações da marca.

Estas configurações de marca podem ser aplicadas à guia:

Ícone: a imagem de sua marca e nome fantasia da empresa
Cor de destaque: usada no botão Copiar número
Cor da marca: usada como cor de fundo

Gerenciar eventos pós-pagamento
Lado do servidor

A OXXO é uma forma de pagamento com notificação posterior: os fundos não ficam disponíveis imediatamente. Os clientes podem não pagar a guia OXXO em uma loja de conveniência OXXO imediatamente após o checkout.

A Stripe envia um evento payment_intent.succeeded no dia útil seguinte (de segunda a sexta, exceto feriados do calendário mexicano) para todas as guias OXXO pagas. Use o Dashboard ou crie um gerenciador de webhooks para receber esses eventos e executar ações (por exemplo, enviar um e-mail de confirmação de pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de entrega).

Após a data de validade, o status do PaymentIntent muda para processing e o cliente não pode mais pagar a guia OXXO vencida. Se a guia não for paga até 23:59 (horário da Mexico_City/UTC-6) da data de validade, a Stripe envia um evento payment_intent.payment_failed até 10 dias corridos após a data de validade (na maioria dos casos, o evento é enviado dentro de 7 dias corridos). Por exemplo, se a guia OXXO vencer em 1º de setembro, o evento será enviado no máximo até 10 de setembro.

Evento	Descrição	Próximas etapas
`payment_intent.requires_action`	A guia OXXO é criada.	Espere que o cliente pague a guia OXXO.
`payment_intent.processing`	O cliente não pode mais pagar a guia OXXO.	Aguarde a confirmação ou falha do pagamento.
`payment_intent.succeeded`	O cliente pagou a guia OXXO antes do vencimento.	Execute o pedido de mercadorias ou serviços do cliente.
`payment_intent.payment_failed`	O cliente não pagou a guia OXXO antes do vencimento.	Entre em contato com o cliente por e-mail ou notificação push e solicite outra forma de pagamento.

Receber eventos e tomar providências comerciais

Manualmente

Use o Stripe Dashboard para ver todos os pagamentos da Stripe, enviar recibos por e-mail, lidar com repasses ou tentar novamente pagamentos com falha.

Veja os pagamentos de teste no Dashboard

Código personalizado

Crie um gerenciador de webhooks para ouvir eventos e criar fluxos personalizados de pagamentos assíncronos. Teste e depure a integração do webhook localmente usando a CLI da Stripe.

Crie um webhook personalizado

Testar a integração

Em uma área restrita, defina payment_method.billing_details.email de acordo com os valores a seguir ao chamar stripe.confirmOxxoPayment para testar diferentes cenários.

E-mail	Descrição
`{any_prefix}@{any_domain}`	Simula uma guia OXXO paga pelo cliente depois de 3 minutos, com o webhook `payment_intent.succeeded` recebido depois de cerca de 3 minutos. Em produção, este webhook chega em 1 dia útil. Exemplo: fulano@test.com
`{any_prefix}succeed_immediately@{any_domain}`	Simula uma guia OXXO paga imediatamente pelo cliente, com o webhook `payment_intent.succeeded` recebido depois de alguns segundos. Em produção, este webhook chega em 1 dia útil. Exemplo: succeed_immediately@test.com
`{any_prefix}expire_immediately@{any_domain}`	Simula uma guia OXXO que vence sem ser paga pelo cliente, com o webhook `payment_intent.payment_failed` recebido depois de alguns segundos. O campo `expires_after` em next_action.oxxo_display_details está configurado para o horário atual, independente da configuração do parâmetro `expires_after_days` em opções de forma de pagamento. Exemplo: expire_immediately@test.com
`{any_prefix}expire_with_delay@{any_domain}`	Simula uma guia OXXO que vence sem ser paga pelo cliente, com o webhook `payment_intent.payment_failed` recebido depois de 3 minutos. O campo `expires_after` em next_action.oxxo_display_details está configurado para 3 minutos no futuro, independente da configuração do parâmetro `expires_after_days` em opções de forma de pagamento. Exemplo: expire_with_delay@test.com
`{any_prefix}fill_never@{any_domain}`	Simula uma guia OXXO que expira sem ser paga pelo cliente, com o webhook `payment_intent.payment_failed` recebido depois de 1 dia e 2 dias corridos. Em produção, este webhook chega no mesmo momento que no modo de teste. Exemplo: fill_never@test.com

OpcionalExiba os dados do OXXO ao cliente
Do lado do cliente

OpcionalEnviar e-mails de instruções de pagamento

Validade e cancelamento

As guias do OXXO expiram após o carimbo de data e hora do UNIX expires_after e o cliente não pode pagá-lo após a expiração. As guias do OXXO não podem ser canceladas antes de expirar.

Depois do vencimento da guia OXXO, o status do PaymentIntent muda para requires_payment_method. Neste ponto, você pode confirmar o PaymentIntent com outra forma de pagamento ou cancelar.