AI resources

Efecty

With Mercado Pago's Checkout API, you can also offer payments with Efecty for buyers in Colombia. With this payment method, the buyer makes a deferred cash payment at any Efecty location, within the expiration period defined by the integrator. The purchase is considered complete only after the payment is confirmed.

If you already have the development environment set up and want to offer Efecty as a payment method, follow the steps below.

Remember: before setting up the payment methods, choose the way you will process your transactions. The processing mode, whether manual or automatic, will be defined at the time of order creation, using the processing_mode parameter. For more information, visit the section Integration Model.

Add payment form

To receive payments with Efecty, add a form to the frontend that securely captures the payer's data.

If you already have a payment form, make sure to include Efecty among the available options as shown below and continue to the Submit payment step.

Payment method	`payment_method_id`
Efecty	`efecty`

html
<form id="form-checkout" action="/process_payment" method="post">
  <div>
    <label for="payerFirstName">First name</label>
    <input id="form-checkout__payerFirstName" name="payerFirstName" type="text">
  </div>
  <div>
    <label for="payerLastName">Last name</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">Document type</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">Document number</label>
    <input id="form-checkout__identificationNumber" name="identificationNumber" type="text">
  </div>
  <div>
    <input type="hidden" name="transactionAmount" id="transactionAmount" value="50000">
    <button type="submit">Pay</button>
  </div>
</form>

Submit payment

Submit the payment by creating an order that contains the associated payment transaction.

To do this, send a request with your test Access TokenPrivate key for the application created in Mercado Pago, used in the backend. Access it at Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the `APP_USR` prefix. and the parameters listed below to the /v1/ordersPOST endpoint and run the request.

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

Order creation is subject to per-client request limits. If you receive a 429 Too Many Requests error, wait the time indicated in the Retry-After response header before retrying. See Possible errors for more details.

Parameter	Type	Description	Required
`Authorization`	Header	Refers to your private key, the test Access TokenPrivate key for the application created in Mercado Pago, used in the backend. Access it at Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the `APP_USR` prefix..	Required
`X-Idempotency-Key`	Header	Idempotency key. Ensures each request is processed only once. Use a unique value in the request header, such as a UUID V4 or a random string.	Required
`processing_mode`	Body. String	Order processing mode: `automatic` to create and process automatically, or `manual` to process in a separate step. For more information, see Integration model.	Required
`total_amount`	Body. String	Total transaction amount in Colombian pesos. In the request, send a whole-number numeric string without decimal places.	Required
`transactions.payments.amount`	Body. String	Payment amount in Colombian pesos. It must be equal to `total_amount` and sent as a whole-number numeric string without decimal places.	Required
`payer.email`	Body. String	Buyer's email address.	Required
`payer.identification.type`	Body. String	Buyer's document type. For Colombia: `CC` (Cédula de Ciudadanía), `CE` (Cédula de Extranjería), `NIT`, among others.	Required
`payer.identification.number`	Body. String	Buyer's document number.	Required
`transactions.payments.payment_method.id`	Body. String	Payment method identifier. For this method, the value must be `efecty`.	Required
`transactions.payments.payment_method.type`	Body. String	Payment method type. For this method, the value must be `ticket`.	Required
`transactions.payments.expiration_time`	Body. String	Voucher expiration period in ISO 8601 duration format. Although you can set it between 1 and 30 days after the payment is created, we recommend setting it between `P1D` and `P3D` to avoid conflicts between the expiration and the payment crediting, which can take up to 2 business hours after completion. If the payment is made after the established expiration date, the amount will be refunded to the payer's Mercado Pago account.	Optional

To learn in detail about all the parameters sent and returned in this request, please refer to our API ReferenceAPI. Additionally, if you receive an error when submitting the payment, you can consult our list of errors.

The creation of the payment occurs asynchronously in the order. While it is being processed, the order is returned with a processing status and without information.

Once processing is complete, and since this is an offline payment method, the order transitions to action_required with the detail waiting_payment, indicating that the buyer still needs to complete the payment, as shown in the following response example. We recommend setting up Order topic notifications to receive updates on the status change, including the updated order data. Alternatively, you can choose to send a request to the /v1/orders/{id}GET endpoint to retrieve the updated status.

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

Although COP amounts must be sent without decimal places in the request, the corresponding fields may be returned with two decimal places in the response, as shown in the example above.

If you have created the order in manual mode, remember that payment processing requires an additional step, sending a request to the Process orderPOST endpoint.

Display payment instructions to the buyer

After creating the order, display to the buyer the information needed to complete the payment at an Efecty location. This data is available in the payment_method fields of the response.

Field	Description
`ticket_url`	URL with full payment instructions. Redirect or display this link to the buyer.
`barcode_content`	Voucher identifier used as the barcode at the Efecty payment location.
`reference`	Payment reference code.
`verification_code`	Payment verification code.

The buyer must use the ticket_url, or the barcode_content/reference/verification_code, at an Efecty location to complete the payment before the date_of_expiration deadline.

Once the buyer completes the payment, the order transitions to status: processed. If you have set up your notifications, you will be notified of this via webhook.

Cancel payment

If you wish, you can cancel a payment created, as long as it is pending or in process; that is, with status=action_required.

Additionally, we recommend canceling payments that were not made by the established due date to avoid billing and reconciliation issues.

If 30 days pass after the established due date for a payment and it has not been made, Mercado Pago will consider it expired. In these cases, it is not possible to perform a manual cancellation, and the payment status will change to canceled or expired.

For more information, please consult the Refunds and cancellations section.

PreviousPSELearn how to integrate PSE payments in Checkout API with Orders API.

NextIntroductionLearn which payment methods you can offer using Checkout API in your mobile store.