Recursos para IA

Integrar o processamento de pagamentos

O processamento de pagamentos com o Mercado Pago Point é realizado por meio da criação de orders associadas a uma transação de pagamento. Essas orders permitem que seu sistema inicie e acompanhe cada pagamento processado no terminal, relacione-o à operação correspondente por meio de external_reference e mantenha a conciliação atualizada a partir das alterações de status.

No modo PDV, o vendedor cria uma order, que é enviada automaticamente ao terminal Point indicado para que o comprador realize o pagamento.

No modo SELF_SERVICE, a order é processada em tempo real entre o totem utilizado pelo comprador e o Mercado Pago, sem intervenção manual. Nesse modo, o terminal fica dedicado ao processamento de pagamentos, com acesso restrito às configurações e funcionalidades avançadas.

Esta integração permite criar, processar e cancelar orders, além de realizar reembolsos e consultar informações e atualizações de status das transações.

Para definir se o parcelamento será com ou sem juros em transações com cartão de crédito, é necessário configurar essa opção previamente na sua conta do Mercado Pago, antes da criação da order. Consulte as instruções para configurar o parcelamento com ou sem juros.

Criar uma order

Para começar a processar pagamentos com o Point a partir dos pontos de venda, primeiro você precisa identificar a qual terminal a order será atribuída.

Lembre-se de que o terminal deve estar configurado no modo PDV ou SELF_SERVICE.

Para isso, envie uma solicitação ao endpoint Obter terminalsGET, utilizando seu Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais, nunca deve ser exposta no frontend e começa com o prefixo `APP_USR`.Acessar as credenciais de teste.

Caso necessário, é possível filtrar a busca usando os query params opcionais store_id e pos_id, que correspondem aos identificadores da loja e do caixa retornados na resposta à criação de cada um.

curl
curl -X GET \
    'https://api.mercadopago.com/terminals/v1/list?limit=50&offset=0&store_id=12354567&pos_id=23545678' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'

A resposta dessa solicitação exibirá os terminals associados à sua conta, permitindo que você selecione aquele que deseja usar para criar sua order.

A identificação do terminal pode ser feita pelos últimos caracteres do campo id, que correspondem ao número de série impresso na etiqueta traseira do terminal físico.

json
{
  "data": {
    "terminals": [
      {
        "id": "NEWLAND_N950__N950NCB801293324",
        "pos_id": "23545678",
        "store_id": "12354567",
        "external_pos_id": "SUC0101POS",
        "operating_mode": "PDV | SELF_SERVICE"
      }
    ]
  },
  "paging": {
    "total": 1,
    "offset": 0,
    "limit": 50
  }
}

Em seguida, você deve criar a order. Para isso, envie uma solicitação ao endpoint /v1/ordersPOST, incluindo seu Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais, nunca deve ser exposta no frontend e começa com o prefixo `APP_USR`.Acessar as credenciais de teste, e o ID do terminal ao qual deseja atribuir a order, obtido no passo anterior.

A mesma solicitação de criação é utilizada para os modos PDV e SELF_SERVICE. No modo SELF_SERVICE, você pode definir por quanto tempo cada tela permanecerá disponível usando o parâmetro opcional config.point.screen_time. No modo PDV, config.point.screen_time não se aplica.

Caso deseje, ao definir cartão de crédito como meio de pagamento padrão (default_type=credit_card), você poderá utilizar a pré-configuração de parcelas e definir qual será o tipo de parcelamento (com ou sem juros), a quantidade de parcelas e quem será o responsável financeiro pelo custo deste parcelamento. Para ativar a pré-configuração, inclua os campos default_installments e installments_cost dentro do objeto config.payment_method ao criar a order.

A pré-configuração de parcelas deve ser habilitada previamente em sua conta pela equipe comercial do Mercado Pago. Entre em contato com seu assessor comercial para solicitar a ativação.

