Recursos para IA

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 vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais, nunca deve ser exposta no frontend e 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.

Os valores autorizados não poderão ser utilizados pelo seu cliente até que não sejam capturados. Por isso, recomendamos realizar a captura o quanto antes.

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.

O prazo para capturar o pagamento autorizado é de 5 dias a partir da sua criação. Se não capturá-lo nesse período, será cancelado. Além disso, é necessário guardar o ID do pagamento para poder finalizar o processo.

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 vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais, nunca deve ser exposta no frontend e 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.