Pagamentos QR em postos de combustíveis

1. O usuário escaneia o código QR no aplicativo Mercado Pago ou Mercado Livre. O QR contém o STORE_ID com a informação da posição onde a venda foi feita.

2. O nosso servidor consulta o seu servidor para a última venda pendente para essa posição nessa filial.

3. Seu servidor procura a última ordem de pagamento pendente e, se existir, retorna o corpo do pedido com QR.

4. Seu servidor retorna o pedido para o nosso servidor e, portanto, o pedido é criado no celular do usuário.

5. O usuário segue o fluxo de compra e confirma o pagamento.

6. Imediatamente após o processamento do pagamento é enviada uma notificação para o servidor [IPN] (https://www.mercadopago.com.uy/developers/pt/guides/notifications/ipn/) relatando que há algo novo.

7. Com o ID de pagamento, você pode pesquisar o pagamento e continuar os seus processos internos.

   Se o status for 'approved', o pagamento deve ser creditado. Por outro lado, se for rejected, o aplicativo tentará novamente o pagamento solicitando outro meio de pagamento.

8. Pronto! Informe ao cliente que o pagamento foi processado corretamente.

Primeiro você deve se familiarizar com os seguintes conceitos, já que você os usará durante a integração.

Além dos conceitos anteriores, você também deve conhecer os objetos com os quais trabalharemos.

{
    "name":"Fornecedor 1", 
    "external_id": "pos_1",
    "category": 473000,
    "store_id": "123456",
    "url": "api.integration.com?apies=1&pos=1"   
}

Definições

• name: Nome descritivo. É uma String de até 45 caracteres.
• external_id: É o identificador único do ponto de venda. É um código alfanumérico definido por você, não pode conter espaços ou caracteres especiais e letras maiúsculas não diferenciam maiúsculas de minúsculas. É uma String de até 40 caracteres.
• category : Código da MCC que indica o item do ponto de venda. Os valores possíveis são:
  • Gastronomia: 621102
  • Companhia de petróleo ou posto de gasolina: 473000
  • Geral: null
• store_id: É um número identificador da filial ao qual o ponto de venda pertence. O id da loja.
• url: URL do servidor do sistema de gerenciamento, que retorna os dados de um fornecedor ou bomba de uma estação específica.

{
   "collector_id": 178106235,
   "sponsor_id": 334249281,
   "items":[
      {
         "title":" $500.00 de Premium",
         "currency_id": "UYU",
         "description":"$500.00 de Premium",
         "quantity": 1.0,
         "unit_price": 500.00
      }
   ],
   "external_reference":"45ea80da",
   "notification_url":"https://www.seusite.com/notifiaction",
   "loyalty":{
      "program":"payback",
      "transaction_id":"45ea80da",
      "invoice_number":"3592",
      "transaction_date":"2018-09-21T12:33:13.000+00:00",
      "transaction_amount":500.00,
      "store_id":"802",
      "products":[
         {
            "code":"1",
            "quantity":1.0,
            "unit":"litro",
            "unit_price":500.00
         }
      ],
      "cashier_identification":{
         "type":"CPF",
         "number":"00000000"
      },
      "period":"0000",
      "shift":"1",
      "affinity_plan":"7"
   }
}

Definições

• collector_id: Long. Identificador da conta do Mercado Pago para o qual os pagamentos serão creditados.
• sponsor_id: Long. Identificador de uma conta de Mercado Pago que integra a solução.
• external_reference: String. Referência para sincronizar com seu sistema.
• notification_url: String. URL à qual serão enviadas as notificações, definida pelo integrador.
• items: Array. Lista dos produtos, onde cada item é um object com os seguintes campos:
  • title: String. Nome do produto.
  • quantity: Inteiro. Quantidade deste produto.
  • unit_price: Decimal. Preço unitário do produto.
• loyalty: Objeto. Dados necessários para marcar pontos em um programa de fidelidade específico:
  • program: String. Programa de fidelização (serviclub, payback, etc.)
  • transaction_id: String. Número de transação.
  • invoice_number: String. Número do comprovante.
  • transaction_date: String. Data e hora da transação (ISO 8601).
  • transaction_amount: Decimal. Valor total da transação.
  • store_id: String. Identificador exclusivo da empresa (identificador da estação de serviço ou APIES).
  • products: Array. Lista de produtos comprados com os seguintes atributos
    • code: String. Código do produto.
    • quantity: Decimal o inteiro. Por exemplo 20.50 litros.
    • unit_price: Decimal. Preço unitário do produto.
    • unit: String. Unidade de medida, se aplicável (litro, etc.)
  • cashier_identification: Object. Dados do funcionário
    • type: String. Tipo de documento (CPF, CNPJ, etc.)
    • number: String. Id do documento.
  • period: String. Número do período.
  • shift: String. Número do turno.
  • affinity_plan: String. Plano de afinidade.

{
    "id": 420101010101,
    "external_reference": "id de transação interno",
    "status": "approved",
    "status_detail": "accredited",
    ...
}

Definições

• id: Id único gerado por Mercado Pago (necessário para realizar devoluções).

• external_reference: Mesma String alfanumérica que você adicionou ao criar o pedido.

• status: Estado do pagamento.

  • approved: O pagamento foi aprovado e creditado.

  • rejected: O pagamento foi rejeitado. O usuário pode tentar novamente o pagamento.

  • refunded: O pagamento foi devolvido ao usuário.

  • charged_back: Um estorno foi feito no cartão de crédito do comprador.

• status_detail: Informações detalhadas sobre o status atual ou o motivo da rejeição.

Consulte a documentação completa sobre este objeto em nossa Referencia API.

É necessário que você tenha uma URL do seu software de gerenciamento que retorne os dados do fornecedor ou bomba de uma determinada estação. Ele contém os parâmetros adicionais que são desejados na consulta (APIES da estação, fornecedor ou identificador de bomba, etc.). Por exemplo: https: //www.mycompany.com/pay-mp?Apies=6232&pos=1

Essa URL ou endpoint deve retornar as informações com as quais o corpo do pedido que adicionaremos ao QR será criado.

Recomendamos usar o campo external_reference para poder associar o pedido (e seu eventual pagamento) à compra. É um código alfanumérico de até 256 caracteres definido pelo integrador, não pode conter espaços ou caracteres especiais e não faz distinção entre maiúsculas e minúsculas.

Se o seu sistema tiver um programa de fidelidade, você deve adicionar o campo de fidelidade que fornece as informações necessárias para creditar os pontos ao comprador assim que o pagamento for aprovado.

A resposta esperada deste endpoint contém o cabeçalho Content-Type: application/json e espera-se que ele responda com um estadoHTTP 200 (OK); Além disso, você deve incluir no corpo um JSON correspondente ao objeto order.

Em caso de erro, será retornado um código de status HTTP 400 (Bad Request), e no corpo da resposta um JSON com o seguinte formato:

{
	"error": {
		"type": "XXX",
		"message": "YYYY"
	}
}

Donde

A message é opcional, corresponde a uma explicação de texto simples da causa do problema.

Seja na fase de teste ou de produção, você deve informar a URL do Mercado Pago para configurá-lo e iniciar o teste.

Você deve criar um código QR para cada fornecedor ou bomba com uma url configurada dentro do POS.

API de criação de QRs

curl -X POST \
-H 'Authorization: Bearer ACCESS_TOKEN' \
https://api.mercadopago.com/pos \
-d \
'{
    "name":"Caixa principal", 
    "fixed_amount": true,
    "category": 621102,
    "store_id": "123456",
    "external_id": "4lph4num3r1c",
    "url": "api.integration.com?apies=1&pos=1"   
}'

