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"
  },
  "additional_info": {
    "sub_merchant": {
      "id": "123123",
      "legal_name": "LOJINHA DO ZE",
      "mcc": "5462",
      "document_type": "CNPJ",
      "document_number": "222222222222222",
      "phone": "5551999999999",
      "url": "www.nomedofacilitador.com.br",
      "address_street": "RUA A",
      "address_door_number": 123,
      "zip": "01310100",
      "city": "Sao Paulo",
      "region_code_iso": "BR-SP",
      "region_code": "BR",
      "country": "BRA"
    }
  },
  "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"
      }
    ]
  }
}