curl
curl -X POST \
    'https://api.mercadopago.com/v1/orders' \
    -H 'Content-Type: application/json' \
    -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
    -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
    -d '{
        "type": "point",
        "external_reference": "ext_ref_1234",
        "expiration_time": "PT16M",
        "transactions": {
            "payments": [
                {
                    "amount": "24.00"
                }
            ]
        },
        "config": {
            "point": {
                "terminal_id": "NEWLAND_N950__N950NCB801293324",
                "print_on_terminal": "no_ticket",
                "ticket_number": "S0392JED"
            },
            "payment_method": {
                "default_type": "credit_card",
                "default_installments": 3,
                "installments_cost": "seller"
            }
        },
        "description": "Point Smart 2",
        "integration_data": {
            "platform_id": "dev_1234567890",
            "integrator_id": "dev_1234567890",
            "sponsor": {
                "id": "446566691"
            }
        }
    }'

Consulte na tabela abaixo as descrições dos parâmetros que possuem alguma particularidade importante que deve ser destacada.

Atributo	Tipo	Descrição	Obrigatoriedade
`Authorization`	Header	Refere-se ao Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais, nunca deve ser exposta no frontend e começa com o prefixo `APP_USR`.Acessar as credenciais de teste.	Obrigatório
`X-Idempotency-Key`	Header	Chave de idempotência. Essa chave garante que cada solicitação seja processada apenas uma vez, evitando duplicidades. Use um valor exclusivo no header da requisição, como um UUID V4 ou uma string aleatória.	Obrigatório
`type`	Body.String	Tipo de order, associado à solução do Mercado Pago para a qual está sendo criada. Para pagamentos com Mercado Pago Point, o único valor possível é `point`.	Obrigatório
`external_reference`	Body.String	É uma referência externa da order, atribuída no momento de sua criação. Deve ser um valor único para cada order e não pode conter dados PII. O limite máximo permitido é de 64 caracteres e os permitidos são: letras maiúsculas e minúsculas, números e os símbolos de hífen (-) e sublinhado(_).	Obrigatório
`expiration_time`	Body. String	Indica o período de validade da order de pagamento a partir de sua criação. Durante esse tempo, a order estará disponível para ser processada pelo cliente; caso não seja processada dentro do prazo especificado, expirará automaticamente e não poderá ser utilizada, sendo necessário gerar uma nova order de pagamento para continuar. O valor mínimo permitido é de 30 segundos (PT30S) e o máximo é de 3 horas (PT3H). Exemplos de uso: para uma expiração de 30 segundos: "PT30S", para 10 minutos: "PT10M" e para 1 hora e 15 minutos: "PT1H15M".	Opcional
`transactions.payments.amount`	Body.String	Valor total da order de pagamento. Aceita até 2 casas decimais, e o separador decimal é opcional. Exemplos válidos: `10`, `10.5` e `10.00`.	Obrigatório
`config.point.screen_time`	Body.String	Disponível apenas no modo SELF_SERVICE. Define, no formato ISO 8601, por quanto tempo as telas do terminal permanecem disponíveis para processar a order. Aceita valores de 5 segundos (`PT5S`) a 5 minutos (`PT5M`); se omitido, utiliza 15 segundos (`PT15S`). O tempo é reiniciado quando a tela muda ou o usuário interage com o terminal. Se a order não for processada nesse período, será cancelada. A tela de leitura do cartão é exibida por no máximo 60 segundos, mesmo que um valor superior seja configurado.	Opcional
`config.point.terminal_id`	Body.String	Identificador do terminal Point que receberá a order. Você deve enviá-lo exatamente como foi retornado na requisição de Obter terminalsGET, como no seguinte exemplo: `NEWLAND_N950__N950NCB801293324`.	Obrigatório
`config.point.print_on_terminal`	Body.String	Define se o terminal imprime o comprovante da transação. No modo PDV, aceita `seller_ticket` —valor padrão— ou `no_ticket`. No modo SELF_SERVICE, aceita `seller_ticket`, `no_ticket` ou `buyer_ticket` —valor padrão—.	Opcional
`config.payment_method.default_type`	Body.String	Indica o meio de pagamento que o terminal aceitará. Se não for enviado, o terminal aceitará todos os meios de pagamento e o cliente poderá escolher o que desejar. Para usar a pré-configuração de parcelas, é obrigatório enviá-lo como `credit_card`. Valores possíveis: `debit_card` (aceita apenas pagamentos com cartão de débito), `credit_card` (aceita apenas pagamentos com cartão de crédito) e `qr` (aceita apenas pagamentos com código QR). No modo SELF_SERVICE, os valores aceitos são `credit_card` e `debit_card`; `qr` está disponível apenas no modo PDV.	Opcional
`config.payment_method.default_installments`	Body.Integer	Quando o meio de pagamento padrão for cartão de crédito (`default_type = credit_card`), envie este parâmetro para informar ao terminal que a quantidade de parcelas foi pré-selecionada, pulando a tela de seleção. Caso o cartão utilizado para o pagamento não suporte o número de parcelas definido, o terminal exibirá a tela de seleção.	Condicional
`config.payment_method.installments_cost`	Body.String	Quando o meio de pagamento padrão for cartão de crédito (`default_type=credit_card`) e `default_installments` for maior que `1`, envie este parâmetro para definir quem assumirá o custo financeiro do parcelamento. Valores possíveis: `seller` (o vendedor assume o custo financeiro, portanto o parcelamento é sem juros; ele deve ter o recurso de parcelamento habilitado em sua conta Mercado Pago, com pelo menos um plano ativo que inclua a quantidade de parcelas solicitada e o valor da transação deve atingir o mínimo exigido por esse plano) e `buyer` (o comprador assume o custo financeiro, portanto o parcelamento é com juros). Se `default_installments=1`, envie `seller` ou omita este campo, pois uma única parcela não tem custo financeiro. Se `default_installments` for maior que `1` e este campo não for enviado, a API retornará o erro `400 - missing_installments_cost`.	Condicional

