La API de Adyen impulsa el procesamiento de pagos para empresas de todo el mundo, permitiendo a los desarrolladores gestionar transacciones en canales online, móviles y presenciales. Los ingenieros integran esta API para admitir más de 250 métodos de pago en más de 150 monedas, garantizando altas tasas de autorización y una sólida prevención de fraudes. A medida que construyes sistemas de pago seguros, las herramientas que simplifican las pruebas se vuelven esenciales.
Este artículo ofrece un recorrido técnico sobre cómo acceder y usar la API de Adyen. Los desarrolladores a menudo comienzan con configuraciones básicas y progresan a características avanzadas, por lo que la guía sigue esa progresión. Primero, comprende los fundamentos y luego pasa a la implementación práctica.
¿Qué es la API de Adyen?
La API de Adyen sirve como una interfaz unificada para pasarelas de pago, permitiendo que las aplicaciones procesen transacciones de forma segura. La plataforma se conecta directamente a las redes de tarjetas y a los métodos de pago locales, evitando intermediarios. Esta conexión directa aumenta la eficiencia y reduce los costos.
Adyen ofrece varias categorías de API, incluyendo Checkout para pagos online, Recurring para suscripciones, Payouts para transferencias de fondos e In-Person Payments para terminales de punto de venta. Además, las APIs de Plataformas soportan soluciones de mercado, mientras que BinLookup ayuda con los cálculos de tarifas y las verificaciones 3D Secure.
Los ingenieros acceden a estos a través de endpoints RESTful, con solicitudes formateadas en JSON. Por ejemplo, la API de Checkout gestiona las iniciaciones de pago, mientras que los Webhooks notifican a los sistemas los cambios de estado. Adyen mantiene la compatibilidad con versiones anteriores mediante el versionado, añadiendo sufijos como /v68 a las URLs.
Además, Adyen proporciona bibliotecas cliente en lenguajes como Java, Node.js, Python y .NET, simplificando las llamadas. Los desarrolladores las instalan a través de gestores de paquetes, por ejemplo, utilizando npm para la biblioteca de Node.js. Esta configuración acelera el desarrollo al abstraer las interacciones HTTP de bajo nivel.
Sin embargo, la API de Adyen requiere una configuración adecuada para funcionar. Sin credenciales, las solicitudes fallan con errores de autenticación. Por lo tanto, la configuración de la cuenta es la base.
¿Por qué elegir la API de Adyen para tus necesidades de pago?
Las empresas eligen la API de Adyen por su escalabilidad y alcance global. El sistema procesa miles de millones de transacciones anualmente para empresas como Uber y eBay. Su función RevenueProtect emplea aprendizaje automático para detectar fraudes, minimizando las devoluciones de cargos mientras aprueba pagos legítimos.
Además, Adyen optimiza los ingresos a través del enrutamiento inteligente, reintentando automáticamente las autorizaciones fallidas. Esto aumenta las tasas de éxito hasta en un 5%. Para los marketplaces, MarketPay gestiona la división de fondos entre vendedores, cumpliendo con las regulaciones.
En comparación con alternativas como Stripe o PayPal, Adyen destaca en el comercio unificado, combinando pagos online y offline bajo un mismo contrato. Los desarrolladores aprecian la documentación detallada y el API Explorer, que les permite probar los endpoints de forma interactiva.
Sin embargo, la integración exige conocimientos técnicos. Las configuraciones simples llevan horas, pero los flujos personalizados requieren días. Apidog mejora este proceso al permitir simulaciones y pruebas rápidas, garantizando la fiabilidad.
A continuación, configura tu entorno para empezar.
¿Cómo configurar una cuenta de prueba de Adyen?
Creas una cuenta de prueba para experimentar sin fondos reales. Visita el sitio web de Adyen y regístrate para una cuenta de desarrollador. Proporciona los detalles del negocio, incluyendo el nombre de la empresa y la ubicación. Adyen revisa las solicitudes, aprobándolas normalmente en cuestión de días.
Una vez aprobado, inicia sesión en el Área de Cliente en ca-test.adyen.com. Aquí, gestionas las cuentas de comerciante que terminan en -ECOM para comercio electrónico. El entorno de prueba simula transacciones, utilizando números de tarjeta falsos de la documentación de Adyen.
Por ejemplo, usa la tarjeta 4111 1111 1111 1111 con CVV 737 para pruebas de Visa. Habilita métodos de pago como iDEAL o Klarna en el panel de control. Este paso asegura que tu integración soporte las preferencias regionales.
Además, distingue entre entornos de prueba y en vivo. Las URLs de prueba usan test.adyen.com, mientras que las de producción incluyen un prefijo único como [aleatorio]-[Empresa]. Adyen aconseja empezar en modo de prueba para evitar cargos.
Después de la configuración, obtén las credenciales para autenticar las solicitudes.
¿Cómo obtener credenciales de API y clave de cliente?
Generas claves de API en el Área de Cliente en Desarrolladores > Credenciales de API. Selecciona una credencial a nivel de comerciante, como ws@Company.[TuCuentaDeEmpresa]. Crea una nueva clave si no existe ninguna.
La clave de API se parece a Aq42_... y otorga acceso a los endpoints. Cópiala de forma segura, ya que Adyen no la mostrará de nuevo. A continuación, genera una clave de cliente en la misma página para la autenticación del lado del cliente, con el prefijo test_ o live_.
Añade orígenes permitidos, como http://localhost:8080, para evitar problemas de CORS. Guarda los cambios. Estas claves permiten llamadas del lado del servidor y componentes frontend como Drop-in.
Almacena las claves en variables de entorno o archivos de configuración, nunca en repositorios de código. Para aplicaciones Java, inyéctalas a través de archivos de propiedades. Esta práctica mejora la seguridad.
Con las credenciales listas, explora la autenticación.
¿Cuáles son los métodos de autenticación para la API de Adyen?
Adyen emplea claves de API para la autenticación básica. Incluye la clave en el encabezado X-API-Key para las solicitudes del lado del servidor. Por ejemplo:
curl -H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://checkout-test.adyen.com/v68/paymentMethods
El lado del cliente utiliza la clave de cliente para inicializar bibliotecas como Adyen.Web. Esto separa las preocupaciones, reduciendo la exposición.
Los Webhooks requieren validación HMAC. Adyen firma las notificaciones con una clave HMAC, que se verifica utilizando bibliotecas. Las firmas no válidas indican manipulación.
Además, algunos endpoints soportan tokens Bearer para OAuth, pero las claves de API son suficientes para la mayoría de las integraciones. Utiliza siempre HTTPS para cifrar las transmisiones.
Una autenticación mal configurada lleva a errores 401. Por lo tanto, prueba las credenciales temprano.
Ahora, examina los endpoints principales.
Explorando los endpoints clave en la API de Adyen
La API de Adyen organiza los endpoints por función. El endpoint /paymentMethods recupera los métodos disponibles según la ubicación y la moneda. Envía un POST con merchantAccount:
{
"merchantAccount": "YOUR_MERCHANT_ACCOUNT"
}
La respuesta lista métodos como tarjetas o iDEAL.
El endpoint /payments inicia transacciones. Incluye amount, paymentMethod y reference:
{
"amount": {
"currency": "EUR",
"value": 1000
},
"reference": "YOUR_REFERENCE",
"paymentMethod": {
"type": "scheme",
"number": "4111111111111111",
"expiryMonth": "03",
"expiryYear": "2030",
"cvc": "737"
},
"merchantAccount": "YOUR_MERCHANT_ACCOUNT",
"returnUrl": "https://your-site.com/return"
}
Las respuestas exitosas incluyen resultCode como Authorised.
Para detalles, usa /payments/details para enviar datos adicionales, como resultados de 3DS.
Los endpoints de la API Recurring como /recurring gestionan credenciales almacenadas. La API Payouts gestiona transferencias de fondos.
Apidog simplifica la exploración de estos importando colecciones, permitiendo ajustes de parámetros y validación de respuestas.
Pasando a la implementación, sigue estos pasos.
Guía paso a paso: Integrando la API de Adyen en tu aplicación
Los desarrolladores integran la API de Adyen utilizando componentes del lado del servidor y del lado del cliente. Comienza con un framework de backend como Java Spring Boot.
Primero, añade la biblioteca de Adyen. En build.gradle:
implementation 'com.adyen:adyen-java-api-library:31.3.0'
Configura el cliente:
Config config = new Config();
config.setApiKey("YOUR_API_KEY");
config.setEnvironment(Environment.TEST);
Client client = new Client(config);
PaymentsApi paymentsApi = new PaymentsApi(client);
En el frontend, incluye Adyen.Web:
<script src="https://checkoutshopper-test.adyen.com/checkoutshopper/sdk/5.0.0/adyen.js"></script>
<link rel="stylesheet" href="https://checkoutshopper-test.adyen.com/checkoutshopper/sdk/5.0.0/adyen.css">
Obtén los métodos de pago:
async function getPaymentMethods() {
const response = await fetch('/api/paymentMethods', { method: 'POST' });
return await response.json();
}
Inicializa Drop-in:
const configuration = {
paymentMethodsResponse: await getPaymentMethods(),
clientKey: "YOUR_CLIENT_KEY",
locale: "en_US",
environment: "test",
onSubmit: (state, dropin) => {
// Handle submission
}
};
const checkout = await AdyenCheckout(configuration);
checkout.create('dropin').mount('#dropin-container');
Para los pagos, crea un endpoint de backend:
PaymentRequest paymentRequest = new PaymentRequest();
paymentRequest.merchantAccount("YOUR_MERCHANT_ACCOUNT");
paymentRequest.amount(new Amount().currency("EUR").value(1000L));
// Set other fields
PaymentResponse response = paymentsApi.payments(paymentRequest);
Gestiona 3D Secure añadiendo browserInfo y origin. Si action.type es redirect, redirige al usuario.
Para los webhooks, configura un endpoint para recibir POSTs. Valida HMAC:
HMACValidator hmacValidator = new HMACValidator();
if (hmacValidator.validateHMAC(notificationItem, "YOUR_HMAC_KEY")) {
// Process event
}
Habilita métodos específicos en el panel de control. Para iDEAL:
Añade la selección del emisor en paymentMethod.
Para Klarna, incluye lineItems:
"lineItems": [
{
"description": "Item",
"quantity": 1,
"amountIncludingTax": 1000
}
]
Prueba con la extensión de tarjeta de Adyen o entradas manuales.
Esta integración soporta flujos básicos. Expande para la tokenización: Almacena los detalles con /payments, estableciendo storeDetails: true.
La preautorización se captura más tarde a través de /captures.
Apidog ayuda simulando respuestas, probando casos extremos.
¿Cómo usar Apidog para probar la API de Adyen?
Apidog agiliza las pruebas de la API de Adyen. Descarga la versión gratuita e importa la colección de Adyen.
Por ejemplo, pega un cURL para /adjustAuthorisation:
Apidog lo analiza, rellenando los campos. Envía para ver las respuestas.
Flujos de prueba: Autoriza, luego captura. Usa aserciones para los códigos de estado.
Apidog simula endpoints, simulando retrasos o errores. Integra con CI/CD para ejecuciones automatizadas.
Para Adyen, valida la seguridad como 3DS encadenando solicitudes.
Además, genera documentos a partir de especificaciones, compartiéndolos con los equipos.
Esta herramienta reduce el esfuerzo manual, detectando problemas temprano.
Mejores prácticas para usar la API de Adyen
Implementa claves de idempotencia para evitar duplicados: Establece UUID en RequestOptions.
Usa el flujo de sesiones para la seguridad del lado del cliente, generando sesiones del lado del servidor.
Monitoriza el rendimiento con webhooks, registrando eventos.
Cumple con PCI DSS evitando el almacenamiento de datos sensibles.
Escala agrupando los pagos.
Además, actualiza las bibliotecas regularmente para obtener nuevas funcionalidades.
Problemas comunes y solución de problemas
401 No autorizado: Verifica la clave de API.
HMAC no válido: Verifica que la clave coincida.
Pagos rechazados: Usa las tarjetas de prueba correctamente.
Errores de CORS: Añade orígenes.
Consulta los registros en el Área de Cliente.
Funciones avanzadas: 3D Secure, Webhooks y más
Habilita 3DS dinámico: Establece attemptAuthentication: always.
Los Webhooks notifican de forma asíncrona: gestiona los eventos AUTHORISATION.
Para plataformas, usa /transfers.
Integra BinLookup para las tarifas.
Apidog prueba esto con escenarios.
Conclusión
Ahora sabes cómo acceder y usar la API de Adyen de manera efectiva. Desde la configuración hasta las integraciones avanzadas, esta guía equipa a los desarrolladores. Experimenta en modo de prueba y luego pasa a producción. Herramientas como Apidog aceleran el proceso.