Efecty

Um provedor de serviços financeiros que oferece vários serviços financeiros, como transferências de dinheiro, pagamentos de contas e muito mais.

A integração da API suporta Pay-ins (geração de uma referência de pagamento para depósitos em dinheiro) e Payouts (permitindo que os clientes retirem dinheiro em um local Efecty). Todos os fluxos são confirmados de forma assíncrona via webhook.

Requisitos

Antes de integrar o Efecty, 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.
Para Payouts: Certifique-se de que sua conta de estabelecimento tenha saldo suficiente para cobrir o valor do desembolso.

O Efecty está disponível apenas na Colômbia e espera a moeda COP. Contate o seu Gerente de Contas para habilitar este método de pagamento para a sua conta de estabelecimento.

Especificidades de Casos de Uso

Ao integrar qualquer solução Getnet, aplicam-se requisitos específicos do mercado. O Efecty está disponível apenas na Colômbia e apenas para as moedas COP e USD. Para saber mais sobre os requisitos específicos da Colômbia, certifique-se de revisar os recursos abaixo antes de entrar em produção (go live):

Características

A tabela abaixo resume o comportamento compartilhado e os requisitos para pagamentos Efecty.

Capacidade	Detalhes
Interação com o cliente	Redirecionamento / Voucher: O cliente recebe um código de referência para pagar em uma loja física.
Confirmação	Assíncrona: status inicial `PENDING`, depois `APPROVED` ou `DECLINED` via webhook.
Notificações	Webhooks para atualizações de status assíncronas quando o pagamento em dinheiro é processado.

Funcionalidades disponíveis

Use a matriz abaixo para confirmar os cenários atualmente suportados para o Efecty.

Fluxo de pagamento	Países suportados	Compras	Reembolsos	Reembolsos parciais	Pré-autorizações	Payouts
Redirect	Colômbia	✅	❌	❌	❌	✅

Fluxo de pagamento

Esta seção o guia através do processo completo de implementação de pagamentos Efecty. O diagrama abaixo fornece uma visão geral do processo de pagamento Efecty:

Fluxo Suportado

Este é o fluxo de pagamento atualmente suportado pela Getnet:

Pagamento Efecty (Depósito / Pay-in em Dinheiro): O usuário paga em dinheiro em um local Efecty. O fluxo é baseado em redirecionamento/voucher.

Esta operação é assíncrona; o estado final é confirmado apenas quando a Getnet recebe o webhook.

1. Criar a requisição de pagamento

Chame o endpoint Create – Authorize com os atributos abaixo.

A tabela descreve os campos mínimos obrigatórios para o pagamento Efecty.

Atributo	Descrição	Valor obrigatório
`payment_method`	Método de pagamento em dinheiro	`CASH_PAYMENT`
`brand`	Identificador da marca	`EFECTY`
`callback_url`	Para onde as atualizações de status são enviadas	Seu endpoint HTTPS
`amount`	Valor da transação em centavos	Inteiro (ex.: `5000` para €50.00)
`currency`	Código de moeda ISO	`COP` ou `USD`
`order_id`	Referência do estabelecimento para conciliação	String única

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 <your-token>' \
--data-raw '{
    "idempotency_key": "32f6208d-4be0-4430-a2cd-898b4b80f9c4",
    "request_id": "1d4daf69-ea17-4e5b-87c7-1f584eb52bc0",
    "order_id": "355413515499",
    "data": {
        "amount": 500001,
        "currency": "COP",
        "customer_id": "a354740d-bea2-46f7-8054-75823992a34c",
        "payment": {
            "payment_id": "1c41f4e1-5eab-41d4-a362-107b8308eb58",
            "payment_method": "CASH_PAYMENT",
            "brand": "EFECTY",
            "soft_descriptor": "EFECTY 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": 500001
                    }
                ]
            }
        }
    }
}'

A resposta contém a redirect_url, que deve ser usada para redirecionar o cliente para o Efecty (ou exibir o código de referência). A transação é imediatamente armazenada como pending na Getnet.

