# Nequi nequi logo A Nequi é uma carteira digital amplamente utilizada na Colômbia. A integração da API suporta **Pay-ins** (coleta de fundos via QR Code ou Notificação Push) e **Payouts** (desembolso de fundos diretamente para uma conta Nequi). Todos os fluxos são confirmados de forma assíncrona via webhook. #### Métodos de Pagamento Disponíveis Existem duas formas principais para um cliente concluir um pagamento com a Nequi, determinadas pelo campo `payment_method`: 1. **Nequi QR (`WALLET`):** A API retorna uma `redirect_url`. O estabelecimento pode redirecionar o cliente para esta URL ou renderizá-la como um QR code para o cliente escanear usando o aplicativo Nequi. 2. **Nequi Push (`WALLET_PUSH`):** O estabelecimento aciona uma notificação push para o número de telefone do cliente. O cliente aceita o pagamento diretamente no aplicativo Nequi. ## Requisitos Antes de integrar a Nequi, você precisa: * Gerar um token de acesso através do [endpoint de Autenticação](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/authentication). * Configurar uma `callback_url` HTTPS pública para receber atualizações de status assíncronas quando o cliente concluir ou rejeitar o pagamento. * Garantir que a conta do estabelecimento esteja configurada para a Colômbia (CO) e para a moeda COP. * **Para Payouts:** Certifique-se de que sua conta de estabelecimento tenha saldo suficiente para cobrir o valor do desembolso. ## Especificidades de Casos de Uso Ao integrar a Nequi via Getnet, aplicam-se requisitos específicos do mercado. A Nequi está disponível apenas na **Colômbia** e suporta a moeda **COP**. * [Códigos de moeda](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) * [Impostos e regulamentações locais](https://www.google.com/search?q=/en/articles%3Farticle%3Dtaxes-and-regulations) ## Características A tabela abaixo resume o comportamento e os requisitos para os fluxos de pagamento Nequi. | Capacidade | Detalhes | | :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Experiência do cliente** | **Fluxo QR:** O cliente escaneia um código gerado a partir da URL de redirecionamento. \
**Fluxo Push:** O cliente recebe uma notificação em seu telefone para aprovar. | | **Confirmação** | Assíncrona — Uma notificação webhook informa o estabelecimento quando o pagamento é aprovado ou rejeitado. | | **Idempotência & unicidade** | Cada requisição deve incluir uma `idempotency_key` única. | ## Funcionalidades disponíveis Use a matriz abaixo para confirmar os cenários atualmente suportados para a Nequi. | Fluxo de pagamento | Países suportados | Compras | Reembolsos | Reembolsos parciais | Pré-autorizações | Pagamentos recorrentes | Payouts | | :----------------: | :-----------------: | :-------: | :-----: | :-------------: | :----------------: | :----------------: | :-----: | | Direto (QR / Push) | Colômbia | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ## Fluxo de pagamento Esta seção o guia através do processo completo de implementação de pagamentos Nequi. O diagrama abaixo fornece uma visão geral do processo de pagamento Nequi: ### 1\. Criar a requisição de pagamento Para iniciar um pagamento Nequi, chame o [endpoint Create - Authorize](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payments/post/dpm/payments-gwproxy/v2/payments). Você deve escolher o fluxo definindo o `payment_method` e fornecer o número de celular do cliente (crítico para o fluxo Push). A tabela descreve os campos mínimos obrigatórios para um pagamento Nequi. | Atributo | Descrição | Valor obrigatório | | :---------------------- | :------------------------------------ | :------------------------------------------------------------------------ | | `payment_method` | Define o tipo de fluxo | `WALLET` (para fluxo QR Code) ou `WALLET_PUSH` (para fluxo Notificação Push) | | `brand` | Identificador da marca Nequi | `NEQUI` | | `callback_url` | Para onde as atualizações de status são enviadas | Seu endpoint HTTPS | | `amount` | Valor da transação em centavos | Inteiro (ex.: `10000` para \$100.00 COP) | | `currency` | Código de moeda ISO | `COP` | | `order_id` | Referência do estabelecimento para conciliação | String única (máx. 32 caracteres) | | `customer.phone_number` | Número de celular do cliente | String (ex., `3001234567`) | #### Notificação Push Nequi Use `WALLET_PUSH`. O cliente recebe uma notificação em seu telefone. Nenhuma URL de redirecionamento é retornada na resposta. O exemplo de requisição a seguir mostra como inicializar um pagamento por notificação push da 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 } ] } } } }' ``` A API responde com um payload semelhante ao exemplo abaixo. ```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." } ``` #### QR Code Nequi Use `WALLET`. A API retorna uma `redirect_url` que permite ao estabelecimento gerar um QR code. O exemplo de requisição a seguir mostra como inicializar um pagamento QR da 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" } } } } }' ``` A API responde com um payload semelhante ao exemplo abaixo. ```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\. Ação do Cliente A ação do cliente depende do fluxo escolhido: #### QR Code 1. O usuário é redirecionado para uma página na qual um QR code é exibido. nequi QR code O usuário pode escanear o QR usando o aplicativo móvel Nequi ou tirar uma captura de tela do QR code e enviá-la para o aplicativo. nequi app flow #### Notificação Push O usuário recebe uma notificação push no aplicativo móvel Nequi. nequi app notification ### 3\. Verificar status do pagamento Assim que o cliente aprova o pagamento, uma notificação de webhook é enviada para a sua `callback_url` configurada com o status atualizado (`APPROVED` ou `REJECTED`). Você também pode verificar o status manualmente usando o [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 A solução Nequi Payout permite que os estabelecimentos desembolsem fundos diretamente para a carteira digital Nequi de um cliente na Colômbia. Isso é ideal para ganhos na gig economy, reembolsos ou saques de jogos. A API da Getnet simplifica o processo subjacente em uma única requisição. Você não precisa registrar o usuário ou token manualmente; basta fornecer o número de telefone e os detalhes do cliente na requisição de payout. ### Características A tabela abaixo resume o comportamento e os requisitos para Payouts da Nequi. | Capacidade | Detalhes | | :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | | **Tipo de Transação** | **Desembolso** (O estabelecimento envia fundos para o Cliente). | | **Confirmação** | Assíncrona — Uma notificação webhook informa o estabelecimento quando os fundos foram creditados com sucesso. | | **Requisitos de Dados** | **Número de Telefone:** Deve ter exatamente **10 dígitos**. \
**Detalhes do Cliente:** Nome e Sobrenome são obrigatórios para o registro do provedor. | ### Fluxo de Payout O diagrama abaixo ilustra o fluxo de negócios para um Payout da Nequi: #### 1\. Criar a requisição de payout Para iniciar a transferência, chame o endpoint **Create Payout**. Você deve especificar o `payment_method` como `WALLET_PAYOUT` e fornecer o número de telefone Nequi do cliente. O `customer.phone_number` é o identificador chave para a conta Nequi. Ele deve ter exatamente **10 dígitos** de comprimento. **Exemplo de Requisição:** ```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" } } } }' ``` **Exemplo de Resposta:** ```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 status do payout A requisição é processada de forma assíncrona. Não faça polling na API; em vez disso, aguarde a **Notificação de Webhook** enviada para a sua `callback_url`. * **`APPROVED`**: Os fundos agora estão disponíveis na conta Nequi do cliente. * **`DECLINED`**: O payout falhou (Número de telefone inválido, conta inativa ou limites mensais excedidos). ## Reembolsos e cancelamentos Pagamentos Nequi suportam reembolsos: * **Reembolsos:** Disponíveis para transações liquidadas (settled). Você pode realizar reembolsos totais ou parciais. * **Cancelamentos:** Se um pagamento ainda estiver no status `PENDING` (por exemplo, o cliente ainda não aceitou o push), ele pode ser cancelável dependendo do tempo limite específico do provedor, mas tipicamente as transações Nequi são aprovadas ou expiram. Para processar um reembolso, siga as instruções no [guia Refund a Payment](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Drefund-payment).