# 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](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.
* **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):
* [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 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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payments/post/dpm/payments-gwproxy/v2/payments) 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 |
```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": "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": "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": 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.
```json
{
"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
1. O cliente é redirecionado para a página de terceiros para ver as instruções de pagamento.
2. O cliente conclui o depósito offline usando o código que recebe.
3. 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](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).
## 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:**
```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-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": "juan.perez@email.com",
"document_number": "12345678",
"document_type": "CC",
"first_name": "Juan",
"last_name": "Perez"
}
}
}
}'
```
**Exemplo de Resposta:**
```json
{
"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.
## Leia mais
* Revise [Autenticação](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/authentication/post/authentication/oauth2/access_token) para gerenciamento de tokens e melhores práticas de segurança.