{
  "idempotency_key": "be278973-35eb-4c45-8619-2800d62b33b6",
  "seller_id": "2ab3e585-3607-467e-b2e8-420fcd45f48e",
  "payment_id": "772f951479c6514b1d9c4e8fd4808fe6",
  "order_id": "ORDER-10187383",
  "amount": "5000",
  "currency": "COP",
  "status": "PENDING",
  "payment_method": "EFECTY",
  "received_at": "2025-11-11T11:51:54.569Z",
  "redirect_url": "[https://efecty-payment-instructions.test/ref/XYZ123](https://efecty-payment-instructions.test/ref/XYZ123)",
  "transaction_id": "772f951479c6514b1d9c4e8fd4808fe6",
  "reason_code": "00",
  "reason_message": "Waiting for customer approval in Efecty."
}

2. Fluxo de Experiência do Usuário

O cliente é redirecionado para a página de terceiros para ver as instruções de pagamento.
O cliente conclui o depósito offline usando o código que recebe.
Uma vez que o cliente conclui o depósito offline, uma notificação com o status é enviada.

3. Verificar status do pagamento

Quando o cliente conclui o pagamento, uma notificação de webhook é enviada com o status atualizado do pagamento. Você também pode verificar o status do pagamento usando o endpoint Get Transaction.

Regras de Negócio

payment_method deve ser CASH_PAYMENT (com brand definido como EFECTY).
Moedas suportadas: COP.
O pagamento é uma operação assíncrona.

Payouts

A solução Efecty Payout permite que os estabelecimentos habilitem Retiradas em Dinheiro (Cash Pickups). O estabelecimento desembolsa fundos, e o beneficiário vai a qualquer local Efecty na Colômbia para retirar o dinheiro pessoalmente.

Características

A tabela abaixo resume o comportamento e os requisitos para Payouts Efecty.

Capacidade	Detalhes
Tipo de Transação	Desembolso em Dinheiro (O estabelecimento envia fundos -> O usuário retira Dinheiro).
Confirmação	Assíncrona — Uma notificação de webhook informa o estabelecimento quando o dinheiro foi recolhido pelo usuário.
Requisitos de Dados	Número do Documento (ID): Crítico. O usuário deve apresentar sua identidade governamental na loja para coletar o dinheiro.

Fluxo de Payout

O diagrama abaixo ilustra o fluxo de negócios para um Payout Efecty:

1. Criar a requisição de payout

Para iniciar a transferência, chame o endpoint Create Payout. Você deve especificar o payment_method como CASH_PAYOUT e fornecer os detalhes de identidade do cliente.

Certifique-se de que o customer.document_number corresponda exatamente ao documento de identidade físico do beneficiário, ou a retirada será negada na agência.

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-efecty-001",
    "request_id": "req-efecty-001",
    "order_id": "payout-ref-9988",
    "data": {
        "amount": 100000,
        "currency": "COP",
        "customer_id": "cust-002",
        "payment": {
            "payment_method": "CASH_PAYOUT",
            "brand": "EFECTY",
            "soft_descriptor": "PAYOUT MERCHANT"
        },
        "additional_data": {
            "callback_url": "[https://your-domain.com/webhook/payouts](https://your-domain.com/webhook/payouts)",
            "customer": {
                "email": "[email protected]",
                "document_number": "12345678",
                "document_type": "CC",
                "first_name": "Juan",
                "last_name": "Perez"
            }
        }
    }
}'

Exemplo de Resposta:

{
  "idempotency_key": "payout-efecty-001",
  "seller_id": "your-seller-id",
  "payment_id": "payout-efecty-trx-5566",
  "order_id": "payout-ref-9988",
  "amount": "100000",
  "currency": "COP",
  "status": "PENDING",
  "payment_method": "CASH_PAYOUT",
  "received_at": "2025-11-20T14:30:00.000Z",
  "reason_code": "00",
  "reason_message": "Payout registered. Waiting for beneficiary pickup."
}

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: O cliente recolheu com sucesso o dinheiro na agência.
DECLINED: O payout expirou (não foi retirado a tempo) ou foi cancelado.

Efecty

Requisitos

Especificidades de Casos de Uso

Características

Funcionalidades disponíveis

Fluxo de pagamento

Fluxo Suportado

1. Criar a requisição de pagamento

2. Fluxo de Experiência do Usuário

3. Verificar status do pagamento

Regras de Negócio

Payouts

Características

Fluxo de Payout

1. Criar a requisição de payout

2. Verificar status do payout

Leia mais