Pular para o conteúdo
Criar conta ou Entrar
O logotipo da documentação da Stripe
/
Criar contaLogin
Visão geralAtualize sua integração
Pagamentos online
Visão geralEncontre seu caso de usoUsar o Managed Payments
Pagamentos presenciais
Formas de pagamento
Cenários de pagamento
Muito mais que pagamentos

Aceitar um pagamento OXXO

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

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

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:

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

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 um 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 o seu PaymentIntent.

Command Line
curl
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "amount"=1099 \
  -d "currency"="mxn" \
  -d "payment_method_types[]"="oxxo"

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:

main.rb
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

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:

CampoValor
nameNome completo (nome e sobrenome) do cliente. O nome e o sobrenome precisam ter pelo menos dois caracteres cada um.
emailEndereç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/clover/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;
  }
});

Nota

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.

EventoDescriçãoPróximas etapas
payment_intent.requires_actionA guia OXXO é criada.Espere que o cliente pague a guia OXXO.
payment_intent.processingO cliente não pode mais pagar a guia OXXO.Aguarde a confirmação ou falha do pagamento.
payment_intent.succeededO cliente pagou a guia OXXO antes do vencimento.Execute o pedido de mercadorias ou serviços do cliente.
payment_intent.payment_failedO 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.

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.

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-mailDescriçã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

Recomendamos usar o Stripe.js para exibir a guia OXXO com confirmOxxoPayment. Mas você também pode exibir a guia aos clientes manualmente.

Para indicar que você vai gerenciar a próxima ação para exibir os dados da OXXO ao seu cliente, especifique handleActions: false ao chamar stripe.confirmOxxoPayment na etapa 4.

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,
        },
      },
    }, {handleActions: false},
  );

  if (result.error) {
    // Display error to your customer
    const errorMsg = document.getElementById('error-message');
    errorMsg.innerText = result.error.message;
  } else {
    // An OXXO voucher was successfully created
    const amount = result.paymentIntent.amount;
    const currency = result.paymentIntent.currency;

    const details = result.paymentIntent.next_action.oxxo_display_details;
    const number = details.number;
    const expires_after = details.expires_after;

    // Handle the next action by displaying the OXXO details to your customer

    // You can also use the generated hosted voucher
    const hosted_voucher_url = result.paymentIntent.next_action.oxxo_display_details.hosted_voucher_url;
  }
});

Inclua, no mínimo, o seguinte:

DetalheDescrição

Logotipo OXXO

Insira o logo da OXXO na guia. Baixe o logo aqui.

NúmeroLocalize o número no objeto PaymentIntent em next_action.oxxo_display_details.number.
Data de validadeLocalize o carimbo de data e hora UNIX para vencimento da guia OXXO, no PaymentIntent em next_action.oxxo_display_details.expires_after.
ValorO valor a ser cobrado.
MoedaAs guias OXXO sempre são cobradas em pesos mexicanos.
Código de barrasGere o código de barras a partir do número, usando Code 128. O código de barras deve ter cerca de 7,5 cm de largura quando impresso. Para telas de celular, faça com que seja possível ampliar o código de barras, para que eles possam ser lidos nos caixas das lojas de conveniência OXXO. Você pode usar uma biblioteca externa, como JSBarcode.
Instruções de pagamentoInstruções de pagamento para o cliente. Veja as versões em português e espanhol, abaixo.

Instruções de pagamento da OXXO

Instruções de pagamento da OXXO:

  1. Entregue a guia ao caixa para fazer a leitura do código de barras.
  2. Faça o pagamento em dinheiro ao caixa.
  3. Após a conclusão do pagamento, guarde o recibo para seu controle.
  4. Em caso de dúvidas, entre em contato com o comerciante.
HTML
CSS
JavaScript
No results
<!-- Include a library for generating OXXO bar codes, such as JsBarcode -->
<!-- <script src="https://cdn.jsdelivr.net/jsbarcode/3.6.0/barcodes/JsBarcode.code128.min.js"></script> -->

<div class="result-oxxo">
  <img width="100px" src="/images/payments/oxxo.png">
  <div class="amount">MX <span class="order-amount"></span></div>
  <div>Expires <span class="oxxo-expiry-date"></span></div>
  <div class="oxxo-display"></div>

  <button onclick="window.print()">Print</button>

  <div class="instructions">
    Instructions to pay your OXXO:
    <ol>
      <li><p>Give the voucher to the cashier to scan the barcode.</p></li>
      <li><p>Provide cash payment to the cashier.</p></li>
      <li><p>After the payment is complete, keep the receipt of your payment for your records.</p></li>
      <li><p>For any questions or clarification, please contact the merchant.</p></li>
    </ol>
  </div>
</div>

Geralmente, os clientes imprimem e levam a guia a uma loja de conveniência da OXXO. Você pode oferecer um botão para impressão fácil e/ou enviar um e-mail com a guia para o cliente. Faça um teste da impressão e confira o tamanho do código de barras (deve ter cerca de 7,5 cm de largura).

OpcionalEnviar e-mails de instruções de pagamento

Você pode habilitar e-mails com instruções de pagamento OXXO na página Configurações de e-mail no Dashboard. Após a habilitação, a Stripe envia e-mails com instruções de pagamento após a confirmação do PaymentIntent. Os e-mails contêm o número OXXO e um link para a página da guia hospedada na Stripe.

Nota

Em ambientes de teste, os e-mails de instruções só são enviados para endereços de e-mail vinculados à conta Stripe.

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.