# Efecty
Un proveedor de servicios financieros que ofrece diversos servicios financieros, como transferencias de dinero, pago de recibos y mucho más.
La integración de la API admite **Pay-ins** (generación de una referencia de pago para ingresos en efectivo) y **Payouts** (que permite a los clientes retirar efectivo en un establecimiento de Efecty). Todos los flujos se confirman de forma asíncrona mediante webhook.
## Requisitos
Antes de integrar Efecty 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.
* **Para Payouts:** Asegúrese de que su cuenta de comercio tiene saldo suficiente para cubrir el importe del desembolso.
Efecty solo está disponible en Colombia y espera COP. Contacte con su Account Manager para habilitar este método de pago en su cuenta de comercio.
## Especificidades de Casos de Uso
Al integrar cualquier solución de Getnet, se aplican requisitos específicos de cada mercado. Efecty solo está disponible en Colombia y exclusivamente para las monedas COP y USD. Para saber más sobre los requisitos específicos de Colombia, asegúrese de revisar los siguientes recursos antes de pasar a producción (go live):
* [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 compartidos para los pagos con Efecty.
| Capacidad | Detalles |
| ------------------------ | -------------------------------------------------------------------------------------- |
| **Interacción con el cliente** | **Redirección / Voucher:** El cliente recibe un código de referencia para pagar en una tienda física. |
| **Confirmación** | Asíncrona: estado inicial `PENDING`, luego `APPROVED` o `DECLINED` mediante webhook. |
| **Notificaciones** | Webhooks para actualizaciones de estado asíncronas cuando se procesa el pago en efectivo. |
## Funcionalidades disponibles
Utilice la siguiente matriz para confirmar los escenarios actualmente soportados para Efecty.
| Flujo de pago | Países soportados | Compras | Reembolsos | Reembolsos parciales | Preautorizaciones | Payouts |
| :----------: | :-----------------: | :-------: | :-----: | :-------------: | :----------------: | :-----: |
| Redirect | Colombia | ✅ | ❌ | ❌ | ❌ | ✅ |
## Flujo de pago
Esta sección le guiará a través del proceso completo de implementación de pagos con Efecty. El siguiente diagrama ofrece una visión general del proceso de pago con Efecty:
## Flujo Soportado
Este es el flujo de pago que actualmente soporta Getnet:
* **Pago con Efecty (Depósito / Pay-in en efectivo):** El usuario paga en efectivo en un establecimiento de Efecty. El flujo se **basa en redirección/voucher**.
Esta operación es asíncrona; el estado final solo se confirma cuando Getnet recibe el webhook.
## 1\. Crear la petición de pago
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) con los atributos a continuación.
La tabla resume los campos mínimos obligatorios para el pago con Efecty.
| Atributo | Descripción | Valor obligatorio |
| :--------------- | :------------------------------------ | :------------------------------- |
| `payment_method` | Método de pago en efectivo | `CASH_PAYMENT` |
| `brand` | Identificador de la marca | `EFECTY` |
| `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. `5000` para 50,00 €) |
| `currency` | Código de moneda ISO | `COP` o `USD` |
| `order_id` | Referencia del comercio para conciliación | Cadena ú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
}
]
}
}
}
}'
```
La respuesta contiene la `redirect_url`, que **debe usarse para redirigir al cliente a Efecty** (o mostrar el código de referencia). La transacción se almacena inmediatamente como `pending` en 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\. Flujo de Experiencia del Usuario
1. El cliente es redirigido a la página de terceros para ver las instrucciones de pago.
2. El cliente completa el depósito offline usando el código que recibe.
3. Una vez que el cliente completa el depósito offline, se envía una notificación con el estado.
## 3\. Verificar el estado del pago
Cuando el cliente completa el pago, se envía una notificación de webhook con el estado actualizado del pago. También puede comprobar el estado del pago 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).
## Reglas de Negocio
* `payment_method` debe ser `CASH_PAYMENT` (con `brand` establecido en `EFECTY`).
* Monedas soportadas: `COP`.
* El pago es una operación **asíncrona**.
## Payouts
La solución Efecty Payout permite a los comercios habilitar las **Retiradas de Efectivo (Cash Pickups)**. El comercio desembolsa los fondos, y el beneficiario acude a cualquier establecimiento de Efecty en Colombia para retirar el efectivo en persona.
### Características
La siguiente tabla resume el comportamiento y los requisitos para los Payouts con Efecty.
| Capacidad | Detalles |
| :-------------------- | :--------------------------------------------------------------------------------------------------------------- |
| **Tipo de Transacción** | **Desembolso de Efectivo** (El comercio envía los fondos -\> El usuario recoge el Efectivo). |
| **Confirmación** | Asíncrona — Una notificación de webhook informa al comercio cuando el usuario ha recogido el efectivo. |
| **Requisitos de Datos** | **Número de Documento (ID):** Crítico. El usuario debe presentar su documento de identidad gubernamental en la tienda para recoger el dinero. |
### Flujo de Payout
El siguiente diagrama ilustra el flujo de negocio para un Payout con Efecty:
#### 1\. Crear la petición de payout
Para iniciar la transferencia, llame al endpoint **Create Payout**. Debe especificar el `payment_method` como `CASH_PAYOUT` y proporcionar los detalles de identidad del cliente.
Asegúrese de que el `customer.document_number` coincida exactamente con el documento de identidad físico del beneficiario, o se le denegará la retirada en la sucursal.
**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-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"
}
}
}
}'
```
**Ejemplo de Respuesta:**
```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 el estado del payout
La petición se procesa de forma asíncrona. No realice polling a la API; en su lugar, espere la **Notificación de Webhook** enviada a su `callback_url`.
* **`APPROVED`**: El cliente ha recogido el efectivo con éxito en la sucursal.
* **`DECLINED`**: El payout ha caducado (no se ha recogido a tiempo) o se ha cancelado.
## Más información
* Revise [Autenticación](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/authentication/post/authentication/oauth2/access_token) para la gestión de tokens y las mejores prácticas de seguridad.