Efecty
Con Checkout API de Mercado Pago, también puedes ofrecer pagos con Efecty para compradores en Colombia. Con este medio de pago, el comprador realiza un pago diferido en efectivo en cualquier punto de la red Efecty, dentro del plazo de vencimiento definido por el integrador. La compra se considera completada solo tras la confirmación del pago.
Si ya tienes el entorno de desarrollo configurado y quieres ofrecer Efecty como medio de pago, sigue los pasos a continuación.
processing_mode. Para más información, accede a la sección Modelo de integración.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.
| Medio de pago | payment_method_id |
| Efecty | efecty |
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.
processing_mode=manual) puede tener un plazo de validez definido en el campo expiration_time. Si el campo no se envía, el plazo predeterminado será de P1D (un día). Cuando el plazo vence sin que la order haya alcanzado un estado final, se cierra automáticamente, se cancelan los pagos pendientes asociados y el integrador es notificado.curlcurl --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_payer@example.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" } }, "config": { "location": { "state_id": "CO-DC" } }, "transactions": { "payments": [ { "amount": "50000", "expiration_time": "P1D", "payment_method": { "id": "efecty", "type": "ticket" } } ] } }'
429 Too Many Requests, espera el tiempo indicado en el header Retry-After de la respuesta antes de intentar nuevamente. Consulta Posibles errores para más detalles.| Parámetro | Tipo | Descripción | Obligatoriedad |
Authorization | Header | Hace referencia a tu clave privada, el 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`.. | Obligatorio |
X-Idempotency-Key | Header | Clave de idempotencia. Garantiza que cada solicitud sea procesada solo una vez. Usa un valor exclusivo en el header de la solicitud, como un UUID V4 o una string aleatoria. | Obligatorio |
processing_mode | Body. String | Modo de procesamiento de la order: automatic para crear y procesar automáticamente, o manual para procesar en una etapa separada. Para más información, accede a Modelo de integración. | Obligatorio |
expiration_time | Body. String | Cuando una order se crea en modo manual (processing_mode=manual), este parámetro permite definir su tiempo de expiración utilizando el formato de duración ISO 8601. El período comienza en created_date y el límite máximo es de 2920 horas. Si no se envía, el valor predeterminado será de P1D (un día). Este parámetro no debe enviarse al crear una order en modo automático (processing_mode=automatic). | Opcional |
config.location | Body. Object | Información sobre la ubicación del pagador. | Opcional |
config.location.state_id | Body. String | Código del estado, provincia o región administrativa del pagador, formado por el código de dos letras del país, seguido de un guion y el código de la localidad. Consulta los valores aceptados.Amazonas (CO-AMA); Antioquia (CO-ANT); Arauca (CO-ARA); Atlántico (CO-ATL); Bogotá D.C. (CO-DCO); Bolívar (CO-BOL); Boyaca (CO-BOY); Caldas (CO-CAL); Caqueta (CO-CAQ); Casanare (CO-CAS); Cauca (CO-CAU); Cesar (CO-CES); Choco (CO-CHO); Córdoba (CO-COR); Cundinamarca (CO-CUN); Guainía (CO-GUA); Guajira (CO-LAG); Guaviare (CO-GUV); Huila (CO-HUI); Magdalena (CO-MAG); Meta (CO-MET); Nariño (CO-NAR); Norte De Santander (CO-NSA); Putumayo (CO-PUT); Quindio (CO-QUI); Risaralda (CO-RIS); San Andres y Providencia (CO-SAP); Santander (CO-SAN); Sucre (CO-SUC); Tolima (CO-TOL); Valle Del Cauca (CO-VAC); Vaupes (CO-VAU); Vichada (CO-VID). | Opcional |
total_amount | Body. String | Monto total de la transacción en pesos colombianos. En la solicitud, envía una string numérica entera, sin decimales. | Obligatorio |
transactions.payments.amount | Body. String | Monto del pago en pesos colombianos. Debe ser igual a total_amount y enviarse como una string numérica entera, sin decimales. | Obligatorio |
payer.email | Body. String | E-mail del comprador. | Obligatorio |
payer.identification.type | Body. String | Tipo de documento del comprador. Para Colombia: CC (Cédula de Ciudadanía), CE (Cédula de Extranjería), NIT, entre otros. | Obligatorio |
payer.identification.number | Body. String | Número de documento del comprador. | Obligatorio |
transactions.payments.payment_method.id | Body. String | Identificador del medio de pago. En este caso, el valor debe ser efecty. | Obligatorio |
transactions.payments.payment_method.type | Body. String | Tipo del medio de pago. En este caso, el valor debe ser ticket. | Obligatorio |
transactions.payments.expiration_time | Body. String | Plazo de vencimiento del comprobante en formato de duración ISO 8601. Si bien puedes configurarlo entre 1 y 30 días luego de la creación del pago, recomendamos definir entre P1D y P3D para evitar conflictos entre el vencimiento y la acreditación del pago, que puede demorar hasta 2 horas hábiles desde su realización. En caso de que el pago se efectúe luego de la fecha de vencimiento establecida, el valor será devuelto a la cuenta de Mercado Pago del pagador. | Opcional |
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" } } ] } }
| Parámetro | Tipo | Descripción |
transactions.payments.status | String | Devuelve el estado de la transacción. En este caso, devolverá action_required para indicar la necesidad de una acción para completar el procesamiento, es decir, hasta que se realice el pago. |
transactions.payments.status_detail | String | Detalle del estado de la transacción. En este caso, el valor obtenido es en espera (waiting_payment) de que el comprador finalice el pago. |
transactions.payments.payment_method.ticket_url | String | URL con las instrucciones de pago a la que deberás redirigir al comprador. |
transactions.payments.payment_method.barcode_content | String | Código de barras del comprobante de pago. |
transactions.payments.payment_method.reference | String | Código de referencia del pago. |
transactions.payments.payment_method.verification_code | String | Código de verificación del pago. |
expiration_time | String | Período de expiración (en formato ISO 8601) devuelto para una order creada en modo manual (processing_mode=manual), contado desde created_date. Cuando se omite en la solicitud, el valor predeterminado devuelto será P1D (un día). Este parámetro no se devolverá para una order creada en modo automático (processing_mode=automatic). |
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.
| Campo | Descripción |
ticket_url | URL con las instrucciones completas de pago. Redirige o muestra este enlace al comprador. |
barcode_content | Identificador del comprobante utilizado como código de barras en el punto de pago Efecty. |
reference | Código de referencia del pago. |
verification_code | Código de verificación del pago. |
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.