Adyen API는 전 세계 기업의 결제 처리를 지원하여 개발자가 온라인, 모바일 및 대면 채널 전반에서 거래를 처리할 수 있도록 합니다. 엔지니어는 이 API를 통합하여 150개 이상의 통화로 250개 이상의 결제 수단을 지원하며, 높은 승인율과 강력한 사기 방지 기능을 보장합니다. 안전한 결제 시스템을 구축할 때 테스트를 단순화하는 도구는 필수적입니다.
이 글은 Adyen API에 액세스하고 사용하는 방법에 대한 기술적인 단계별 가이드를 제공합니다. 개발자들은 종종 기본적인 설정으로 시작하여 고급 기능으로 나아가므로, 이 가이드도 그러한 진행 방식에 따릅니다. 먼저 기본 사항을 이해한 다음 실제 구현으로 넘어갑니다.
Adyen API란 무엇인가요?
Adyen API는 결제 게이트웨이를 위한 통합 인터페이스 역할을 하며, 애플리케이션이 거래를 안전하게 처리할 수 있도록 합니다. 이 플랫폼은 카드 네트워크 및 현지 결제 수단에 직접 연결되어 중개자를 거치지 않습니다. 이러한 직접 연결은 효율성을 높이고 비용을 절감합니다.
Adyen은 온라인 결제를 위한 Checkout, 구독을 위한 Recurring, 자금 이체를 위한 Payouts, POS(Point-of-Sale) 단말기를 위한 In-Person Payments를 포함한 여러 API 카테고리를 제공합니다. 또한 Platforms API는 마켓플레이스 솔루션을 지원하며, BinLookup은 수수료 계산 및 3D Secure 검사를 돕습니다.
엔지니어는 RESTful 엔드포인트를 통해 JSON 형식의 요청으로 이러한 기능에 액세스합니다. 예를 들어, Checkout API는 결제 시작을 처리하고, 웹훅(Webhooks)은 시스템에 상태 변경을 알립니다. Adyen은 URL에 /v68과 같은 접미사를 추가하는 버전 관리를 통해 하위 호환성을 유지합니다.
또한 Adyen은 Java, Node.js, Python, .NET과 같은 언어로 클라이언트 라이브러리를 제공하여 호출을 단순화합니다. 개발자는 패키지 관리자(예: Node.js 라이브러리의 경우 npm 사용)를 통해 이를 설치합니다. 이러한 설정은 낮은 수준의 HTTP 상호작용을 추상화하여 개발 속도를 높입니다.
하지만 Adyen API가 제대로 작동하려면 적절한 구성이 필요합니다. 자격 증명 없이는 요청이 인증 오류와 함께 실패합니다. 따라서 계정 설정이 기본이 됩니다.
결제 요구 사항에 Adyen API를 선택해야 하는 이유?
기업들은 확장성과 글로벌 도달 범위 때문에 Adyen API를 선택합니다. 이 시스템은 Uber 및 eBay와 같은 회사에서 연간 수십억 건의 거래를 처리합니다. RevenueProtect 기능은 머신러닝을 사용하여 사기를 감지하고, 합법적인 결제를 승인하는 동시에 차지백(chargeback)을 최소화합니다.
또한 Adyen은 지능형 라우팅을 통해 수익을 최적화하고, 실패한 승인을 자동으로 재시도합니다. 이는 성공률을 최대 5%까지 높입니다. 마켓플레이스의 경우 MarketPay는 판매자 간의 자금 분할을 처리하며 규정을 준수합니다.
Stripe 또는 PayPal과 같은 대안과 비교할 때 Adyen은 통합 커머스(단일 계약으로 온라인 및 오프라인 결제 결합)에서 탁월합니다. 개발자들은 상세한 문서와 API Explorer를 통해 엔드포인트를 대화식으로 테스트할 수 있음을 높이 평가합니다.
그럼에도 불구하고 통합에는 기술적 전문성이 필요합니다. 간단한 설정은 몇 시간이 걸리지만, 사용자 정의 흐름은 며칠이 걸립니다. Apidog는 빠른 모의 테스트 및 실제 테스트를 가능하게 하여 신뢰성을 보장함으로써 이 프로세스를 향상시킵니다.
다음으로, 시작하려면 환경을 구성하세요.
Adyen 테스트 계정을 어떻게 설정하나요?
실제 자금 없이 실험하기 위해 테스트 계정을 만듭니다. Adyen 웹사이트를 방문하여 개발자 계정에 가입하세요. 회사 이름과 위치를 포함한 비즈니스 세부 정보를 제공합니다. Adyen은 신청서를 검토하며, 일반적으로 며칠 내에 승인합니다.
승인되면 ca-test.adyen.com의 고객 영역(Customer Area)에 로그인합니다. 여기에서 전자상거래용 -ECOM으로 끝나는 판매자 계정을 관리합니다. 테스트 환경은 Adyen 문서의 가짜 카드 번호를 사용하여 거래를 시뮬레이션합니다.
예를 들어, Visa 테스트를 위해 CVV 737인 카드 4111 1111 1111 1111을 사용하세요. 대시보드에서 iDEAL 또는 Klarna와 같은 결제 수단을 활성화하세요. 이 단계는 통합이 지역 선호도를 지원하도록 보장합니다.
또한 테스트 환경과 실제 환경을 구별하세요. 테스트 URL은 test.adyen.com을 사용하고, 실제 URL은 [random]-[Company]와 같은 고유한 접두사를 포함합니다. Adyen은 요금 발생을 피하기 위해 테스트 모드에서 시작할 것을 권장합니다.
설정 후, 요청을 인증하기 위한 자격 증명을 얻으세요.
API 자격 증명 및 클라이언트 키를 얻는 방법?
고객 영역(Customer Area)의 개발자(Developers) > API 자격 증명(API credentials)에서 API 키를 생성합니다. ws@Company.[YourCompanyAccount]와 같은 판매자 수준 자격 증명을 선택합니다. 키가 없으면 새 키를 만듭니다.
API 키는 Aq42_...와 유사하며 엔드포인트에 대한 액세스 권한을 부여합니다. Adyen은 이 키를 다시 표시하지 않으므로 안전하게 복사하세요. 다음으로, 클라이언트 측 인증을 위해 동일한 페이지에서 test_ 또는 live_ 접두사가 붙은 클라이언트 키를 생성합니다.
CORS 문제를 방지하려면 http://localhost:8080과 같은 허용된 출처(origin)를 추가합니다. 변경 사항을 저장합니다. 이 키는 서버 측 호출과 Drop-in과 같은 프런트엔드 구성 요소를 활성화합니다.
키는 코드 저장소에 절대 저장하지 말고, 환경 변수나 구성 파일에 저장하세요. Java 앱의 경우, 속성 파일(properties files)을 통해 삽입합니다. 이 방법은 보안을 강화합니다.
자격 증명이 준비되면, 인증을 살펴보세요.
Adyen API의 인증 방법은 무엇인가요?
Adyen은 기본 인증을 위해 API 키를 사용합니다. 서버 측 요청의 경우 X-API-Key 헤더에 키를 포함하세요. 예를 들어:
curl -H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://checkout-test.adyen.com/v68/paymentMethods
클라이언트 측은 Adyen.Web과 같은 라이브러리를 초기화하는 데 클라이언트 키를 사용합니다. 이는 관심사를 분리하여 노출을 줄입니다.
웹훅(Webhooks)은 HMAC 유효성 검사가 필요합니다. Adyen은 HMAC 키로 알림에 서명하며, 라이브러리를 사용하여 이를 확인합니다. 유효하지 않은 서명은 변조를 나타냅니다.
또한 일부 엔드포인트는 OAuth용 Bearer 토큰을 지원하지만, 대부분의 통합에는 API 키로 충분합니다. 전송을 암호화하려면 항상 HTTPS를 사용하세요.
잘못 구성된 인증은 401 오류를 발생시킵니다. 따라서 일찍 자격 증명을 테스트하세요.
이제 핵심 엔드포인트를 살펴보세요.
Adyen API의 주요 엔드포인트 탐색
Adyen API는 기능별로 엔드포인트를 구성합니다. /paymentMethods 엔드포인트는 위치 및 통화에 따라 사용 가능한 결제 수단을 검색합니다. merchantAccount를 포함하여 POST 요청을 보내세요:
{
"merchantAccount": "YOUR_MERCHANT_ACCOUNT"
}
응답은 카드 또는 iDEAL과 같은 결제 수단을 나열합니다.
/payments 엔드포인트는 거래를 시작합니다. 금액(amount), 결제 수단(paymentMethod) 및 참조(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"
}
성공적인 응답에는 Authorised와 같은 resultCode가 포함됩니다.
자세한 내용을 보려면 /payments/details를 사용하여 3DS 결과와 같은 추가 데이터를 제출하세요.
/recurring과 같은 Recurring API 엔드포인트는 저장된 자격 증명을 처리합니다. Payouts API는 자금 이체를 관리합니다.
Apidog는 컬렉션 가져오기를 통해 이러한 기능을 쉽게 탐색할 수 있도록 하며, 매개변수 조정 및 응답 유효성 검사를 허용합니다.
구현으로 전환하기 위해 다음 단계를 따르세요.
단계별 가이드: Adyen API를 애플리케이션에 통합하기
개발자는 서버 측 및 클라이언트 측 구성 요소를 사용하여 Adyen API를 통합합니다. Java Spring Boot와 같은 백엔드 프레임워크로 시작하세요.
먼저 Adyen 라이브러리를 추가합니다. build.gradle에:
implementation 'com.adyen:adyen-java-api-library:31.3.0'
클라이언트를 구성합니다:
Config config = new Config();
config.setApiKey("YOUR_API_KEY");
config.setEnvironment(Environment.TEST);
Client client = new Client(config);
PaymentsApi paymentsApi = new PaymentsApi(client);
프런트엔드에서 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">
결제 수단을 가져옵니다:
async function getPaymentMethods() {
const response = await fetch('/api/paymentMethods', { method: 'POST' });
return await response.json();
}
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');
결제의 경우, 백엔드 엔드포인트를 생성합니다:
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);
browserInfo 및 origin을 추가하여 3D Secure를 처리합니다. action.type이 redirect인 경우, 사용자를 리디렉션합니다.
웹훅(webhooks)의 경우, POST를 수신할 엔드포인트를 설정합니다. HMAC를 검증합니다:
HMACValidator hmacValidator = new HMACValidator();
if (hmacValidator.validateHMAC(notificationItem, "YOUR_HMAC_KEY")) {
// Process event
}
대시보드에서 특정 결제 수단을 활성화합니다. iDEAL의 경우:
paymentMethod에 발행자(issuer) 선택을 추가합니다.
Klarna의 경우, lineItems를 포함합니다:
"lineItems": [
{
"description": "Item",
"quantity": 1,
"amountIncludingTax": 1000
}
]
Adyen의 카드 확장 프로그램 또는 수동 입력을 사용하여 테스트합니다.
이 통합은 기본 흐름을 지원합니다. 토큰화를 위해 확장하세요: /payments를 사용하여 세부 정보를 저장하고 storeDetails: true로 설정합니다.
선승인(Preauthorization)은 나중에 /captures를 통해 처리됩니다.
Apidog는 응답을 모의 테스트하고 예외 케이스를 테스트하여 도움을 줍니다.
Adyen API 테스트를 위해 Apidog를 사용하는 방법?
Apidog는 Adyen API 테스트를 간소화합니다. 무료 버전을 다운로드하고 Adyen 컬렉션을 가져오세요.
예를 들어, /adjustAuthorisation에 대한 cURL을 붙여넣으세요:
Apidog는 이를 파싱하여 필드를 채웁니다. 응답을 보려면 전송하세요.
테스트 흐름: 승인(Authorize) 후 캡처(capture). 상태 코드에 대한 어설션(assertion)을 사용하세요.
Apidog는 엔드포인트를 모의 테스트하여 지연 또는 오류를 시뮬레이션합니다. 자동 실행을 위해 CI/CD와 통합하세요.
Adyen의 경우, 요청을 연결하여 3DS와 같은 보안을 검증합니다.
또한 스펙에서 문서를 생성하여 팀과 공유하세요.
이 도구는 수동 작업을 줄이고 문제를 조기에 발견합니다.
Adyen API 사용을 위한 모범 사례
중복을 방지하기 위해 멱등성(idempotency) 키를 구현하세요: RequestOptions에 UUID를 설정합니다.
클라이언트 측 보안을 위해 세션 흐름을 사용하고, 서버 측에서 세션을 생성합니다.
웹훅(webhooks)으로 성능을 모니터링하고 이벤트를 로깅합니다.
민감한 데이터 저장을 피하여 PCI DSS를 준수합니다.
일괄 결제(payouts)를 통해 확장합니다.
또한 기능을 위해 라이브러리를 정기적으로 업데이트하세요.
일반적인 문제 및 문제 해결
401 권한 없음: API 키를 확인하세요.
잘못된 HMAC: 키가 일치하는지 확인하세요.
거부된 결제: 테스트 카드를 올바르게 사용하세요.
CORS 오류: 출처(origins)를 추가하세요.
고객 영역(Customer Area)에서 로그를 참조하세요.
고급 기능: 3D Secure, 웹훅 및 기타
동적 3DS 활성화: attemptAuthentication: always로 설정합니다.
웹훅(Webhooks)은 비동기적으로 알림을 보냅니다—AUTHORISATION 이벤트를 처리하세요.
플랫폼의 경우, /transfers를 사용합니다.
수수료를 위해 BinLookup을 통합합니다.
Apidog는 시나리오를 통해 이를 테스트합니다.
결론
이제 Adyen API에 효과적으로 액세스하고 사용하는 방법을 알게 되었습니다. 설정부터 고급 통합까지, 이 가이드는 개발자들에게 필요한 지식을 제공합니다. 테스트 모드에서 실험한 다음 실제 환경으로 전환하세요. Apidog와 같은 도구는 이 과정을 가속화합니다.