Nequi

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:

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.
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.
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.

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. <br /> 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.

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.

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

A API responde com um payload semelhante ao exemplo abaixo.

{
  "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.

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

A API responde com um payload semelhante ao exemplo abaixo.

{
  "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

O usuário é redirecionado para uma página na qual um QR code é exibido.

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.

Notificação Push

O usuário recebe uma notificação push no aplicativo móvel Nequi.

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.

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. <br /> 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:

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

Exemplo de Resposta:

{
  "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.