Nequi

Nequi es un wallet digital ampliamente utilizado en Colombia. La integración de la API admite Pay-ins (cobro de fondos mediante código QR o notificación Push) y Payouts (desembolso de fondos directamente a una cuenta Nequi). Todos los flujos se confirman de forma asíncrona mediante webhook.

Métodos de pago disponibles

Existen dos formas principales para que un cliente complete un pago con Nequi, determinadas por el campo payment_method:

Nequi QR (WALLET): La API devuelve una redirect_url. El comercio puede redirigir al cliente a esta URL o representarla como un código QR para que el cliente lo escanee utilizando la aplicación Nequi.
Nequi Push (WALLET_PUSH): El comercio activa una notificación push al número de teléfono del cliente. El cliente acepta el pago directamente en la aplicación Nequi.

Requisitos

Antes de integrar Nequi, debe:

Generar un token de acceso a través del endpoint de Autenticación.
Configurar una callback_url HTTPS pública para recibir actualizaciones de estado asíncronas cuando el cliente complete o rechace el pago.
Asegurarse de que la cuenta de comercio esté configurada para Colombia (CO) y la moneda COP.
Para Payouts: Asegúrese de que su cuenta de comercio tiene saldo suficiente para cubrir el importe del desembolso.

Especificidades de Casos de Uso

Al integrar Nequi a través de Getnet, se aplican requisitos específicos del mercado. Nequi solo está disponible en Colombia y soporta la moneda COP.

Características

La siguiente tabla resume el comportamiento y los requisitos de los flujos de pago con Nequi.

Capacidad	Detalles
Experiencia del cliente	Flujo QR: El cliente escanea un código generado a partir de la URL de redirección. Flujo Push: El cliente recibe una notificación en su teléfono para aprobar.
Confirmación	Asíncrona — Una notificación de webhook informa al comercio cuando el pago es aprobado o rechazado.
Idempotencia y unicidad	Cada petición debe incluir una `idempotency_key` única.

Funcionalidades disponibles

Utilice la siguiente matriz para confirmar los escenarios actualmente soportados para Nequi.

Flujo de pago	Países soportados	Compras	Reembolsos	Reembolsos parciales	Preautorizaciones	Pagos recurrentes	Payouts
Directo (QR / Push)	Colombia	✅	✅	✅	❌	✅	✅

Flujo de pago

Esta sección le guía a través del proceso completo de implementación de pagos con Nequi. El siguiente diagrama ofrece una visión general del proceso de pago con Nequi:

1. Crear la petición de pago

Para iniciar un pago con Nequi, llame al endpoint Create - Authorize.

Debe elegir el flujo estableciendo el payment_method y proporcionar el número de teléfono móvil del cliente (crítico para el flujo Push).

La tabla resume los campos mínimos requeridos para un pago con Nequi.

Atributo	Descripción	Valor obligatorio
`payment_method`	Define el tipo de flujo	`WALLET` (para flujo QR Code) o `WALLET_PUSH` (para flujo Notificación Push)
`brand`	Identificador de marca Nequi	`NEQUI`
`callback_url`	Dónde se envían las actualizaciones de estado	Su endpoint HTTPS
`amount`	Importe de la transacción en céntimos	Entero (ej. `10000` para 100,00 $ COP)
`currency`	Código de moneda ISO	`COP`
`order_id`	Referencia del comercio para conciliación	Cadena única (máx. 32 caracteres)
`customer.phone_number`	Número de móvil del cliente	Cadena (ej., `3001234567`)

Notificación Push de Nequi

Utilice WALLET_PUSH. El cliente recibe una notificación en su teléfono. No se devuelve ninguna URL de redirección en la respuesta.

El siguiente ejemplo de petición muestra cómo inicializar un pago con notificación push de Nequi.