Para mais detalhes sobre os parâmetros que devem ser enviados nesta requisição, consulte nossa Referência de APIAPI.

Se a solicitação for bem-sucedida, a resposta retornará uma order com status created.

json
{
  "id": "ORD00001111222233334444555566",
  "type": "point",
  "user_id": "5238400195",
  "external_reference": "ext_ref_1234",
  "description": "Point Smart 2",
  "expiration_time": "PT16M",
  "processing_mode": "automatic",
  "country_code": "AR",
  "integration_data": {
    "application_id": "1234567890",
    "platform_id": "dev_1234567890",
    "integrator_id": "dev_1234567890",
    "sponsor": {
      "id": "446566691"
    }
  },
  "status": "created",
  "status_detail": "created",
  "created_date": "2024-09-10T14:26:42.109320977Z",
  "last_updated_date": "2024-09-10T14:26:42.109320977Z",
  "config": {
    "point": {
      "terminal_id": "NEWLAND_N950__N950NCB801293324",
      "print_on_terminal": "no_ticket",
      "ticket_number": "S0392JED"
    },
    "payment_method": {
      "default_type": "credit_card",
      "installments_cost": "seller",
      "default_installments": 3
    }
  },
  "transactions": {
    "payments": [
      {
        "id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
        "amount": "24.00",
        "status": "created"
      }
    ]
  }
}

Como a order é a base do processamento do pagamento, armazene seu ID (order_id) e o ID do pagamento (transactions.payments.id) obtidos na criação e relacione-os com external_reference. Esses dados permitirão realizar outras operações, consultar suas notificações e manter a conciliação com seu sistema. Além disso, consulte nossa documentação na seção Recursos para conhecer os possíveis status de uma order e de uma transação.

Depois de criada, a order será enviada ao terminal atribuído.

No modo PDV, se a order não for carregada automaticamente, pressione o botão Atualizar ou, se o terminal possuir, o botão verde para recebê-la. Se você não preencher o parâmetro expiration_time, a order expirará 15 minutos após sua criação.

No modo SELF_SERVICE, a order é processada sem intervenção manual. Se você não preencher o parâmetro expiration_time, a order expirará 15 segundos após sua criação. Se o comprovante de pagamento for impresso pelo totem, envie no_ticket em config.point.print_on_terminal para evitar sua impressão pelo terminal Point.

Cancelar uma order

O cancelamento de uma order pode ser solicitado via API ou, quando ela estiver no status at_terminal, realizado diretamente no terminal.

Para acompanhar o cancelamento de uma order em at_terminal, seja ele solicitado via API ou realizado no terminal, configure previamente suas notificações Webhooks. A notificação confirma que o cancelamento foi efetivado e permite manter sua conciliação.

Se o status da order for created, o cancelamento deve ser feito via API e é processado de forma síncrona.
Se o status for at_terminal, isso indica que a order já foi recebida pelo terminal. Nesse caso, o cancelamento pode ser solicitado de forma assíncrona via API ou realizado diretamente no terminal.

