Adyen API cung cấp khả năng xử lý thanh toán cho các doanh nghiệp trên toàn thế giới, cho phép các nhà phát triển xử lý giao dịch trên các kênh trực tuyến, di động và tại cửa hàng. Các kỹ sư tích hợp API này để hỗ trợ hơn 250 phương thức thanh toán bằng hơn 150 loại tiền tệ, đảm bảo tỷ lệ ủy quyền cao và khả năng phòng chống gian lận mạnh mẽ. Khi bạn xây dựng các hệ thống thanh toán an toàn, các công cụ đơn giản hóa việc kiểm thử trở nên cần thiết.
Bài viết này cung cấp hướng dẫn kỹ thuật chi tiết về cách truy cập và sử dụng Adyen API. Các nhà phát triển thường bắt đầu với các thiết lập cơ bản và tiến tới các tính năng nâng cao, vì vậy hướng dẫn sẽ đi theo tiến trình đó. Đầu tiên, hãy hiểu các nguyên tắc cơ bản, sau đó chuyển sang triển khai thực tế.
Adyen API là gì?
Adyen API đóng vai trò là một giao diện thống nhất cho các cổng thanh toán, cho phép các ứng dụng xử lý giao dịch một cách an toàn. Nền tảng này kết nối trực tiếp với các mạng thẻ và phương thức thanh toán địa phương, bỏ qua các bên trung gian. Kết nối trực tiếp này giúp tăng hiệu quả và giảm chi phí.
Adyen cung cấp một số danh mục API, bao gồm Checkout cho thanh toán trực tuyến, Recurring cho các gói đăng ký, Payouts cho chuyển tiền và In-Person Payments cho các thiết bị POS. Ngoài ra, Platforms APIs hỗ trợ các giải pháp thị trường, trong khi BinLookup giúp tính phí và kiểm tra 3D Secure.
Các kỹ sư truy cập chúng thông qua các điểm cuối RESTful, với các yêu cầu được định dạng bằng JSON. Ví dụ, Checkout API xử lý việc khởi tạo thanh toán, trong khi Webhooks thông báo cho các hệ thống về sự thay đổi trạng thái. Adyen duy trì khả năng tương thích ngược thông qua việc lập phiên bản, thêm các hậu tố như /v68 vào URL.
Hơn nữa, Adyen cung cấp các thư viện máy khách bằng các ngôn ngữ như Java, Node.js, Python và .NET, đơn giản hóa các lệnh gọi. Các nhà phát triển cài đặt chúng thông qua các trình quản lý gói – ví dụ, sử dụng npm cho thư viện Node.js. Thiết lập này giúp tăng tốc độ phát triển bằng cách trừu tượng hóa các tương tác HTTP cấp thấp.
Tuy nhiên, Adyen API yêu cầu cấu hình phù hợp để hoạt động. Nếu không có thông tin đăng nhập, các yêu cầu sẽ thất bại với lỗi xác thực. Do đó, thiết lập tài khoản là nền tảng.
Tại sao nên chọn Adyen API cho nhu cầu thanh toán của bạn?
Các doanh nghiệp chọn Adyen API vì khả năng mở rộng và phạm vi toàn cầu của nó. Hệ thống này xử lý hàng tỷ giao dịch hàng năm cho các công ty như Uber và eBay. Tính năng RevenueProtect của nó sử dụng học máy để phát hiện gian lận, giảm thiểu các khoản bồi hoàn đồng thời phê duyệt các khoản thanh toán hợp lệ.
Ngoài ra, Adyen tối ưu hóa doanh thu thông qua định tuyến thông minh, tự động thử lại các ủy quyền thất bại. Điều này giúp tăng tỷ lệ thành công lên tới 5%. Đối với các thị trường, MarketPay xử lý việc phân chia quỹ giữa các người bán, tuân thủ các quy định.
So với các lựa chọn thay thế như Stripe hoặc PayPal, Adyen vượt trội trong lĩnh vực thương mại hợp nhất – kết hợp thanh toán trực tuyến và ngoại tuyến theo một hợp đồng duy nhất. Các nhà phát triển đánh giá cao tài liệu chi tiết và API Explorer, cho phép họ kiểm thử các điểm cuối một cách tương tác.
Tuy nhiên, tích hợp đòi hỏi chuyên môn kỹ thuật. Các thiết lập đơn giản mất vài giờ, nhưng các luồng tùy chỉnh cần vài ngày. Apidog tăng cường quá trình này bằng cách cho phép tạo giả lập và kiểm thử nhanh chóng, đảm bảo độ tin cậy.
Tiếp theo, hãy cấu hình môi trường của bạn để bắt đầu.
Làm thế nào để thiết lập tài khoản kiểm thử Adyen?
Bạn tạo tài khoản kiểm thử để thử nghiệm mà không cần tiền thật. Truy cập trang web Adyen và đăng ký tài khoản nhà phát triển. Cung cấp thông tin chi tiết về doanh nghiệp, bao gồm tên công ty và địa điểm. Adyen xem xét các ứng dụng, thường phê duyệt trong vài ngày.
Sau khi được phê duyệt, đăng nhập vào Khu vực khách hàng tại ca-test.adyen.com. Tại đây, bạn quản lý các tài khoản người bán kết thúc bằng -ECOM cho thương mại điện tử. Môi trường kiểm thử mô phỏng các giao dịch, sử dụng số thẻ giả từ tài liệu của Adyen.
Ví dụ, sử dụng thẻ 4111 1111 1111 1111 với CVV 737 cho các kiểm thử Visa. Bật các phương thức thanh toán như iDEAL hoặc Klarna trong bảng điều khiển. Bước này đảm bảo tích hợp của bạn hỗ trợ các tùy chọn khu vực.
Hơn nữa, hãy phân biệt môi trường kiểm thử với môi trường thực. Các URL kiểm thử sử dụng test.adyen.com, trong khi các URL thực bao gồm một tiền tố duy nhất như [random]-[Company]. Adyen khuyên bạn nên bắt đầu ở chế độ kiểm thử để tránh các khoản phí.
Sau khi thiết lập, hãy lấy thông tin xác thực để xác thực các yêu cầu.
Làm thế nào để lấy thông tin xác thực API và khóa máy khách (Client Key)?
Bạn tạo các khóa API trong Khu vực khách hàng dưới phần Developers > API credentials. Chọn một thông tin xác thực cấp người bán, chẳng hạn như ws@Company.[YourCompanyAccount]. Tạo khóa mới nếu chưa có.
Khóa API giống như Aq42_... và cấp quyền truy cập vào các điểm cuối. Sao chép khóa một cách an toàn, vì Adyen sẽ không hiển thị lại nó. Tiếp theo, tạo Khóa máy khách (Client Key) trên cùng trang đó để xác thực phía máy khách, có tiền tố test_ hoặc live_.
Thêm các nguồn gốc được phép, như http://localhost:8080, để ngăn chặn các vấn đề CORS. Lưu các thay đổi. Các khóa này cho phép các cuộc gọi phía máy chủ và các thành phần giao diện người dùng như Drop-in.
Lưu trữ các khóa trong các biến môi trường hoặc tệp cấu hình, không bao giờ trong các kho mã. Đối với các ứng dụng Java, hãy chèn chúng thông qua các tệp thuộc tính. Thực hành này tăng cường bảo mật.
Với thông tin xác thực đã sẵn sàng, hãy khám phá xác thực.
Các phương thức xác thực cho Adyen API là gì?
Adyen sử dụng các khóa API để xác thực cơ bản. Bao gồm khóa trong tiêu đề X-API-Key cho các yêu cầu phía máy chủ. Ví dụ:
curl -H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://checkout-test.adyen.com/v68/paymentMethods
Phía máy khách sử dụng Khóa máy khách (Client Key) để khởi tạo các thư viện như Adyen.Web. Điều này tách biệt các mối quan tâm, giảm thiểu rủi ro.
Webhooks yêu cầu xác thực HMAC. Adyen ký các thông báo bằng khóa HMAC, mà bạn xác minh bằng cách sử dụng các thư viện. Chữ ký không hợp lệ cho thấy đã bị giả mạo.
Ngoài ra, một số điểm cuối hỗ trợ token Bearer cho OAuth, nhưng các khóa API là đủ cho hầu hết các tích hợp. Luôn sử dụng HTTPS để mã hóa truyền dữ liệu.
Cấu hình xác thực sai dẫn đến lỗi 401. Do đó, hãy kiểm thử thông tin xác thực sớm.
Bây giờ, hãy xem xét các điểm cuối cốt lõi.
Khám phá các điểm cuối chính trong Adyen API
Adyen API tổ chức các điểm cuối theo chức năng. Điểm cuối /paymentMethods truy xuất các phương thức có sẵn dựa trên vị trí và tiền tệ. Gửi một yêu cầu POST với merchantAccount:
{
"merchantAccount": "YOUR_MERCHANT_ACCOUNT"
}
Phản hồi liệt kê các phương thức như thẻ hoặc iDEAL.
Điểm cuối /payments khởi tạo các giao dịch. Bao gồm amount, paymentMethod và 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"
}
Các phản hồi thành công bao gồm resultCode như Authorised.
Để biết chi tiết, sử dụng /payments/details để gửi dữ liệu bổ sung, chẳng hạn như kết quả 3DS.
Các điểm cuối API định kỳ như /recurring xử lý thông tin xác thực được lưu trữ. API Payouts quản lý việc chuyển tiền.
Apidog đơn giản hóa việc khám phá những điều này bằng cách nhập các bộ sưu tập, cho phép điều chỉnh tham số và xác thực phản hồi.
Chuyển sang triển khai, hãy làm theo các bước sau.
Hướng dẫn từng bước: Tích hợp Adyen API vào ứng dụng của bạn
Các nhà phát triển tích hợp Adyen API bằng cách sử dụng các thành phần phía máy chủ và phía máy khách. Bắt đầu với một framework backend như Java Spring Boot.
Đầu tiên, thêm thư viện Adyen. Trong build.gradle:
implementation 'com.adyen:adyen-java-api-library:31.3.0'
Cấu hình máy khách:
Config config = new Config();
config.setApiKey("YOUR_API_KEY");
config.setEnvironment(Environment.TEST);
Client client = new Client(config);
PaymentsApi paymentsApi = new PaymentsApi(client);
Trên giao diện người dùng, bao gồm 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">
Tìm nạp các phương thức thanh toán:
async function getPaymentMethods() {
const response = await fetch('/api/paymentMethods', { method: 'POST' });
return await response.json();
}
Khởi tạo Drop-in:
const configuration = {
paymentMethodsResponse: await getPaymentMethods(),
clientKey: "YOUR_CLIENT_KEY",
locale: "en_US",
environment: "test",
onSubmit: (state, dropin) => {
// Xử lý việc gửi
}
};
const checkout = await AdyenCheckout(configuration);
checkout.create('dropin').mount('#dropin-container');
Để thanh toán, tạo một điểm cuối backend:
PaymentRequest paymentRequest = new PaymentRequest();
paymentRequest.merchantAccount("YOUR_MERCHANT_ACCOUNT");
paymentRequest.amount(new Amount().currency("EUR").value(1000L));
// Đặt các trường khác
PaymentResponse response = paymentsApi.payments(paymentRequest);
Xử lý 3D Secure bằng cách thêm browserInfo và origin. Nếu action.type là redirect, chuyển hướng người dùng.
Đối với webhooks, thiết lập một điểm cuối để nhận POST. Xác thực HMAC:
HMACValidator hmacValidator = new HMACValidator();
if (hmacValidator.validateHMAC(notificationItem, "YOUR_HMAC_KEY")) {
// Xử lý sự kiện
}
Bật các phương thức cụ thể trong bảng điều khiển. Đối với iDEAL:
Thêm lựa chọn nhà phát hành trong paymentMethod.
Đối với Klarna, bao gồm lineItems:
"lineItems": [
{
"description": "Mặt hàng",
"quantity": 1,
"amountIncludingTax": 1000
}
]
Kiểm thử bằng tiện ích mở rộng thẻ của Adyen hoặc nhập thủ công.
Tích hợp này hỗ trợ các luồng cơ bản. Mở rộng để mã hóa token (tokenization): Lưu trữ chi tiết bằng /payments, đặt storeDetails: true.
Ủy quyền trước (Preauthorization) sau đó được thu thập qua /captures.
Apidog hỗ trợ bằng cách giả lập các phản hồi, kiểm thử các trường hợp đặc biệt.
Cách sử dụng Apidog để kiểm thử Adyen API?
Apidog hợp lý hóa việc kiểm thử Adyen API. Tải xuống phiên bản miễn phí và nhập bộ sưu tập Adyen.
Ví dụ, dán một lệnh cURL cho /adjustAuthorisation:
Apidog phân tích nó, điền vào các trường. Gửi để xem phản hồi.
Kiểm thử các luồng: Ủy quyền, sau đó thu thập. Sử dụng các khẳng định cho mã trạng thái.
Apidog giả lập các điểm cuối, mô phỏng độ trễ hoặc lỗi. Tích hợp với CI/CD để chạy tự động.
Đối với Adyen, xác thực bảo mật như 3DS bằng cách nối chuỗi các yêu cầu.
Ngoài ra, tạo tài liệu từ các đặc tả kỹ thuật, chia sẻ với các nhóm.
Công cụ này giúp giảm bớt công sức thủ công, phát hiện sớm các vấn đề.
Các phương pháp hay nhất khi sử dụng Adyen API
Thực hiện các khóa tính bất biến (idempotency keys) để ngăn chặn các bản sao: Đặt UUID trong RequestOptions.
Sử dụng luồng phiên (sessions flow) để bảo mật phía máy khách, tạo các phiên phía máy chủ.
Giám sát hiệu suất với webhooks, ghi lại các sự kiện.
Tuân thủ PCI DSS bằng cách tránh lưu trữ dữ liệu nhạy cảm.
Mở rộng quy mô bằng cách nhóm các khoản thanh toán.
Hơn nữa, cập nhật thư viện thường xuyên để có các tính năng mới.
Các vấn đề thường gặp và cách khắc phục sự cố
401 Unauthorized: Kiểm tra khóa API.
HMAC không hợp lệ: Xác minh khóa khớp.
Thanh toán bị từ chối: Sử dụng thẻ kiểm thử đúng cách.
Lỗi CORS: Thêm các nguồn gốc.
Tham khảo nhật ký trong Khu vực khách hàng.
Các tính năng nâng cao: 3D Secure, Webhooks và hơn thế nữa
Bật 3DS động: Đặt attemptAuthentication: always.
Webhooks thông báo không đồng bộ – xử lý các sự kiện AUTHORISATION.
Đối với các nền tảng, sử dụng /transfers.
Tích hợp BinLookup để tính phí.
Apidog kiểm thử những điều này với các kịch bản.
Kết luận
Bạn hiện đã biết cách truy cập và sử dụng Adyen API một cách hiệu quả. Từ thiết lập đến các tích hợp nâng cao, hướng dẫn này trang bị cho các nhà phát triển. Hãy thử nghiệm trong chế độ kiểm thử, sau đó đưa vào hoạt động thực tế. Các công cụ như Apidog giúp tăng tốc quá trình.