curl --location --request POST '[https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments](https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments)' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data-raw '{
    "idempotency_key": "bcad559e-ae27-480c-86ff-fe6c17c762c3",
    "request_id": "894d2718-3966-4df2-b9c2-1a7ddece28ff",
    "order_id": "35541354322",
    "data": {
        "amount": 400,
        "currency": "COP",
        "customer_id": "47377104-827e-4143-b461-fdf768fb2903",
        "payment": {
            "payment_id": "42853760-f2a5-4dff-b4f2-a60689c19965",
            "payment_method": "WALLET_PUSH",
            "brand": "NEQUI",
            "soft_descriptor": "NEQUI TESTE"
        },
        "additional_data": {
            "callback_url": "https://localhost:8080/notification/fake/1",
            "customer": {
                "email": "[email protected]",
                "document_number": "50506468",
                "document_type": "uyci",
                "name": "Jose da Silva",
                "phone_number": "34700000000",
                "billing_address": {
                    "street": "R a",
                    "number": "1",
                    "district": "B",
                    "city": "City Z",
                    "state": "SP",
                    "country": "CO",
                    "postal_code": "05781000",
                    "complement": "N/A"
                }
            },
            "order": {
                "items": [
                    {
                        "name": "Item2",
                        "quantity": 1,
                        "sku": "sku1",
                        "price": 1022
                    }
                ]
            }
        }
    }
}'

La API responde con un payload similar al siguiente ejemplo.

{
  "idempotency_key": "bcad559e-ae27-480c-86ff-fe6c17c762c3",
  "seller_id": "your-seller-id",
  "payment_id": "42853760-f2a5-4dff-b4f2-a60689c19965",
  "order_id": "35541354322",
  "amount": "400",
  "currency": "COP",
  "status": "PENDING",
  "payment_method": "WALLET_PUSH",
  "received_at": "2025-11-15T10:00:00.000Z",
  "reason_code": "00",
  "reason_message": "Waiting for customer approval in Nequi app."
}

Código QR de Nequi

Utilice WALLET. La API devuelve una redirect_url que permite al comercio generar un código QR.

El siguiente ejemplo de petición muestra cómo inicializar un pago QR de Nequi.

curl --location --request POST '[https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments](https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments)' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data-raw '{
    "idempotency_key": "qr-flow-unique-key-123",
    "request_id": "qr-req-001",
    "order_id": "35541354323",
    "data": {
        "amount": 400,
        "currency": "COP",
        "customer_id": "47377104-827e-4143-b461-fdf768fb2903",
        "payment": {
            "payment_id": "55853760-f2a5-4dff-b4f2-a60689c19966",
            "payment_method": "WALLET",
            "brand": "NEQUI",
            "soft_descriptor": "NEQUI QR TEST"
        },
        "additional_data": {
            "callback_url": "https://localhost:8080/notification/fake/1",
            "customer": {
                "email": "[email protected]",
                "document_number": "50506468",
                "document_type": "uyci",
                "name": "Jose da Silva",
                "phone_number": "34700000000",
                "billing_address": {
                    "street": "R a",
                    "number": "1",
                    "district": "B",
                    "city": "City Z",
                    "state": "SP",
                    "country": "CO",
                    "postal_code": "05781000",
                    "complement": "N/A"
                }
            }
        }
    }
}'

La API responde con un payload similar al siguiente ejemplo.

{
  "idempotency_key": "qr-flow-unique-key-123",
  "seller_id": "your-seller-id",
  "payment_id": "55853760-f2a5-4dff-b4f2-a60689c19966",
  "order_id": "35541354323",
  "amount": "400",
  "currency": "COP",
  "status": "PENDING",
  "payment_method": "WALLET",
  "received_at": "2025-11-15T10:05:00.000Z",
  "reason_code": "00",
  "reason_message": "Waiting for payment confirmation.",
  "additional_data": {
      "redirect_url": "[https://payment.nequi.com/qr/transaction-token-12345](https://payment.nequi.com/qr/transaction-token-12345)"
  }
}

2. Acción del cliente

La acción del cliente depende del flujo elegido:

Código QR

El usuario es redirigido a una página en la que aparece un código QR.

El usuario puede escanear el QR utilizando la aplicación móvil Nequi o hacer una captura de pantalla del código QR y subirla a la aplicación.

Notificación Push

El usuario recibe una notificación push en la aplicación móvil Nequi.