Escolha a opção que melhor se adequa às suas necessidades para saber como cancelar sua order.

Para cancelar uma order com status created ou at_terminal via API, envie uma solicitação ao endpoint /v1/orders/{order_id}/cancelPOST, incluindo seu Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais, nunca deve ser exposta no frontend e começa com o prefixo `APP_USR`.Acessar as credenciais de teste e o ID da order obtido na resposta à sua criação.

Se o header x-allow-cancelable-status não for enviado ou tiver um valor diferente de at_terminal, a solicitação de cancelamento via API de uma order em status=at_terminal retornará o erro 409 cannot_cancel_order.

Além disso, o recurso está disponível em terminals Point Smart 1 e Point Smart 2 que estejam com a versão de software atualizada para a última disponível. Caso contrário, a solicitação será tratada como se o header não tivesse sido enviado e retornará o mesmo erro.

curl
curl -X POST \
    'https://api.mercadopago.com/v1/orders/{{ORDER_ID}}/cancel' \
    -H 'Content-Type: application/json' \
    -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
    -H 'x-allow-cancelable-status: at_terminal' \
    -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'

O resultado depende do status da order no momento da solicitação:

Para created, o cancelamento é síncrono e a API retorna HTTP 200, com a order em status=canceled e o pagamento em status_detail=canceled_by_api. O header x-allow-cancelable-status é opcional e, quando enviado, é ignorado.
Para at_terminal, a API aceita a solicitação de forma assíncrona e retorna HTTP 202. A order permanece em status=at_terminal, enquanto o pagamento passa a ter status_detail=cancellation_requested, até que uma notificação Webhook confirme o cancelamento. Se o pagamento já estiver em processamento, o terminal poderá priorizá-lo e não concluir o cancelamento; por isso, a resposta HTTP 202 não deve ser interpretada como a confirmação final.

Resposta para uma order em `created`

json
{
  "id": "ORD00009999222233334444555566",
  "user_id": "5238400195",
  "type": "point",
  "external_reference": "ext_ref_1234",
  "description": "Point Smart 2",
  "expiration_time": "PT16M",
  "country_code": "AR",
  "processing_mode": "automatic",
  "integration_data": {
    "application_id": "1234567890",
    "platform_id": "dev_1234567890",
    "integrator_id": "dev_1234567890",
    "sponsor": {
      "id": "446566691"
    }
  },
  "status": "canceled",
  "status_detail": "canceled",
  "created_date": "2024-09-10T14:26:42.109320977Z",
  "last_updated_date": "2024-09-10T14:26:42.109320977Z",
  "config": {
    "point": {
      "terminal_id": "NEWLAND_N950__N950NCB801293324",
      "print_on_terminal": "no_ticket",
      "ticket_number": "S0392JED"
    },
    "payment_method": {
      "default_type": "credit_card",
      "default_installments": 3,
      "installments_cost": "seller"
    }
  },
  "transactions": {
    "payments": [
      {
        "id": "PAY01J67CQQH5904WDBVZEM4JMEP4",
        "amount": "24.00",
        "status": "canceled",
        "status_detail": "canceled_by_api"
      }
    ]
  }
}

Resposta para uma order em `at_terminal`

json
{
  "id": "ORD00009999222233334444555566",
  "status": "at_terminal",
  "status_detail": "at_terminal",
  "transactions": {
    "payments": [
      {
        "id": "PAY01J67CQQH5904WDBVZEM4JMEP4",
        "status": "at_terminal",
        "status_detail": "cancellation_requested"
      }
    ]
  }
}

A resposta HTTP 202 confirma apenas que a solicitação foi aceita. Considere a order cancelada somente após receber a confirmação por meio das notificações Webhooks.

Reembolsar uma order

Caso necessário, é possível reembolsar uma order criada por meio da nossa API. Este endpoint permite realizar a devolução total ou parcial de uma transação de pagamento associada à order. Para solicitar um reembolso total, não é necessário enviar um body na requisição. Já para o reembolso parcial, é preciso informar no body o valor a ser reembolsado e o identificador da transação.

Uma order poderá ser reembolsada via API até 90 dias após o pagamento ter sido realizado. Após esse prazo, não será mais possível realizar a devolução. Em algumas orders, dependendo da adquirente e da bandeira do cartão, o reembolso deverá ser processado diretamente no terminal físico, já que é necessário inserir o cartão no dispositivo.

