Reservar, capturar e cancelar valores

Ao integrar pagamentos com cartão com o Checkout Transparente é possível processar transações reservando fundos e posteriormente capturá-los. Veja abaixo como gerenciar as transações realizadas.

Reserva de valores

Uma reserva de valores acontece quando uma compra é realizada e seu montante é reservado do limite total do cartão, garantindo que o valor fique guardado até a conclusão do processamento, ou seja, sua captura.

Para realizar uma autorização de reserva de valores, envie uma requisição com seu Access Token de testeChave privada de testes da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`. e todos os atributos necessários ao endpoint /v1/ordersPOST.

curl
curl -X POST \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
    -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
    'https://api.mercadopago.com/v1/orders \
    -d '
{
  "capture_mode": "manual",
  "type": "online",
  "external_reference": "ext_ref_1234",
  "processing_mode": "automatic",
  "marketplace": "NONE",
  "total_amount": "50.00",
  "payer": {
    "email": "{{PAYER_EMAIL}}",
    "identification": {
      "type": "{{PAYER_DOCUMENT_TYPE}}",
      "number": "{{PAYER_DOCUMENT_NUMBER}}"
    }
  },
  "transactions": {
    "payments": [
      {
        "amount": "50.00",
        "payment_method": {
          "id": "master",
          "type": "credit_card",
          "token": "{{CREDIT_CARD_TOKEN}}",
          "installments": 1
        }
      }
    ]
  }
}

Caso a requisição tenha ocorrido com sucesso, a resposta indicará que o pagamento encontra-se autorizado e pendente de captura, conforme o exemplo abaixo.

json
{
  "id": ORDER_ID,
  ...
  "status": "action_required",
  "status_detail": "waiting_capture",
  ...
    "capture_mode": "manual",
  ...
 "transactions": {
    "payments": [
      {
        "id": TRANSACTION_ID,
        "status": "action_required",
        "status_detail": "waiting_capture"
      }
    ]
  }
}

Caso a reserva seja recusada, será retornada uma resposta no seguinte formato:

json
{
  "errors": [
    {
      "code": "failed",
      "message": "The following transactions failed",
      "details": [
        "pay_01JE797F7RX989RWQJHP4VHF94: required_call_for_authorize"
      ]
    }
  ],
  "data": {
    "id": "01JE797F7RX989RWQJHMY34WJ4",
    "capture_mode": "manual",
    "status": "failed",
    "status_detail": "failed",
    ...
    "transactions": {
      "payments": [
        {
          "id": "pay_01JE797F7RX989RWQJHP4VHF94",
          "amount": "50.00",
          "status": "failed",
          "status_detail": "required_call_for_authorize"
          ...
        }
      ]
    }
  }
}

Além disso, também é possível que o status retorne como pending. Caso isso aconteça, você deverá ficar atento às notificações enviadas pelo Mercado Pago para saber qual o status final do pagamento.

Captura de pagamento autorizado

A finalização de um pagamento autorizado acontece após a captura do valor autorizado, o que significa que o valor reservado para a compra pode ser debitado do cartão.

Atualmente, só é possível capturar o valor integral do pagamento reservado.

Para realizar a captura do valor total de uma reserva, é necessário enviar uma requisição ao endpoint /v1/orders/{order_id}/capturePOST com seu Access Token de testeChave privada de testes da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`., substituindo {order_id} pelo ID da order cuja captura total deseja efetuar.

Cancelamento de reserva

O cancelamento de uma reserva ocorre quando, por algum motivo, o pagamento de uma compra não é aprovado e a reserva do valor precisa retornar para o limite do cartão do cliente ou quando um comprador desiste da compra.

Para cancelar uma reserva, você deve enviar uma requisição ao endpoint /v1/orders/{order_id}/cancelPOST. Certifique-se de substituir {order_id} pelo ID da ordem que deseja cancelar.