Efecty

Para recibir pagos con Efecty, es necesario agregar al frontend un formulario que capture los datos del pagador de forma segura.

Si ya tienes un formulario de pago, asegúrate de incluir Efecty entre las opciones disponibles como se indica a continuación y continúa con el paso Enviar pago.

html
<form id="form-checkout" action="/process_payment" method="post">
  <div>
    <label for="payerFirstName">Nombre</label>
    <input id="form-checkout__payerFirstName" name="payerFirstName" type="text">
  </div>
  <div>
    <label for="payerLastName">Apellido</label>
    <input id="form-checkout__payerLastName" name="payerLastName" type="text">
  </div>
  <div>
    <label for="email">E-mail</label>
    <input id="form-checkout__email" name="email" type="text">
  </div>
  <div>
    <label for="identificationType">Tipo de documento</label>
    <select id="form-checkout__identificationType" name="identificationType">
      <option value="CC">CC</option>
      <option value="CE">CE</option>
      <option value="NIT">NIT</option>
    </select>
  </div>
  <div>
    <label for="identificationNumber">Número del documento</label>
    <input id="form-checkout__identificationNumber" name="identificationNumber" type="text">
  </div>
  <div>
    <input type="hidden" name="transactionAmount" id="transactionAmount" value="50000">
    <button type="submit">Pagar</button>
  </div>
</form>

El envío del pago se realiza creando una order que contenga la transacción de pago asociada.

Para eso, envía una solicitud con tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago, utilizada en el backend. Accede a ella en Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`. y los parámetros indicados a continuación al endpoint /v1/ordersPOST y ejecuta la solicitud.

curl
curl --location --request POST 'https://api.mercadopago.com/v1/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
--data-raw '{
  "type": "online",
  "external_reference": "ext_ref_1234",
  "processing_mode": "automatic",
  "total_amount": "50000",
  "payer": {
    "email": "test_user_co@testuser.com",
    "entity_type": "individual",
    "first_name": "John",
    "last_name": "Doe",
    "identification": {
      "type": "CC",
      "number": "12345678"
    },
    "phone": {
      "area_code": "57",
      "number": "3001234567"
    },
    "address": {
      "street_name": "Calle 10",
      "street_number": "100",
      "zip_code": "110111",
      "neighborhood": "Centro",
      "city": "Bogota"
    }
  },
  "transactions": {
    "payments": [
      {
        "amount": "50000",
        "expiration_time": "P1D",
        "payment_method": {
          "id": "efecty",
          "type": "ticket"
        }
      }
    ]
  }
}'

La creación del pago ocurre de forma asíncrona en la order. Mientras se procesa, la order se devuelve con el estado processing y sin información.

Una vez finalizado el procesamiento, y al tratarse de un medio de pago offline, la order pasa al estado action_required con el detalle waiting_payment, indicando que el comprador aún debe completar el pago, tal como se muestra en el siguiente ejemplo de respuesta. Te recomendamos configurar las notificaciones del tópico Order para recibir actualizaciones sobre el cambio de estado, incluyendo los datos actualizados de la order. Alternativamente, puedes optar por enviar una solicitud al endpoint /v1/orders/{id}GET para consultar el estado actualizado.

json
{
  "id": "ORDBTA01M0WS8YTXXA36FK58BZKTDQ8S",
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_1234",
  "total_amount": "50000",
  "total_paid_amount": "0",
  "country_code": "COL",
  "user_id": "1234567890",
  "status": "action_required",
  "status_detail": "waiting_payment",
  "capture_mode": "automatic_async",
  "currency": "COP",
  "created_date": "2026-08-25T15:40:27.396Z",
  "last_updated_date": "2026-08-25T15:40:28.407Z",
  "transactions": {
    "payments": [
      {
        "id": "PAY01M0WS8YW3Z669ASQX7D0YPFE8",
        "amount": "50000",
        "expiration_time": "P1D",
        "date_of_expiration": "2026-08-27T04:59:59.000+00:00",
        "reference_id": "123456789012",
        "status": "action_required",
        "status_detail": "waiting_payment",
        "payment_method": {
          "id": "efecty",
          "type": "ticket",
          "ticket_url": "https://www.mercadopago.com.co/payments/123456789012/ticket?caller_id=1234567890&payment_method_id=efecty&payment_id=123456789012&payment_method_reference_id=1234567890&hash=00000000-0000-0000-0000-000000000000",
          "barcode_content": "123456789012",
          "reference": "1234567890",
          "verification_code": "1234567890"
        }
      }
    ]
  }
}

Aunque los montos en COP deben enviarse sin decimales en la solicitud, los campos correspondientes pueden devolverse con dos decimales en la respuesta, como en el ejemplo anterior.

Tras crear la order, muestra al comprador la información necesaria para completar el pago en un punto Efecty. Estos datos están disponibles en los campos payment_method de la respuesta.

El comprador debe utilizar el ticket_url, o el barcode_content/reference/verification_code, en un punto Efecty para completar el pago dentro del plazo de vencimiento definido en date_of_expiration.

Una vez que el comprador realice el pago, la order pasa a status: processed. Si configuraste tus notificaciones, esto te será notificado vía webhook.

Si lo deseas, puedes cancelar un pago creado, siempre y cuando se encuentre pendiente o en proceso; es decir, con status=action_required.

Adicionalmente, recomendamos cancelar los pagos que no fueron realizados dentro de la fecha de vencimiento establecida, para evitar problemas de facturación y conciliación.

Para obtener más información, consulta la sección Reembolsos y cancelaciones.