# Nequi nequi logo 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`: 1. **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. 2. **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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/authentication). * 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**. * [Códigos de moneda](https://www.google.com/search?q=/en/articles%3Farticle%3Dcurrency-codes) * [Tipos de documento](https://www.google.com/search?q=/en/articles%3Farticle%3Ddocument-types) * [Impuestos y normativas locales](https://www.google.com/search?q=/en/articles%3Farticle%3Dtaxes-and-regulations) ## 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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payments/post/dpm/payments-gwproxy/v2/payments). 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. ```bash 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 ' \ --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": "stevan.viapiana@getnet.net", "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. ```json { "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. ```bash 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 ' \ --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": "stevan.viapiana@getnet.net", "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. ```json { "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 1. El usuario es redirigido a una página en la que aparece un código QR. nequi QR code 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. nequi app flow #### Notificación Push El usuario recibe una notificación push en la aplicación móvil Nequi. nequi app notification ### 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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payment-record-management/get/dpm/hub-payment-info/v1/payments/info/%7Bpayment_id%7D). ## 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:** ```bash 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 ' \ --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": "john.smith@email.com", "document_number": "12345678", "document_type": "CC", "first_name": "John", "last_name": "Smith" } } } }' ``` **Ejemplo de Respuesta:** ```json { "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](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Drefund-payment).