Procesar pagos

La creación de la order es la operación que efectiva el cobro en la billetera del comprador. Solo es posible asociar una transacción de pago por order en integraciones con Wallet Connect.

Para ello, envía una solicitud al endpoint /v1/ordersPOST, incluyendo tu Access Token de pruebaClave privada utilizada en el backend para autenticar las solicitudes. En la integración con Wallet Connect, en un primer momento tu Access Token será entregado por el equipo responsable de crear tu aplicación en Mercado Pago, pero después de tener acceso a esa aplicación podrás visualizarlo en Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`. y el payer_token obtenido en la vinculación.

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"
        }
      }
    ]
  }
}'

Consulta en la tabla a continuación las descripciones de los parámetros que son obligatorios en la solicitud y aquellos que, aunque son opcionales, tienen alguna particularidad importante que debe destacarse.

Si la solicitud es exitosa, la respuesta devolverá el estado 201 con la order creada. Para orders con capture_mode=automatic, el pago devolverá status=processed y status_detail=accredited, indicando que el monto ya fue debitado de la billetera del 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
        }
      }
    ]
  }
}

Entre los parámetros devueltos, tenemos los indicados en la tabla a continuación.

Si creaste la order en modo manual, es decir, con el campo capture_mode=manual, recuerda que el procesamiento del pago requiere una etapa adicional. En ese escenario, el monto es solamente autorizado en la creación de la order y la respuesta devolverá status=action_required con status_detail=waiting_capture, indicando que la transacción aguarda la captura. Para efectuar el cobro y debitar el monto de la billetera del comprador, es necesario realizar una solicitud al endpoint /v1/orders/{order_id}/capturePOST. Después de la captura, la order pasará a devolver status=processed con status_detail=accredited.

La consulta permite obtener los datos actualizados de una order, incluyendo el status del pago y los intentos de procesamiento realizados. Recomendamos utilizarla como alternativa a las notificaciones cuando sea necesario confirmar el resultado de una transacción.

Para realizar la consulta, envía una solicitud al endpoint /v1/orders/{order_id}GET, incluyendo tu Access Token de pruebaClave privada utilizada en el backend para autenticar las solicitudes. En la integración con Wallet Connect, en un primer momento tu Access Token será entregado por el equipo responsable de crear tu aplicación en Mercado Pago, pero después de tener acceso a esa aplicación podrás visualizarlo en Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`. y el ID de la order (order_id) obtenido en la respuesta a su creación.

curl
curl -X GET \
    'https://api.mercadopago.com/v1/orders/{{ORDER_ID}}' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'

Si la solicitud es exitosa, la respuesta devolverá el estado 200 con los datos actualizados de la 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"
      }
    ]
  }
}

La cancelación libera la autorización de un pago que aún no fue capturado, sin que ningún monto sea transferido de la billetera del comprador. Se aplica solamente a orders en el estado action_required, es decir, creadas con capture_mode=manual y aún pendientes de captura.

Para cancelar una order, envía una solicitud al endpoint /v1/orders/{order_id}/cancelPOST sin enviar el body en la solicitud. Asegúrate de incluir tu Access Token de pruebaClave privada utilizada en el backend para autenticar las solicitudes. En la integración con Wallet Connect, en un primer momento tu Access Token será entregado por el equipo responsable de crear tu aplicación en Mercado Pago, pero después de tener acceso a esa aplicación podrás visualizarlo en Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`. y el ID de la order (order_id) que deseas 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}}'

Si la solicitud es exitosa, la respuesta traerá la order con status=canceled y status_detail=canceled_transaction, indicando que la autorización fue liberada.

Los reembolsos son transacciones realizadas cuando determinado cobro es revertido y los montos pagados son devueltos al comprador. Con Wallet Connect, es posible realizar la devolución total o parcial de una order ya procesada.

Elige la opción que mejor se adecue a tus necesidades y sigue las instrucciones correspondientes.

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"
      }
    ]
  }
}