Adyen APIは、世界中の企業の決済処理を強化し、開発者がオンライン、モバイル、対面のチャネルにわたって取引を処理できるようにします。エンジニアはこのAPIを統合して、150以上の通貨で250以上の決済方法をサポートし、高い承認率と堅牢な不正防止を実現しています。安全な決済システムを構築する上で、テストを簡素化するツールは不可欠になります。
この記事では、Adyen APIへのアクセスと使用に関する技術的な解説を提供します。開発者は通常、基本的な設定から始めて高度な機能へと進むため、このガイドもその順序に従っています。まず基本を理解し、次に実践的な実装に移りましょう。
Adyen APIとは？
Adyen APIは、決済ゲートウェイのための統一インターフェースとして機能し、アプリケーションが安全に取引を処理できるようにします。このプラットフォームは、仲介業者を介さずにカードネットワークや現地の決済方法に直接接続します。この直接接続により、効率が向上し、コストが削減されます。
Adyenは、オンライン決済用のCheckout、サブスクリプション用のRecurring、資金移動用のPayouts、POS端末用のIn-Person Paymentsなど、いくつかのAPIカテゴリを提供しています。さらに、Platforms APIはマーケットプレイスソリューションをサポートし、BinLookupは手数料計算と3Dセキュアチェックに役立ちます。
エンジニアは、JSON形式のリクエストを使用して、RESTfulエンドポイントを介してこれらにアクセスします。例えば、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機能は、機械学習を使用して不正行為を検出し、正当な支払いを承認しながらチャージバックを最小限に抑えます。
さらに、Adyenはインテリジェントルーティングにより収益を最適化し、失敗した承認を自動的に再試行します。これにより、成功率が最大5%向上します。マーケットプレイスの場合、MarketPayは規制に準拠しながら出品者間の資金分割を処理します。
StripeやPayPalのような代替サービスと比較して、Adyenは統一コマース（オンライン決済とオフライン決済を1つの契約の下で組み合わせる）において優れています。開発者は、エンドポイントをインタラクティブにテストできる詳細なドキュメントとAPI Explorerを高く評価しています。
とはいえ、統合には技術的な専門知識が必要です。簡単な設定は数時間で済みますが、カスタムフローには数日かかります。Apidogは、迅速なモックとテストを可能にすることでこのプロセスを強化し、信頼性を確保します。
次に、開始するために環境を設定します。
Adyenテストアカウントのセットアップ方法
実際の資金を使わずに実験するためにテストアカウントを作成します。Adyenのウェブサイトにアクセスし、開発者アカウントにサインアップしてください。会社名や所在地などのビジネス詳細を提供します。Adyenは申請を審査し、通常数日以内に承認します。
承認されたら、ca-test.adyen.comのカスタマーエリアにログインします。ここでは、Eコマース用の「-ECOM」で終わるマーチャントアカウントを管理します。テスト環境では、Adyenのドキュメントにある偽のカード番号を使用して取引をシミュレートします。
例えば、Visaのテストにはカード番号4111 1111 1111 1111とCVV 737を使用します。ダッシュボードでiDEALやKlarnaなどの決済方法を有効にしてください。この手順により、統合が地域ごとの設定をサポートしていることを確認できます。
さらに、テスト環境と本番環境を区別します。テストURLはtest.adyen.comを使用しますが、本番URLは[ランダム]-[会社名]のような一意のプレフィックスを含みます。Adyenは、料金を避けるためにテストモードから開始することを推奨しています。
セットアップ後、リクエストを認証するための認証情報を取得します。
API認証情報とクライアントキーの取得方法
カスタマーエリアの「開発者」>「API認証情報」でAPIキーを生成します。ws@Company.[貴社アカウント]のようなマーチャントレベルの認証情報を選択します。存在しない場合は、新しいキーを作成します。
APIキーはAq42_...のようになり、エンドポイントへのアクセスを許可します。Adyenは再度表示しないため、安全にコピーしてください。次に、同じページでクライアントサイド認証用のクライアントキーを生成します（test_ または live_ のプレフィックスが付きます）。
CORSの問題を防ぐために、http://localhost:8080のような許可されたオリジンを追加します。変更を保存します。これらのキーにより、サーバーサイドの呼び出しやDrop-inのようなフロントエンドコンポーネントが有効になります。
キーは環境変数または設定ファイルに保存し、コードリポジトリには決して保存しないでください。Javaアプリケーションの場合、プロパティファイルを介して注入します。この方法はセキュリティを強化します。
認証情報の準備ができたら、認証について見ていきましょう。
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セキュアを処理します。action.typeがredirectの場合は、ユーザーをリダイレクトします。
Webhooksの場合、POSTを受け取るためのエンドポイントを設定します。HMACを検証します。
HMACValidator hmacValidator = new HMACValidator();
if (hmacValidator.validateHMAC(notificationItem, "YOUR_HMAC_KEY")) {
// Process event
}
ダッシュボードで特定の決済方法を有効にします。iDEALの場合：
paymentMethodに発行者の選択を追加します。
Klarnaの場合、lineItemsを含めます。
"lineItems": [
{
"description": "Item",
"quantity": 1,
"amountIncludingTax": 1000
}
]
Adyenのカード拡張機能または手動入力でテストします。
この統合は基本的なフローをサポートしています。トークン化のために拡張するには、/paymentsを使用して詳細を保存し、storeDetails: trueを設定します。
事前承認は後で/capturesを介してキャプチャされます。
Apidogは、応答のモックやエッジケースのテストによって役立ちます。
Adyen APIのテストにApidogを使用する方法
Adyen APIのテストにApidogを使用する方法ApidogはAdyen APIのテストを効率化します。無料版をダウンロードし、Adyenコレクションをインポートしてください。
例えば、/adjustAuthorisationのcURLを貼り付けます。
Apidogはそれを解析し、フィールドを埋めます。送信して応答を表示します。
テストフロー：承認し、その後キャプチャします。ステータスコードにはアサーションを使用します。
Apidogはエンドポイントをモックし、遅延やエラーをシミュレートします。CI/CDと統合して自動実行します。
Adyenの場合、リクエストを連結して3DSのようなセキュリティを検証します。
さらに、仕様からドキュメントを生成し、チームと共有します。
このツールは手作業を減らし、問題を早期に発見します。
Adyen APIを使用するためのベストプラクティス
Adyen APIを使用するためのベストプラクティス重複を防ぐためにべき等性キーを実装します：RequestOptionsにUUIDを設定します。
クライアントサイドのセキュリティにはセッションフローを使用し、セッションはサーバーサイドで生成します。
Webhooksでパフォーマンスを監視し、イベントをログに記録します。
機密データの保存を避けることでPCI DSSに準拠します。
ペイアウトをバッチ処理することでスケーリングします。
さらに、機能のためにライブラリを定期的に更新します。
一般的な問題とトラブルシューティング
一般的な問題とトラブルシューティング401 Unauthorized: APIキーを確認してください。
Invalid HMAC: キーが一致しているか確認してください。
Refused payments: テストカードを正しく使用してください。
CORSエラー: オリジンを追加してください。
カスタマーエリアのログを参照してください。
高度な機能：3Dセキュア、Webhooksなど
高度な機能：3Dセキュア、Webhooksなど動的3DSを有効にします：attemptAuthentication: always を設定します。
Webhooksは非同期に通知します — AUTHORISATIONイベントを処理します。
プラットフォームの場合、/transfersを使用します。
手数料のためにBinLookupを統合します。
Apidogはシナリオを用いてこれらをテストします。
まとめ
まとめAdyen APIへのアクセス方法と効果的な使用方法を理解できたことでしょう。セットアップから高度な統合まで、このガイドは開発者の皆様を支援します。テストモードで試した後、本番環境に移行してください。Apidogのようなツールはプロセスを加速させます。
ボタン