Escolha a opção que melhor se adequa às suas necessidades e siga as instruções correspondentes.

Para realizar o reembolso total de uma order, envie uma solicitação ao endpoint /v1/orders/{order_id}/refundPOST sem enviar o body na requisição. Certifique-se de incluir seu Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais, nunca deve ser exposta no frontend e começa com o prefixo `APP_USR`.Acessar as credenciais de teste. Também é necessário informar o ID da order (order_id) que deseja reembolsar, obtido na resposta à sua criação.

curl
curl -X POST \
    'https://api.mercadopago.com/v1/orders/{{ORDER_ID}}/refund' \
    -H 'Content-Type: application/json' \
    -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
    -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'

Se a solicitação for bem-sucedida, a resposta trará o status=refunded e um novo nó transactions.refunds, que irá conter os detalhes do reembolso, além do ID do pagamento original (transactions.payments.id) e o ID da transação (transaction_id) de reembolso.

json
{
  "id": "ORD00001111222233334444555566",
  "status": "refunded",
  "status_detail": "refunded",
  "transactions": {
    "refunds": [
      {
        "id": "REF01J67CQQH5904WDBVZEM1234D",
        "transaction_id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
        "reference_id": "12345678",
        "amount": "24.00",
        "status": "processed"
      }
    ]
  }
}

Consultar dados de uma order

Se necessário, você pode consultar os dados de uma order e suas transações associadas, sejam pagamentos ou reembolsos, incluindo seus status ou valores.

Embora o uso recorrente desta consulta via API não seja recomendado, ela pode ser útil caso você precise de informações adicionais sobre o pedido.

Para realizar a consulta, envie uma solicitação ao endpoint /v1/orders/{order_id}GET, incluindo o Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais, nunca deve ser exposta no frontend e começa com o prefixo `APP_USR`.Acessar as credenciais de teste, além do ID da order (order_id) obtido na resposta à sua criação.

Esta solicitação está disponível apenas para orders criadas há menos de 3 meses. Para acessar informações de orders mais antigas, é necessário entrar em contato com nosso serviço de atendimento ao cliente.

curl
curl -X GET \
    'https://api.mercadopago.com/v1/orders/{{ORDER_ID}}' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'

Se a solicitação for bem-sucedida, a resposta retornará todas as informações da order, incluindo seu status, o status do pagamento e/ou o status do reembolso em tempo real:

json
{
  "id": "ORD00001111222233334444555566",
  "user_id": "5238400195",
  "type": "point",
  "external_reference": "ext_ref_1234",
  "processing_mode": "automatic",
  "description": "Point Smart 2",
  "expiration_time": "PT16M",
  "country_code": "AR",
  "integration_data": {
    "application_id": "1234567890",
    "platform_id": "dev_1234567890",
    "integrator_id": "dev_1234567890",
    "sponsor": {
      "id": "446566691"
    }
  },
  "status": "refunded",
  "status_detail": "refunded",
  "created_date": "2024-09-10T14:26:42.109320977Z",
  "last_updated_date": "2024-09-10T14:26:42.109320977Z",
  "config": {
    "point": {
      "terminal_id": "NEWLAND_N950__N950NCB801293324",
      "print_on_terminal": "no_ticket",
      "ticket_number": "S0392JED"
    },
    "payment_method": {
      "default_type": "credit_card",
      "default_installments": 3,
      "installments_cost": "seller"
    }
  },
  "transactions": {
    "payments": [
      {
        "id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
        "amount": "24.00",
        "refunded_amount": "24.00",
 "paid_amount": "24.00",
        "status": "refunded",
        "status_detail": "refunded",
        "reference_id": "12345678",
        "payment_method": {
          "type": "credit_card",
          "installments": 6,
          "id": "master"
        }
      }
    ],
    "refunds": [
      {
        "id": "REF01J67CQQH5904WDBVZEM1234D",
        "transaction_id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
        "reference_id": "12345678",
        "amount": "24.00",
        "status": "processed"
      }
    ]
  }
}

AnteriorConfigurar terminalSaiba como configurar seu terminal Point para operar de modo integrado com seu PDV.

PróximoConfigurar notificações de ordersConfigure notificações de orders para receber alertas das suas transações com o Mercado Pago Point