A API da Adyen impulsiona o processamento de pagamentos para empresas em todo o mundo, permitindo que desenvolvedores lidem com transações em canais online, móveis e presenciais. Engenheiros integram esta API para suportar mais de 250 métodos de pagamento em mais de 150 moedas, garantindo altas taxas de autorização e uma robusta prevenção de fraudes. Ao construir sistemas de pagamento seguros, ferramentas que simplificam os testes tornam-se essenciais.
Este artigo oferece um guia técnico sobre como acessar e usar a API da Adyen. Desenvolvedores geralmente começam com configurações básicas e progridem para recursos avançados, então o guia segue essa progressão. Primeiro, entenda os fundamentos, depois passe para a implementação prática.
O Que É a API da Adyen?
A API da Adyen serve como uma interface unificada para gateways de pagamento, permitindo que aplicativos processem transações com segurança. A plataforma conecta-se diretamente a redes de cartões e métodos de pagamento locais, ignorando intermediários. Essa conexão direta aumenta a eficiência e reduz custos.
A Adyen oferece diversas categorias de API, incluindo Checkout para pagamentos online, Recurring para assinaturas, Payouts para transferências de fundos e In-Person Payments para terminais de ponto de venda. Além disso, as APIs de Plataformas suportam soluções de marketplace, enquanto o BinLookup auxilia no cálculo de taxas e verificações 3D Secure.
Engenheiros acessam estes recursos por meio de endpoints RESTful, com requisições formatadas em JSON. Por exemplo, a API de Checkout lida com a iniciação de pagamentos, enquanto Webhooks notificam os sistemas sobre mudanças de status. A Adyen mantém compatibilidade retroativa através de versionamento, anexando sufixos como /v68 a URLs.
Além disso, a Adyen fornece bibliotecas cliente em linguagens como Java, Node.js, Python e .NET, simplificando as chamadas. Desenvolvedores as instalam via gerenciadores de pacotes – por exemplo, usando npm para a biblioteca Node.js. Essa configuração acelera o desenvolvimento ao abstrair interações HTTP de baixo nível.
No entanto, a API da Adyen requer configuração adequada para funcionar. Sem credenciais, as requisições falham com erros de autenticação. Portanto, a configuração da conta forma a base.
Por Que Escolher a API da Adyen Para Suas Necessidades de Pagamento?
Empresas escolhem a API da Adyen por sua escalabilidade e alcance global. O sistema processa bilhões de transações anualmente para empresas como Uber e eBay. Seu recurso RevenueProtect emprega aprendizado de máquina para detectar fraudes, minimizando estornos enquanto aprova pagamentos legítimos.
Além disso, a Adyen otimiza a receita através de roteamento inteligente, retentando autorizações falhas automaticamente. Isso aumenta as taxas de sucesso em até 5%. Para marketplaces, o MarketPay lida com a divisão de fundos entre vendedores, em conformidade com as regulamentações.
Comparada a alternativas como Stripe ou PayPal, a Adyen se destaca no comércio unificado – combinando pagamentos online e offline sob um único contrato. Desenvolvedores apreciam a documentação detalhada e o API Explorer, que lhes permite testar endpoints interativamente.
No entanto, a integração exige expertise técnica. Configurações simples levam horas, mas fluxos personalizados exigem dias. O Apidog aprimora esse processo, permitindo mocks e testes rápidos, garantindo a confiabilidade.
A seguir, configure seu ambiente para começar.
Como Configurar Uma Conta de Teste Adyen?
Você cria uma conta de teste para experimentar sem fundos reais. Visite o site da Adyen e inscreva-se para uma conta de desenvolvedor. Forneça detalhes comerciais, incluindo nome da empresa e localização. A Adyen analisa as aplicações, geralmente aprovando em poucos dias.
Uma vez aprovado, faça login na Área do Cliente em ca-test.adyen.com. Aqui, você gerencia contas de comerciante que terminam em -ECOM para e-commerce. O ambiente de teste simula transações, usando números de cartão falsos da documentação da Adyen.
Por exemplo, use o cartão 4111 1111 1111 1111 com CVV 737 para testes Visa. Habilite métodos de pagamento como iDEAL ou Klarna no painel. Este passo garante que sua integração suporte preferências regionais.
Além disso, diferencie ambientes de teste de ambientes de produção. URLs de teste usam test.adyen.com, enquanto as de produção incluem um prefixo único como [aleatório]-[Empresa]. A Adyen aconselha começar em modo de teste para evitar cobranças.
Após a configuração, obtenha as credenciais para autenticar as requisições.
Como Obter Credenciais de API e a Chave do Cliente?
Você gera chaves de API na Área do Cliente, em Developers > API credentials. Selecione uma credencial de nível de comerciante, como ws@Company.[SuaContaEmpresa]. Crie uma nova chave se nenhuma existir.
A chave da API se assemelha a Aq42_... e concede acesso aos endpoints. Copie-a com segurança, pois a Adyen não a exibirá novamente. Em seguida, gere uma Chave de Cliente na mesma página para autenticação do lado do cliente, prefixada com test_ ou live_.
Adicione origens permitidas, como http://localhost:8080, para evitar problemas de CORS. Salve as alterações. Essas chaves permitem chamadas do lado do servidor e componentes de frontend como o Drop-in.
Armazene as chaves em variáveis de ambiente ou arquivos de configuração, nunca em repositórios de código. Para aplicativos Java, injete-as via arquivos de propriedades. Esta prática aumenta a segurança.
Com as credenciais prontas, explore a autenticação.
Quais São os Métodos de Autenticação para a API da Adyen?
A Adyen emprega chaves de API para autenticação básica. Inclua a chave no cabeçalho X-API-Key para requisições do lado do servidor. Por exemplo:
curl -H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://checkout-test.adyen.com/v68/paymentMethods
O lado do cliente usa a Chave do Cliente para inicializar bibliotecas como Adyen.Web. Isso separa as preocupações, reduzindo a exposição.
Webhooks exigem validação HMAC. A Adyen assina as notificações com uma chave HMAC, que você verifica usando bibliotecas. Assinaturas inválidas indicam adulteração.
Além disso, alguns endpoints suportam tokens Bearer para OAuth, mas chaves de API são suficientes para a maioria das integrações. Sempre use HTTPS para criptografar as transmissões.
Autenticação mal configurada leva a erros 401. Portanto, teste as credenciais cedo.
Agora, examine os endpoints principais.
Explorando os Principais Endpoints na API da Adyen
A API da Adyen organiza os endpoints por função. O endpoint /paymentMethods recupera os métodos disponíveis com base na localização e moeda. Envie um POST com merchantAccount:
{
"merchantAccount": "YOUR_MERCHANT_ACCOUNT"
}
A resposta lista métodos como cartões ou iDEAL.
O endpoint /payments inicia transações. Inclua valor, paymentMethod e referência:
{
"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"
}
Respostas bem-sucedidas incluem resultCode como Authorised.
Para detalhes, use /payments/details para enviar dados adicionais, como resultados 3DS.
Endpoints da API Recurring como /recurring lidam com credenciais armazenadas. A API Payouts gerencia transferências de fundos.
O Apidog simplifica a exploração destes importando coleções, permitindo ajustes de parâmetros e validação de respostas.
Fazendo a transição para a implementação, siga estes passos.
Guia Passo a Passo: Integrando a API da Adyen em Sua Aplicação
Desenvolvedores integram a API da Adyen usando componentes de servidor e de cliente. Comece com um framework de backend como Java Spring Boot.
Primeiro, adicione a biblioteca da Adyen. Em build.gradle:
implementation 'com.adyen:adyen-java-api-library:31.3.0'
Configure o cliente:
Config config = new Config();
config.setApiKey("YOUR_API_KEY");
config.setEnvironment(Environment.TEST);
Client client = new Client(config);
PaymentsApi paymentsApi = new PaymentsApi(client);
No frontend, inclua 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">
Busque os métodos de pagamento:
async function getPaymentMethods() {
const response = await fetch('/api/paymentMethods', { method: 'POST' });
return await response.json();
}
Inicialize o 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 pagamentos, crie um 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);
Lide com o 3D Secure adicionando browserInfo e origin. Se action.type for redirect, redirecione o usuário.
Para webhooks, configure um endpoint para receber POSTs. Valide o HMAC:
HMACValidator hmacValidator = new HMACValidator();
if (hmacValidator.validateHMAC(notificationItem, "YOUR_HMAC_KEY")) {
// Process event
}
Habilite métodos específicos no painel. Para iDEAL:
Adicione a seleção do emissor em paymentMethod.
Para Klarna, inclua lineItems:
"lineItems": [
{
"description": "Item",
"quantity": 1,
"amountIncludingTax": 1000
}
]
Teste com a extensão de cartão da Adyen ou entradas manuais.
Esta integração suporta fluxos básicos. Expanda para tokenização: Armazene detalhes com /payments, definindo storeDetails: true.
A pré-autorização captura posteriormente via /captures.
O Apidog auxilia simulando respostas, testando casos extremos.
Como Usar o Apidog para Testar a API da Adyen?
O Apidog otimiza os testes da API da Adyen. Baixe a versão gratuita e importe a coleção da Adyen.
Por exemplo, cole um cURL para /adjustAuthorisation:
O Apidog o analisa, preenchendo os campos. Envie para ver as respostas.
Teste fluxos: Autorize, depois capture. Use asserções para códigos de status.
O Apidog simula endpoints, simulando atrasos ou erros. Integre com CI/CD para execuções automatizadas.
Para Adyen, valide a segurança como 3DS encadeando requisições.
Além disso, gere documentação a partir das especificações, compartilhando com as equipes.
Esta ferramenta reduz o esforço manual, detectando problemas cedo.
Melhores Práticas para Usar a API da Adyen
Implemente chaves de idempotência para prevenir duplicatas: Defina UUID em RequestOptions.
Use o fluxo de sessões para segurança do lado do cliente, gerando sessões no lado do servidor.
Monitore o desempenho com webhooks, registrando eventos.
Cumpra com o PCI DSS evitando o armazenamento de dados sensíveis.
Escale agrupando pagamentos.
Além disso, atualize as bibliotecas regularmente para obter recursos.
Problemas Comuns e Solução de Problemas
401 Não Autorizado: Verifique a chave da API.
HMAC Inválido: Verifique se a chave corresponde.
Pagamentos recusados: Use cartões de teste corretamente.
Erros de CORS: Adicione origens.
Consulte os logs na Área do Cliente.
Recursos Avançados: 3D Secure, Webhooks e Mais
Habilite 3DS dinâmico: Defina attemptAuthentication: always.
Webhooks notificam assincronamente – lide com eventos AUTHORISATION.
Para plataformas, use /transfers.
Integre BinLookup para taxas.
O Apidog testa isso com cenários.
Conclusão
Agora você sabe como acessar e usar a API da Adyen de forma eficaz. Desde a configuração até integrações avançadas, este guia capacita os desenvolvedores. Experimente no modo de teste e depois vá para o ambiente de produção. Ferramentas como o Apidog aceleram o processo.