Processar pagamentos

A criação da order é a operação que efetiva a cobrança na carteira do comprador. Só é possível associar uma transação de pagamento por order em integrações com Wallet Connect.

Para isso, envie uma solicitação ao endpoint /v1/ordersPOST, incluindo seu Access Token de testeChave privada utilizada no backend para autenticar as requisições. Na integração com Wallet Connect, em um primeiro momento o seu Access Token será repassado pela equipe responsável por criar a sua aplicação no Mercado Pago, mas após ter acesso a essa aplicação você poderá visualizá-lo em Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`. e o payer_token obtido na vinculaçã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": "online",
  "external_reference": "ext_ref_1234",
  "total_amount": "24.90",
  "description": "Smartphone",
  "capture_mode": "automatic",
  "integration_data": {
    "platform_id": "123abc"
  },
  "transactions": {
    "payments": [
      {
        "amount": "24.90",
        "payment_method": {
          "type": "wallet",
          "id": "wallet",
          "token": "PAYER_TOKEN",
          "statement_descriptor": "My Store"
        }
      }
    ]
  }
}'

Consulte na tabela abaixo as descrições dos parâmetros que são obrigatórios na requisição e daqueles que, embora sejam opcionais, possuem alguma particularidade importante de ser destacada.

Se a solicitação for bem-sucedida, a resposta retornará o status 201 com a order criada. Para orders com capture_mode=automatic, o pagamento retornará com status=processed e status_detail=accredited, indicando que o valor já foi debitado da carteira do comprador.

json
{
  "id": "ORDBTA01KJZ06DEJX3DMY26FAB44BXNN",
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_1234",
  "description": "Smartphone",
  "total_amount": "24.90",
  "total_paid_amount": "24.90",
  "status": "processed",
  "status_detail": "accredited",
  "capture_mode": "automatic",
  "transactions": {
    "payments": [
      {
        "id": "PAY01KJZ06DEJX3DMXXXXXXXXXXXX",
        "amount": "24.90",
        "paid_amount": "24.90",
        "status": "processed",
        "status_detail": "accredited",
        "payment_method": {
          "id": "wallet",
          "type": "wallet",
          "statement_descriptor": "My Store",
          "installments": 1
        }
      }
    ]
  }
}

Dentre os parâmetros retornados, temos os indicados na tabela abaixo.

Caso tenha criado a order em modo manual, ou seja, com o campo capture_mode=manual, lembre-se de que o processamento do pagamento requer uma etapa adicional. Nesse cenário, o valor é apenas autorizado na criação da order e a resposta retornará status=action_required com status_detail=waiting_capture, indicando que a transação aguarda a captura. Para efetivar a cobrança e debitar o valor da carteira do comprador, é necessário realizar uma solicitação ao endpoint /v1/orders/{order_id}/capturePOST. Após a captura, a order passará a retornar status=processed com status_detail=accredited.

A consulta permite obter os dados atualizados de uma order, incluindo o status do pagamento e as tentativas de processamento realizadas. Recomendamos utilizá-la como alternativa às notificações quando for necessário confirmar o resultado de uma transação.

Para realizar a consulta, envie uma solicitação ao endpoint /v1/orders/{order_id}GET, incluindo seu Access Token de testeChave privada utilizada no backend para autenticar as requisições. Na integração com Wallet Connect, em um primeiro momento o seu Access Token será repassado pela equipe responsável por criar a sua aplicação no Mercado Pago, mas após ter acesso a essa aplicação você poderá visualizá-lo em Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`. e o ID da order (order_id) 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 {{YOUR_ACCESS_TOKEN}}'

Se a solicitação for bem-sucedida, a resposta retornará o status 200 com os dados atualizados da order.

json
{
  "id": "ORDBTA01KJZ06DEJX3DMY26FAB44BXNN",
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_1234",
  "description": "Smartphone",
  "total_amount": "24.90",
  "total_paid_amount": "24.90",
  "status": "processed",
  "status_detail": "accredited",
  "transactions": {
    "payments": [
      {
        "id": "PAY01KJZ06DEJX3DMXXXXXXXXXXXX",
        "amount": "24.90",
        "paid_amount": "24.90",
        "status": "processed",
        "status_detail": "accredited"
      }
    ]
  }
}

O cancelamento libera a autorização de um pagamento que ainda não foi capturado, sem que nenhum valor seja transferido da carteira do comprador. Aplica-se apenas a orders no status action_required, ou seja, criadas com capture_mode=manual e ainda pendentes de captura.

Para cancelar uma order, envie uma solicitação ao endpoint /v1/orders/{order_id}/cancelPOST sem enviar o body na requisição. Certifique-se de incluir seu Access Token de testeChave privada utilizada no backend para autenticar as requisições. Na integração com Wallet Connect, em um primeiro momento o seu Access Token será repassado pela equipe responsável por criar a sua aplicação no Mercado Pago, mas após ter acesso a essa aplicação você poderá visualizá-lo em Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`. e o ID da order (order_id) que deseja cancelar.

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 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'

Se a solicitação for bem-sucedida, a resposta trará a order com status=canceled e status_detail=canceled_transaction, indicando que a autorização foi liberada.

Os reembolsos são transações realizadas quando determinada cobrança é revertida e os valores pagos são devolvidos ao comprador. Com o Wallet Connect, é possível realizar a devolução total ou parcial de uma order já processada.

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

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}}'

json
{
  "id": "ORDBTA01KJZ0AYZPD3SXDYCQ109Q69EA",
  "status": "refunded",
  "status_detail": "refunded",
  "transactions": {
    "refunds": [
      {
        "id": "REF01KJZ0BPKX0BQ0KG1VPBMJDX9G",
        "transaction_id": "PAY01KJZ0AYZPD3SXDYCQ10RYPF8E",
        "amount": "24.90",
        "status": "processed"
      }
    ]
  }
}