Efecty

Para receber pagamentos com Efecty, é necessário adicionar ao frontend um formulário que capture os dados do pagador de forma segura.

Se você já tem um formulário de pagamento, certifique-se de incluir Efecty entre as opções disponíveis conforme indicado abaixo e continue para a etapa de Enviar pagamento.

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>

O envio do pagamento é realizado criando uma order que contenha a transação de pagamento associada.

Para isso, envie uma requisição com o seu Access Token de testeChave privada da aplicação criada no Mercado Pago, utilizada no backend. Acesse-a em Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`. e os parâmetros indicados abaixo para o endpoint /v1/ordersPOST e execute a requisição.

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

A criação do pagamento ocorre de forma assíncrona na order. Enquanto está sendo processada, a order é devolvida com o status de processing e sem informações.

Após a conclusão do processamento, e por se tratar de um meio de pagamento offline, a order passa para o status action_required com o detalhe waiting_payment, indicando que o comprador ainda precisa concluir o pagamento, como mostrado no exemplo de resposta a seguir. Recomendamos configurar as notificações do tópico Order para receber atualizações sobre a mudança de status, incluindo os dados atualizados da order. Alternativamente, você pode optar por enviar uma requisição ao endpoint /v1/orders/{id}GET para consultar o status atualizado.

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

Embora os valores monetários em COP devam ser enviados sem casas decimais na requisição, os campos correspondentes podem ser retornados com duas casas decimais na resposta, como no exemplo acima.

Após criar a order, exiba ao comprador as informações necessárias para concluir o pagamento em um ponto Efecty. Esses dados estão disponíveis nos campos payment_method da resposta.

O comprador deve utilizar o ticket_url, ou o barcode_content/reference/verification_code, em um ponto Efecty para concluir o pagamento dentro do prazo de vencimento definido em date_of_expiration.

Depois que o comprador realizar o pagamento, a order passa para status: processed. Se você configurou suas notificações, isso será notificado via webhook.

Caso deseje, você pode cancelar um pagamento criado, desde que esteja pendente ou em processamento. Ou seja, com status=action_required.

Além disso, recomendamos cancelar os pagamentos que não foram realizados dentro da data de vencimento estabelecida, para evitar problemas de cobrança e conciliação.

Para obter mais informações, consulte a seção Reembolsos e cancelamentos.