Tu primer pago

• Tu primer pago
  • Antes de empezar
  • Elige tu modalidad
  • Camino A · redirect, en dos pasos
  • Camino B · api, en tres pasos
  • Y ahora, ¿qué?

Antes de empezar

Tres cosas, cinco minutos:

1. Un token de prueba. Genéralo en Documentación → API key.
2. El id de tu sucursal. Está en la misma pantalla, o pídelo con GET /api/v1/offices/get.
3. curl o el cliente HTTP que prefieras.

La URL base es https://sag-qa.efipay.co/api/v1 y no cambia entre prueba y producción: lo que cambia es el token.

Comprueba que todo está en orden:

curl -X GET \
'/api/v1/offices/get' \
-H 'Authorization: Bearer TU_TOKEN_DE_PRUEBA' \
-H 'Content-type: application/json'

Si ves tus sucursales, ya puedes cobrar.

Elige tu modalidad

{success} Si estás empezando, usa redirect. Es más rápido de integrar y el número de tarjeta nunca pasa por tus servidores. Puedes cambiar a api más adelante sin rehacer la integración: el paso 1 es el mismo.

Camino A · redirect, en dos pasos

Paso 1 · Genera el cobro

curl -X POST \
'/api/v1/payment/generate-payment' \
-H 'Authorization: Bearer TU_TOKEN_DE_PRUEBA' \
-H 'Content-type: application/json' \
-d '{
    "payment": {
        "description": "Mi primer cobro",
        "amount": 50000,
        "currency_type": "COP",
        "checkout_type": "redirect"
    },
    "advanced_options": {
        "has_comments": false,
        "result_urls": {
            "approved": "https://mi-tienda.com/gracias",
            "rejected": "https://mi-tienda.com/error",
            "pending": "https://mi-tienda.com/procesando",
            "webhook": "https://mi-tienda.com/webhooks/efipay"
        }
    },
    "office": 1
}'

{
    "saved": true,
    "payment_id": "9dc12b03-5833-496a-83e6-4dfb8eb2570b",
    "url": "https://sag-qa.efipay.co/Checkout/PaymentGateway/9dc12b03-...?signature=e7e333..."
}

Guarda el payment_id junto a tu pedido: es cómo vas a reconocer el pago cuando llegue el webhook.

Paso 2 · Manda a tu cliente al link

Redirige a url. Ahí tu cliente elige medio de pago y paga.

Prueba con una tarjeta que aprueba:

Al terminar vuelve a la result_urls que corresponda, y tú recibes el webhook con el resultado.

{warning} Decide con el webhook, no con la URL de retorno. El cliente puede cerrar el navegador antes de volver, y entonces la redirección nunca ocurre pero el pago sí.

Camino B · api, en tres pasos

{danger} Este camino recibe el número de tarjeta y el CVV en tu servidor. Úsalo solo si tu plataforma está certificada en PCI DSS.

Paso 1 · Genera el cobro, pidiendo un token

Igual que antes, pero con checkout_type: "api":

curl -X POST \
'/api/v1/payment/generate-payment' \
-H 'Authorization: Bearer TU_TOKEN_DE_PRUEBA' \
-H 'Content-type: application/json' \
-d '{
    "payment": {
        "description": "Mi primer cobro",
        "amount": 50000,
        "currency_type": "COP",
        "checkout_type": "api"
    },
    "advanced_options": {
        "has_comments": false,
        "result_urls": {
            "approved": "https://mi-tienda.com/gracias",
            "rejected": "https://mi-tienda.com/error",
            "pending": "https://mi-tienda.com/procesando",
            "webhook": "https://mi-tienda.com/webhooks/efipay"
        }
    },
    "office": 1
}'

{
    "saved": true,
    "payment_id": "9dc12b26-dc55-474c-8602-5d9e00af129e",
    "token": "ZQZ82Ifn5fAuzKL"
}

{danger} El token se muestra una sola vez. Guárdalo con el payment_id: los dos juntos autentican el paso 2.

Paso 2 · Cobra con la tarjeta

curl -X POST \
'/api/v1/payment/transaction-checkout/card' \
-H 'Authorization: Bearer TU_TOKEN_DE_PRUEBA' \
-H 'Content-type: application/json' \
-d '{
    "payment": {
        "id": "9dc12b26-dc55-474c-8602-5d9e00af129e",
        "token": "ZQZ82Ifn5fAuzKL"
    },
    "customer_payer": {
        "name": "Ana Gomez",
        "email": "ana@ejemplo.com",
        "address_1": "Calle 100 # 20-30",
        "city": "Bogota",
        "state": "Cundinamarca",
        "country": "COL",
        "zip_code": "110111"
    },
    "payment_card": {
        "number": "4485902178877927",
        "name": "ANA GOMEZ",
        "expiration_date": "2030-12",
        "cvv": "963",
        "installments": 1,
        "dialling_code": "+57",
        "cellphone": "3001234567"
    }
}'

Paso 3 · Lee el resultado

La respuesta trae el estado de la transacción. Si activaste 3D Secure, en su lugar recibirás las instrucciones para continuar la autenticación: ver el flujo de 3DS.

Prueba también un rechazo —4315 8923 8199 8017 con CVV 950— y comprueba que tu sistema no deja el pedido a medias. Es la mitad del trabajo y la que suele quedar sin probar.

Y ahora, ¿qué?

En este orden:

1. Recibe el webhook y verifica su firma. Es lo que hace que tu integración sea confiable.
2. Prueba los rechazos y el estado Pendiente.
3. Consulta el estado como respaldo, para cuando un webhook no llegue.
4. Recorre la lista de verificación antes de cambiar al token de producción.

Y según lo que cobres: