By integrating card payments with Checkout Transparente , it is possible to process the transactions by reserving funds and subsequently capturing them. See below how to manage these transactions.

The reserve of amounts happens when a purchase is made and its amount is reserved from the total limit of the card, ensuring that the value is kept until the completion of processing, which is to say, its capture.

To carry out an authorization of a reserved amount, send a POST request with your test Access TokenTesting private key of the application created in Mercado Pago, that is used in the backend. You can access it through Your integrations > Application details > Testing > Testing credentials. and all the necessary attributes to the endpoint /v1/ordersAPI.

curl
Copiar
curl -X POST \
    -H 'accept: application/json' \
    -H 'content-type: application/json' \
    -H 'Authorization: Bearer {{ENV_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": "200.00",
  "payer": {
    "email": "{{PAYER_EMAIL}}",
    "identification": {
      "type": "{{PAYER_DOCUMENT_TYPE}}",
      "number": "{{PAYER_DOCUMENT_NUMBER}}"
    }
  },
  "transactions": {
    "payments": [
      {
        "amount": "200.00",
        "payment_method": {
          "id": "master",
          "type": "credit_card",
          "token": "{{CREDIT_CARD_TOKEN}}",
          "installments": 1
        }
      }
    ]
  }
}

If the request is successful, the response will indicate that the payment is authorized and pending capture, as shown below.

json
Copiar
{
  "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"
      }
    ]
  }
}

If the reserve is rejected, a response will be returned in the following format:

json
Copiar
{
  "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": "200.00",
          "status": "failed",
          "status_detail": "required_call_for_authorize"
          ...
        }
      ]
    }
  }
}

It is also possible to receive a pending status. In these cases, you should pay attention to the notifications sent by Mercado Pago to know what the final status of the payment is.

The completion of a payment takes place after the authorized payment has been captured, which means that the amount reserved for the purchase can be debited from the card.

Currently, it is only possible to capture the total amount of the reserved payment.

The cancellation of a reserve occurs when, for some reason, the payment for a purchase is not approved and the reserved amount needs to return to the customer's card limit, or when a buyer withdraws from the purchase.

To cancel a reserve, you must send a request to the endpoint /v1/orders/{order_id}/cancelAPI. Be sure to replace {order_id} with the ID of the order you wish to cancel.