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

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

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

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.

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

El cliente es redirigido a la página de terceros para ver las instrucciones de pago.
El cliente completa el depósito offline usando el código que recibe.
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.

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:

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

Ejemplo de Respuesta:

{
  "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 para la gestión de tokens y las mejores prácticas de seguridad.