3. Verificar el estado del pago

Una vez que el cliente aprueba el pago, se envía una notificación webhook a su callback_url configurada con el estado actualizado (APPROVED o REJECTED).

También puede comprobar manualmente el estado utilizando el endpoint Get Transaction.

Payouts

La solución Nequi Payout permite a los comercios desembolsar fondos directamente al wallet digital Nequi de un cliente en Colombia. Esto es ideal para ganancias en la gig economy, reembolsos o retiradas de juegos.

La API de Getnet simplifica el proceso subyacente en una única petición. No es necesario registrar manualmente al usuario o el token; simplemente proporcione el número de teléfono del cliente y los detalles en la petición de payout.

Características

La siguiente tabla resume el comportamiento y los requisitos de los Payouts con Nequi.

Capacidad	Detalles
Tipo de Transacción	Desembolso (El comercio envía fondos al Cliente).
Confirmación	Asíncrona — Una notificación de webhook informa al comercio cuando los fondos se han abonado con éxito.
Requisitos de Datos	Número de Teléfono: Debe tener exactamente 10 dígitos. Detalles del Cliente: Se requiere Nombre y Apellido para el registro en el proveedor.

Flujo de Payout

El siguiente diagrama ilustra el flujo de negocio para un Payout con Nequi:

1. Crear la petición de payout

Para iniciar la transferencia, llame al endpoint Create Payout. Debe especificar el payment_method como WALLET_PAYOUT y proporcionar el número de teléfono Nequi del cliente.

El customer.phone_number es el identificador clave para la cuenta Nequi. Debe tener exactamente 10 dígitos de longitud.

Ejemplo de Petición:

curl --location --request POST '[https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payouts](https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payouts)' \
--header 'Content-Type: application/json' \
--header 'x-seller-id: your-seller-id' \
--header 'country: CO' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data-raw '{
    "idempotency_key": "payout-unique-key-001",
    "request_id": "req-payout-001",
    "order_id": "payout-ref-12345",
    "data": {
        "amount": 50000,
        "currency": "COP",
        "customer_id": "cust-001",
        "payment": {
            "payment_method": "WALLET_PAYOUT",
            "brand": "NEQUI",
            "soft_descriptor": "PAYOUT MERCHANT"
        },
        "additional_data": {
            "callback_url": "[https://your-domain.com/webhook/payouts](https://your-domain.com/webhook/payouts)",
            "customer": {
                "phone_number": "3001234567",
                "email": "[email protected]",
                "document_number": "12345678",
                "document_type": "CC",
                "first_name": "John",
                "last_name": "Smith"
            }
        }
    }
}'

Ejemplo de Respuesta:

{
  "idempotency_key": "payout-unique-key-001",
  "seller_id": "your-seller-id",
  "payment_id": "payout-nequi-998877",
  "order_id": "payout-ref-12345",
  "amount": "50000",
  "currency": "COP",
  "status": "PENDING",
  "payment_method": "WALLET_PAYOUT",
  "received_at": "2025-11-20T14:30:00.000Z",
  "reason_code": "00",
  "reason_message": "Payout request accepted. Processing funds transfer."
}

2. Verificar el estado del payout

La petición se procesa de forma asíncrona. No realice polling a la API; en su lugar, escuche la Notificación de Webhook enviada a su callback_url.

APPROVED: Los fondos ya están disponibles en la cuenta Nequi del cliente.
DECLINED: El payout falló (Número de teléfono no válido, cuenta inactiva o límites mensuales excedidos).

Reembolsos y cancelaciones

Los pagos con Nequi soportan reembolsos:

Reembolsos: Disponibles para transacciones liquidadas (settled). Puede realizar reembolsos totales o parciales.
Cancelaciones: Si un pago se encuentra aún en estado PENDING (por ejemplo, el cliente aún no ha aceptado el push), es posible que se pueda cancelar dependiendo del timeout específico del proveedor, pero habitualmente las transacciones Nequi se aprueban o caducan.

Para procesar un reembolso, siga las instrucciones de la guía Refund a Payment.