Integrar o processamento de pagamentos

O processamento de pagamentos com o Mercado Pago Point, integrado ao ponto de venda, é realizado por meio da criação de orders que incluem uma transação de pagamento associada. Ao criar uma order, ela é automaticamente enviada ao terminal Point indicado, permitindo que o comprador realize o pagamento de forma presencial.

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, é 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 que este terminal deverá ter sido configurado em modo PDV.

Para isso, envie um GET para o endpoint Obter lista de terminalsAPI, utilizando seu Access Token de produçãoChave privada da aplicação criada no Mercado Pago, utilizada no backend em ambientes de desenvolvimento e no momento de receber pagamentos reais. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Produção > Credenciais de produção., em caso de uma integração própria, ou o Access Token obtido via OAuthChave privada gerada a partir o protocolo de segurança OAuth, o que permite gerenciar integrações em nome de terceiros. Para mais informações, acesse a documentação.OAuth se estiver integrando em nome de terceiros.

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=1&store_id=1235456678&pos_id=1235456678' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer TEST-232********97488-12********26f67454********f4c8b49c********9526408'

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": "PAX_A910__SMARTPOS1234345545",
        "pos_id": 47792476,
        "store_id": "47792478",
        "external_pos_id": "SUC0101POS",
        "operating_mode": "PDV"
      }
    ]
  },
  "paging": {
    "total": 1,
    "offset": 0,
    "limit": 50
  }
}

Em seguida, você deve criar a order. Para isso, envie um POST para o endpoint /v1/ordersAPI, incluindo seu Access Token de produçãoChave privada da aplicação criada no Mercado Pago, utilizada no backend em ambientes de desenvolvimento e no momento de receber pagamentos reais. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Produção > Credenciais de produção., caso esteja realizando uma integração própria, ou o Access Token obtido via OAuthChave privada gerada a partir o protocolo de segurança OAuth, o que permite gerenciar integrações em nome de terceiros. Para mais informações, acesse a documentação.OAuth, caso esteja realizando uma integração para terceiros, e o id do terminal ao qual deseja atribuir a order, obtido no passo anterior.

curl
curl -X POST \
    'https://api.mercadopago.com/v1/orders' \
    -H 'Content-Type: application/json' \
    -H 'X-Idempotency-Key: 0d5020ed-1af6-469c-ae06-c3bec19954bb' \
    -H 'Authorization: Bearer TEST-232********97488-12********26f67454********f4c8b49c********9526408' \
    -d '{
        "type": "point",
        "external_reference": "ext_ref_1234",
        "transactions": {
            "payments": [
                {
                    "amount": "24"
                }
            ]
        },
        "config": {
            "point": {
                "terminal_id": "PAX_A910__SMARTPOS1423",
                "print_on_terminal": "no_ticket"
            },
            "payment_method": {
                "default_type": "credit_card"
            }
        },
        "description": "Point Smart 2",
        "integration_data": {
            "platform_id": "dev_1234567890",
            "integrator_id": "dev_1234567890",
            "sponsor": {
                "id": "446566691"
            }
        },
        "taxes": [
            {
                "payer_condition": "payment_taxable_iva"
            }
        ]
    }'

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 produçãoChave privada da aplicação criada no Mercado Pago, utilizada no backend em ambientes de desenvolvimento e no momento de receber pagamentos reais. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Produção > Credenciais de produção., caso esteja realizando uma integração própria, ou ao Access Token obtido via OAuthChave privada gerada a partir o protocolo de segurança OAuth, o que permite gerenciar integrações em nome de terceiros. Para mais informações, acesse a documentação.OAuth.	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
`transaction.payments.amount`	Body.String	Valor total da order de pagamento. No Chile: inteiro sem decimais. Nos outros países: 2 decimais obrigatórios, mesmo se for inteiro (ex: "10.00").	Obrigatório
`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 Obter terminalsAPI, como no seguinte exemplo: "PAX_A910SMARTPOS123456789".	Obrigatório

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

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",
  "processing_mode": "automatic",
  "country_code": "CHL",
  "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": "PAX_A910__SMARTPOS1423",
      "print_on_terminal": "no_ticket"
    },
    "payment_method": {
      "default_type": "credit_card",
      "default_installments": "6",
      "installments_cost": "seller"
    }
  },
  "transactions": {
    "payments": [
      {
        "id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
        "amount": "24",
        "status": "created"
      }
    ]
  },
  "taxes": [
    {
      "payer_condition": "payment_taxable_iva"
    }
  ]
}

Como a order é a base do processamento do pagamento, é importante armazenar os dados retornados na sua criação, principalmente seu id e o id do pagamento (transactions.payments.id). Esses identificadores serão necessários para realizar outras operações e consultar notificações de forma adequada. Além disso, você pode consultar nossa documentação na seção Recursos para entender melhor sobre os possíveis status de uma order e de uma transação.

A order criada será automaticamente recebida pelo terminal ao qual foi atribuída, permitindo que o comprador realize o pagamento no ponto de venda físico e, em seguida, o processamento da transação. Lembre-se de que o pagamento deve ocorrer em até 15 minutos após a criação da order e, após esse prazo, ela expirará.

Cancelar uma order

O cancelamento de uma order pode ser feito de duas formas, a depender do status em que ela se encontra.

Se o status da order for created, o cancelamento deve ser feito via API.
Se o status for at_terminal, isso indica que a order já foi recebida pelo terminal e deverá ser cancelada a partir dele.

Se uma order não for processada em até 15 minutos após sua criação, seu status passará a ser expired e não será mais possível cancelá-la. < br> Além disso, no caso de cancelamentos a partir do terminal, é importante ter previamente configurado suas notificações Webhooks para receber o aviso do cancelamento em seu sistema, o que permitirá manter sua conciliação.

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

Para cancelar uma order com status created, envie um POST para o endpoint Cancelar order por IDAPI, incluindo seu Access Token de produçãoChave privada da aplicação criada no Mercado Pago, utilizada no backend em ambientes de desenvolvimento e no momento de receber pagamentos reais. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Produção > Credenciais de produção., em caso de integração própria, ou o Access Token obtido via OAuthChave privada gerada a partir o protocolo de segurança OAuth, o que permite gerenciar integrações em nome de terceiros. Para mais informações, acesse a documentação.OAuth, caso esteja integrando para terceiros. Também é necessário enviar o id da order que deseja cancelar, obtido na resposta à sua criação.

curl
curl -X POST \
    'https://api.mercadopago.com/v1/orders/ORDER_ID/cancel' \
    -H 'Content-Type: application/json' \
    -H 'X-Idempotency-Key: 0d5020ed-1af6-469c-ae06-c3bec19954bb' \
    -H 'Authorization: Bearer ACCESS_TOKEN'

Se a solicitação for bem-sucedida, a resposta mostrará um status=canceled.

json
{
  "id": "ORD0000ABCD222233334444555566",
  "user_id": "5238400195",
  "type": "point",
  "external_reference": "ext_ref_1234",
  "description": "Point Smart 2",
  "country_code": "CHL",
  "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": "PAX_A910__SMARTPOS1423",
      "print_on_terminal": "no_ticket"
    },
    "payment_method": {
      "default_type": "credit_card",
      "default_installments": "6",
      "installments_cost": "seller"
    }
  },
  "transactions": {
    "payments": [
      {
        "id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
        "amount": "24.00",
        "status": "canceled",
        "status_detail": "canceled_by_api"
      }
    ]
  },
  "taxes": [
    {
      "payer_condition": "payment_taxable_iva"
    }
  ]
}

Reembolsar uma order

Caso queira, é possível reembolsar uma order criada por meio da nossa API. Neste caso, o reembolso será sempre uma devolução total do valor da order.

Um pedido pago com cartão poderá ser reembolsado via API até 90 dias após a realização do pagamento. Para os pagos realizados via Edenred, os reembolsos via API só poderão ser feitos até 23:59:59 do mesmo dia em que o pagamento foi criado e para os pagos efetuados com Pluxee, os reembolsos via API poderão ser realizados até 5 dias úteis a partir da criação do pagamento. Após esse período, não será mais possível realizar a devolução.

Para realizar o reembolso total de uma order, envie um POST para o endpoint Reembolsar uma orderAPI. Certifique-se de incluir seu Access Token de produçãoChave privada da aplicação criada no Mercado Pago, utilizada no backend em ambientes de desenvolvimento e no momento de receber pagamentos reais. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Produção > Credenciais de produção., caso esteja realizando uma integração própria, ou o Access Token obtido via OAuthChave privada gerada a partir o protocolo de segurança OAuth, o que permite gerenciar integrações em nome de terceiros. Para mais informações, acesse a documentação.OAuth, se estiver integrando em nome de terceiros. Também é necessário informar o id da order 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: 0d5020ed-1af6-469c-ae06-c3bec19954bb' \
    -H 'Authorization: Bearer ACCESS_TOKEN'

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

json
{
  "id": "ORD0000ABCD222233334444555566",
  "status": "refunded",
  "status_detail": "refunded",
  "transactions": {
    "refunds": [
      {
        "id": "REF01J67CQQH5904WDBVZEM1234D",
        "transaction_id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
        "reference_id": "12345678",
        "amount": "38.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 um GET para o endpoint Obter order por IDAPI, incluindo o Access Token de produçãoChave privada da aplicação criada no Mercado Pago, utilizada no backend em ambientes de desenvolvimento e no momento de receber pagamentos reais. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Produção > Credenciais de produção., caso esteja realizando uma integração própria, ou o Access Token obtido via OAuthChave privada gerada a partir o protocolo de segurança OAuth, o que permite gerenciar integrações em nome de terceiros. Para mais informações, acesse a documentação.OAuth, caso esteja integrando para terceiros, além do id da order 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 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",
  "country_code": "CHL",
  "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": "PAX_A910__SMARTPOS1423",
      "print_on_terminal": "no_ticket"
    },
    "payment_method": {
      "default_type": "credit_card",
      "default_installments": "6",
      "installments_cost": "seller"
    }
  },
  "transactions": {
    "payments": [
      {
        "id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
        "amount": "24.00",
        "refunded_amount": "38.00",
        "tip_amount": "14.00",
        "paid_amount": "38.00",
        "status": "refunded",
        "status_detail": "created",
        "reference_id": "12345678",
        "payment_method": {
          "type": "credit_card",
          "installments": 1,
          "id": "master"
        }
      }
    ],
    "refunds": [
      {
        "id": "REF01J67CQQH5904WDBVZEM1234D",
        "transaction_id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
        "reference_id": "12345678",
        "amount": "38.00",
        "status": "processed"
      }
    ]
  },
  "taxes": [
    {
      "payer_condition": "payment_taxable_iva"
    }
  ]
}

Configurar terminal

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

Configurar notificações

Notificações são mensagens enviadas pelo servidor do Mercado Pago a partir de eventos realizados em sua aplicação.

Documentação

Começando agora?

Recursos

Suporte

Comunidade

Integrar o processamento de pagamentos

Navegação

Recursos e Comunidade

Mercado Pago

País e idioma