Depois que o usuário fizer o pagamento, você poderá obter os dados usando qualquer uma das seguintes maneiras:

1. IPN: Quando o pagamento é criado, enviamos uma notificação via webhook para a URL configurado no notification_url da ordem, você deve se inscrever para o tipo de notificações merchant_order.
2. Faça a pesquisa de pagamento usando o external_reference como critério de pesquisa.

Haverá momentos em que você precisará efetuar a devolução parcial ou total de um pagamento.

Devolução total

curl -X POST \
-H 'Authorization: Bearer ACCESS_TOKEN' \
https://api.mercadopago.com/v1/payments/PAYMENT_ID/refunds

Devolução parcial

curl -X POST \
-H 'Authorization: Bearer ACCESS_TOKEN' \
https://api.mercadopago.com/v1/payments/PAYMENT_ID/refunds \
-d '{ "amount": 10.50 }'

Para testar a integração, você deve criar dois usuários de teste: um comprador, outro fornecedor:

Você usará o usuário vendedor para criar o QR e completar o dado collector_id; Assim, com o usuário comprador, acesse o aplicativo Mercado Pago ou Mercado Livre e complete o fluxo.

Verifique os dados de teste: teste usuários e cartões de teste que podem ser usados.

Casos de teste

Aqui você pode encontrar nosso dicionário de erros.

Consulte a documentação completa sobre os relatórios do Mercado Pago.