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.
No modo PDV, o vendedor cria uma order e ela é automaticamente enviada ao terminal Point indicado, permitindo que o comprador realize o pagamento. No caso do modo SELF-SERVICE, o processamento da order ocorre em tempo real entre o totem utilizado pelo comprador e o Mercado Pago, sem a necessidade de intervenção manual. Além disso, em modo SELF_SERVICE o terminal ficará 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 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 ou SELF-SERVICE.
Para isso, envie um GET para o endpoint Obter lista de terminalsAPI, utilizando seu Access Token de testeChave privada da aplicação criada no Mercado Pago, utilizada no backend durante o desenvolvimento da integração. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Testes > Credenciais de teste. Ao subir em produção, substitua-o pelo Access Token de produção se se tratar de uma integração própria, ou pelo Access Token obtido mediante OAuth no caso de integrações de terceiros.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 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": "NEWLAND_N950__N950NCB801293324", "pos_id": "23545678", "store_id": "12354567", "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 testeChave privada da aplicação criada no Mercado Pago, utilizada no backend durante o desenvolvimento da integração. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Testes > Credenciais de teste. Ao subir em produção, substitua-o pelo Access Token de produção se se tratar de uma integração própria, ou pelo Access Token obtido mediante OAuth no caso de integrações de terceiros.Acessar as credenciais de teste, 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", "expiration_time": "PT16M", "transactions": { "payments": [ { "amount": "24.00" } ] }, "config": { "point": { "screen_time": "PT15S", "terminal_id": "NEWLAND_N950__N950NCB801293324", "print_on_terminal": "no_ticket", "ticket_number": "S0392JED" }, "payment_method": { "default_type": "credit_card" } }, "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 da aplicação criada no Mercado Pago, utilizada no backend durante o desenvolvimento da integração. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Testes > Credenciais de teste. Ao subir em produção, substitua-o pelo Access Token de produção se se tratar de uma integração própria, ou pelo Access Token obtido mediante OAuth no caso de integrações de terceiros.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 |
transaction.payments.amount | Body.String | Valor total da order de pagamento. O campo deve obrigatoriamente conter 2 casas decimais, mesmo quando for um número inteiro (por exemplo, "10.00"). | Obrigatório |
config.point.screen_time | Body.String | Permite especificar o tempo que as telas dos terminals ficarão habilitadas para que seja processada a order utilizando o formato de duração ISO 8601 (exemplo: "PT1M15S" representa uma duração de 1 minuto e 15 segundos, sendo que o tempo mínimo que pode ser definido é 5 segundos e o máximo é 5 minutos.). Esse tempo se reinicia a cada mudança de tela ou interação do usuário com o terminal e, se não for configurado, o valor padrão será 15 segundos. Durante o período configurado a order estará habilitada para ser processada e, caso não seja processada dentro deste período, será cancelada. Se desejar continuar com o pagamento, será necessário criar uma nova order. Importante: a tela de leitura do cartão para o pagamento será exibida por, no máximo, 60 segundos (1 minuto) independentemente de o valor configurado para este campo for acima de 60 segundos. | 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 Obter terminalsAPI, como no seguinte exemplo: "NEWLAND_N950__N950NCB801293324. | Obrigatório |
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": "ARG", "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": { "screen_time": "PT15S", "terminal_id": "NEWLAND_N950__N950NCB801293324", "print_on_terminal": "no_ticket", "ticket_number": "S0392JED" }, "payment_method": { "default_type": "credit_card", } }, "transactions": { "payments": [ { "id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "amount": "24.00", "status": "created" } ] }, }
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.Esta order será recebida automaticamente pelo terminal ao qual foi atribuída. Caso a order não seja carregada automaticamente no terminal, pressione o botão Atualizar ou, se o terminal possuir, o botão verde para receber a order. Assim, o pagamento poderá ser realizado pelo comprador no terminal e, em seguida, processado. Lembre-se de que, caso o parâmetro expiration_time não seja preenchido, o pagamento deve ocorrer em até 15 minutos (para modo PDV) ou em até 15 segundos (para modo SELF_SERVICE) após a criação da order. Após esse prazo, a order expirará.
O cancelamento de uma order pode ser feito de duas formas, a depender do status em que ela se encontra.
- Se o
statusda order forcreated, o cancelamento deve ser feito via API. - Se o
statusforat_terminal, isso indica que a order já foi recebida pelo terminal e deverá ser cancelada a partir dele.
expiration_time não seja preenchido, se a order não for processada em até 15 minutos após sua criação, no caso do modo de operação PDV, e em até 15 segundos, no caso do modo de operação SELF_SERVICE, seu status passará a ser expired e não será mais possível cancelá-la.
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 /v1/orders/{order_id}/cancelAPI, incluindo seu Access Token de testeChave privada da aplicação criada no Mercado Pago, utilizada no backend durante o desenvolvimento da integração. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Testes > Credenciais de teste. Ao subir em produção, substitua-o pelo Access Token de produção se se tratar de uma integração própria, ou pelo Access Token obtido mediante OAuth no caso de integrações de terceiros.Acessar as credenciais de teste. 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", "expiration_time": "PT16M", "country_code": "ARG", "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": { "screen_time": "PT15S", "terminal_id": "NEWLAND_N950__N950NCB801293324", "print_on_terminal": "no_ticket", "ticket_number": "S0392JED" }, "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" } ] }, }
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.
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 um POST para o endpoint /v1/orders/{order_id}/refundAPI sem enviar o body na requisição. Certifique-se de incluir seu Access Token de testeChave privada da aplicação criada no Mercado Pago, utilizada no backend durante o desenvolvimento da integração. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Testes > Credenciais de teste. Ao subir em produção, substitua-o pelo Access Token de produção se se tratar de uma integração própria, ou pelo Access Token obtido mediante OAuth no caso de integrações de terceiros.Acessar as credenciais de teste. 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 status=refunded e um novo nó transactions.refunds, que irá conter os detalhes do reembolso, além do id 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" } ] } }
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 /v1/orders/{order_id}API, incluindo o Access Token de testeChave privada da aplicação criada no Mercado Pago, utilizada no backend durante o desenvolvimento da integração. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Testes > Credenciais de teste. Ao subir em produção, substitua-o pelo Access Token de produção se se tratar de uma integração própria, ou pelo Access Token obtido mediante OAuth no caso de integrações de terceiros.Acessar as credenciais de teste, além do id da order obtido na resposta à sua criação.
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", "expiration_time": "PT16M", "country_code": "ARG", "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": { "screen_time": "PT15S", "terminal_id": "NEWLAND_N950__N950NCB801293324", "print_on_terminal": "no_ticket", "ticket_number": "S0392JED" }, "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" } ] }, }