Saltar a contenido

Cómo aceptar pagos con tarjeta de crédito en su sitio web utilizando la API de 4Geeks Payments

🤖 Explicar con IA

La API de 4Geeks Payments permite a los desarrolladores crear experiencias de pago totalmente personalizables. Ya sea que esté operando una tienda de comercio electrónico sencilla o una plataforma SaaS compleja, esta API le permite procesar tarjetas de crédito, débito y transacciones de billeteras digitales directamente desde su aplicación.

Esta guía proporciona un recorrido paso a paso para integrar la API de Pagos, garantizando un procesamiento de transacciones seguro y eficiente.

Requisitos previos

Antes de escribir cualquier código, asegúrese de tener listo lo siguiente:

  • Cuenta de 4Geeks verificada: Debe tener acceso a la 4Geeks Console.
  • Servicio de Pagos activo: Asegúrese de que el módulo de Pagos esté habilitado en la configuración de su cuenta.
  • Credenciales de API: Necesitará su Client ID y Client Secret (o claves de API) del panel de desarrollador.
  • Certificado SSL: Su sitio web debe servir el contenido a través de HTTPS para manejar de forma segura los datos de las transacciones.

Instrucciones paso a paso

Siga estos pasos para procesar un cargo de pago estándar utilizando la API.

Paso 1: Obtener sus credenciales de API

Para comunicarse con la API, primero debe obtener sus credenciales seguras.

  1. Inicie sesión en la 4Geeks Console.
  2. Navegue a Settings > API Keys en el menú lateral.
  3. Localice su Client ID y Client Secret.

Consejo: Verá dos juegos de claves: “Test” y “Live”. Utilice siempre las claves de prueba (Test keys) durante el desarrollo para simular transacciones sin mover dinero real. Cambie a las claves en vivo (Live keys) solo cuando esté listo para el lanzamiento.

Paso 2: Generar un token de acceso

La API de 4Geeks utiliza la autenticación de Bearer Token. Debe intercambiar sus credenciales por un token de acceso temporal antes de realizar solicitudes de pago.

Endpoint: POST /oauth/token

Cuerpo de la solicitud (Request Body): 

    {
        "client_id": "TU_CLIENT_ID",
        "client_secret": "TU_CLIENT_SECRET",
        "grant_type": "client_credentials"
    }

Respuesta: La API devolverá un objeto JSON que contiene un access_token. Utilizará este token en el encabezado de sus solicitudes posteriores.

Paso 3: Crear un cargo de pago

Ahora que está autenticado, puede iniciar una transacción. Esta solicitud envía los detalles del pago a 4Geeks para su procesamiento.

Endpoint: POST /v1/payments/

Encabezados (Headers):

  • Authorization: Bearer <TU_ACCESS_TOKEN>
  • Content-Type: application/json

Parámetros del cuerpo (Body Parameters):

  • amount: El costo total (por ejemplo, 150.00).
  • currency: El código ISO de 3 letras (por ejemplo, USD, EUR).
  • description: Un breve resumen de la compra.
  • return_url: La URL a la que se redirigirá a su cliente después del proceso de pago (esencial para los flujos de 3D Secure).

Ejemplo de solicitud:

{
  "amount": 150.00,
  "currency": "USD",
  "description": "Suscripción Premium Anual",
  "return_url": "https://su-sitio-web.com/checkout/success"
}

Paso 4: Manejar la respuesta

La API devolverá el estado de la transacción inmediatamente.

  • Éxito (Success): Si el estado es succeeded o approved, el pago se ha completado. Debe mostrar un mensaje de éxito al usuario y actualizar su base de datos.
  • Acción requerida (Action Required): Si el estado es action_required (común con 3D Secure), la respuesta incluirá una redirect_url. Debe redirigir al cliente a esta URL para completar la verificación bancaria.

Casos de uso comunes

1. Proceso de pago de comercio electrónico

Un cliente añade productos a su carrito y hace clic en “Pagar”. Su backend calcula el total y llama al endpoint /v1/payments/. Tras una respuesta exitosa, usted activa su sistema de inventario (quizás gestionado por 4Geeks Asset) para descontar el stock y enviar un correo electrónico de confirmación.

2. Facturación de suscripciones SaaS

Para un servicio de software mensual, puede tokenizar la tarjeta de un cliente durante su primer pago. Luego puede usar ese token para automatizar los cargos futuros a través de la API sin pedirle al usuario que vuelva a introducir sus datos cada mes. Esto se integra perfectamente con las funciones de facturación recurrente de 4Geeks Payments.

Solución de problemas

Aquí tiene soluciones a los errores comunes que podría encontrar durante la integración:

  • Error 401 Unauthorized:
  • Causa: Su Bearer Token falta, es incorrecto o ha caducado.

  • Solución: Regenere un nuevo token utilizando el endpoint /oauth/token y asegúrese de que se incluya correctamente en el encabezado de Autorización.

  • Transacción rechazada (Error genérico):

  • Causa: El emisor de la tarjeta rechazó la transacción (por ejemplo, fondos insuficientes).

  • Solución: Verifique el error_code en la respuesta de la API. Si está en modo de prueba, asegúrese de utilizar los números de tarjeta de prueba válidos proporcionados en la documentación.

  • Error de CORS:

  • Causa: Está intentando realizar llamadas a la API directamente desde el navegador (lado del cliente).
  • Solución: Por seguridad, nunca exponga su Client Secret en el código de frontend. Enrute siempre las solicitudes de pago a través de su propio servidor de backend.

Conclusión

Integrar la API de 4Geeks Payments le otorga un control total sobre sus flujos de pago, permitiendo una experiencia personalizada y segura para sus usuarios. Siguiendo estos pasos, puede empezar a aceptar tarjetas de crédito de forma segura y eficiente.

Para configuraciones más avanzadas, como guardar tarjetas para su uso futuro o gestionar webhooks, visite la 4Geeks Console o explore nuestra documentación para desarrolladores.

Recursos adicionales