Reserve, capture, and cancel amounts
By integrating Order transactions, it is possible to process them by reserving funds and subsequently capturing them. See below how to manage the transactions made.
Reserve amounts
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.
To carry out an authorization of a reserved amount, send a POST request with all the necessary attributes as described in our API Reference, including capture_mode set to manual, to the endpoint /v1/orders.
curl
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
}
}
]
}
}'The response will indicate that the payment is authorized and pending capture.
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"
}
]
}
}If the capture is declined, a response will be returned in the following format:
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": "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 to know what the final status of the payment is.
Capture an authorized payment
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.
For now, we only have the possibility of subsequent capture, where the full amount of the reserved payment is captured.
To capture the total amount of a reservation, you need to send a request to the endpoint /v1/orders/{order_id}/capture, replacing {order_id} with the ID of the order you want to capture in full.
Cancel reservation
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 reserde, you must send a request to the endpoint /v1/orders/{order_id}/cancel. Be sure to replace {order_id} with the ID of the order you wish to cancel.