-
Notifications
You must be signed in to change notification settings - Fork 146
Add agents.md #1566
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
Open
Add agents.md #1566
Changes from all commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
899b76c
Add agents.md (draft)
gcatanese a9f1151
Update agents.md
gcatanese e9a6a3d
Update agents.md
gcatanese 57516b7
Update agents.md
gcatanese 6350cf6
Update agents.md
gcatanese 46642f7
Update agents.md
gcatanese 7c235ec
Update agents.md
gcatanese 1409208
Update agents.md
gcatanese 01fb99b
Update agents.md
gcatanese fb18b85
Update agents.md
gcatanese 2232511
Update agents.md
gcatanese File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,234 @@ | ||
| # Adyen Java API Library for AI Assistants | ||
|
|
||
| This file gives guidance to AI-based coding assistants (like Copilot or ChatGPT) to help developers use the **Adyen Java API Library**. | ||
|
|
||
| The goal is to provide **simple, working examples** that help developers quickly get started with setup, making requests, and handling responses. | ||
|
|
||
| --- | ||
|
|
||
| ## General Rules | ||
|
|
||
| - Always use classes from the `com.adyen` package (not internal or test code). | ||
| - Show **minimal, copy-pasteable examples**. | ||
| - Use `Environment.TEST` in all examples. | ||
| - Get credentials (API key, merchant account) from **environment variables** — never hardcode secrets. | ||
| - Generate snippets only looking at this file, the README.md or the unit test source code at https://github.com/Adyen/adyen-java-api-library/tree/main/src/test/java/com/adyen | ||
| - If developers need more details, link to: | ||
| - [Adyen Java API Library](https://github.com/Adyen/adyen-java-api-library) | ||
| - [Adyen API Explorer](https://docs.adyen.com/api-explorer/) | ||
| - [Adyen Java Sample Application](https://github.com/adyen-examples/adyen-java-spring-online-payments) | ||
|
|
||
| ## What is the Adyen Java API Library? | ||
|
|
||
| The Adyen Java API Library is a client SDK that allows developers to integrate with Adyen from Java applications. It provides: | ||
|
|
||
| - Simplified access to Adyen APIs (Checkout, Terminal API, Platforms and Financial Services). | ||
| - Request and response models for all API endpoints, so you don’t have to manually construct JSON. | ||
| - Helpers for security and HTTP calls, including setting API keys, idempotency keys, and headers. | ||
| - Error handling utilities to manage API exceptions in a structured way. | ||
|
|
||
| It supports the following Adyen APIs: | ||
|
|
||
| - **Checkout** https://docs.adyen.com/api-explorer/Checkout/latest/overview | ||
| - **Terminal API** https://docs.adyen.com/api-explorer/terminal-api/1/overview | ||
| - **Management API** https://docs.adyen.com/api-explorer/Management/ | ||
| - **Legal Entity Management API** https://docs.adyen.com/api-explorer/legalentity/ | ||
| - **Balance Platform Configuration API** https://docs.adyen.com/api-explorer/balanceplatform/ | ||
| - **Transfers API** https://docs.adyen.com/api-explorer/transfers/ | ||
| - **Webhooks** https://docs.adyen.com/api-explorer/Webhooks/1/overview | ||
| - **Balance Platform Configuration webhooks** https://docs.adyen.com/api-explorer/balanceplatform-webhooks/ | ||
| - **Transfers Webhooks** https://docs.adyen.com/api-explorer/transfer-webhooks/ | ||
|
|
||
|
|
||
| ## Installation | ||
|
|
||
| Show developers how to add the library: | ||
|
|
||
| **Maven** | ||
|
|
||
| ```xml | ||
|
|
||
| <dependency> | ||
| <groupId>com.adyen</groupId> | ||
| <artifactId>adyen-java-api-library</artifactId> | ||
| <version>LATEST_VERSION</version> | ||
| </dependency> | ||
| ``` | ||
|
|
||
| ```gradle | ||
| implementation 'com.adyen:adyen-java-api-library:LATEST_VERSION' | ||
|
|
||
| ``` | ||
|
|
||
| ## Setup | ||
|
|
||
| Show developers how to setup the client: | ||
|
|
||
| ```java | ||
|
|
||
| import com.adyen.Client; | ||
| import com.adyen.enums.Environment; | ||
| import com.adyen.service.checkout.PaymentsApi; | ||
| import com.adyen.model.checkout.*; | ||
|
|
||
| // Setup Client | ||
| Client client = new Client(new Config() | ||
| .environment(Environment.TEST) | ||
| .apiKey(System.getenv("ADYEN_API_KEY")) | ||
| ); | ||
|
|
||
| // Setup Service | ||
| PaymentsApi paymentsApi = new PaymentsApi(client); | ||
| ``` | ||
|
|
||
| ## Make a payment with Checkout | ||
|
|
||
| Show developers how to make a payment with the Checkout API: | ||
|
|
||
| ```java | ||
|
|
||
| import com.adyen.Client; | ||
| import com.adyen.Config; | ||
| import com.adyen.enums.Environment; | ||
| import com.adyen.service.checkout.PaymentsApi; | ||
| import com.adyen.model.checkout.*; | ||
|
|
||
| // Setup Client | ||
| Client client = new Client(new Config() | ||
| .environment(Environment.TEST) | ||
| .apiKey(System.getenv("ADYEN_API_KEY")) | ||
| ); | ||
|
|
||
| // Setup Service | ||
| PaymentsApi paymentsApi = new PaymentsApi(client); | ||
|
|
||
| // Create PaymentRequest | ||
| CardDetails cardDetails = | ||
| new CardDetails() | ||
| .type(CardDetails.TypeEnum.SCHEME) | ||
| .encryptedCardNumber("5136333333333335") | ||
| .holderName("John Doe") | ||
| .cvc("737") | ||
| .encryptedExpiryMonth("08") | ||
| .encryptedExpiryYear("2018"); | ||
| PaymentRequest paymentRequest = | ||
| new PaymentRequest() | ||
| .merchantAccount("YOUR_MERCHANT_ACCOUNT") | ||
| .reference("YOUR_REFERENCE") | ||
| .amount(new Amount() | ||
| .currency("EUR") | ||
| .value(1000L)) | ||
| .returnUrl("https://your-company.example.org/checkout?shopperOrder=12xy..") | ||
| .paymentMethod(new CheckoutPaymentMethod(cardDetails)); | ||
|
|
||
| // Make a call to the /payments endpoint | ||
| PaymentResponse paymentResponse = paymentsApi.payments(paymentRequest); | ||
| ``` | ||
|
|
||
| ## Error handling | ||
|
|
||
| Show developers how to handle errors: use a try-catch block to handle API errors. | ||
| Catch the `ApiException` to inspect the response and handle specific cases: | ||
|
|
||
|
|
||
| ```java | ||
| // Setup Client | ||
| Client client = new Client(new Config() | ||
| .environment(Environment.TEST) | ||
| .apiKey(System.getenv("ADYEN_API_KEY")) | ||
| ); | ||
|
|
||
|
|
||
| // Setup Service | ||
| PaymentLinksApi paymentLinksApi = new PaymentLinksApi(client); | ||
|
|
||
| // Get Payment link | ||
| try { | ||
| paymentLinksApi.getPaymentLink("1234"); | ||
| } catch (ApiException e) { | ||
| // Obtain response | ||
| int statusCode = e.getStatusCode(); | ||
| String responseBody = e.getResponseBody(); | ||
| // Check ApiError object | ||
| ApiError apiError = e.getError(); | ||
| String errorCode = apiError.getErrorCode(); | ||
| List<com.adyen.model.InvalidField> invalidFields = apiError.getInvalidFields(); | ||
| } | ||
|
|
||
| ``` | ||
|
|
||
| ## Webhook processing | ||
|
|
||
| Show developers how to handle webhooks: | ||
|
|
||
| ```java | ||
| import java.util.List; | ||
| import com.adyen.util.HMACValidator; | ||
| import com.adyen.notification.WebhookHandler; | ||
| import com.adyen.model.notification.NotificationRequest; | ||
| import com.adyen.model.notification.NotificationRequestItem; | ||
|
|
||
| String hmacKey = System.getenv("ADYEN_HMAC_KEY"); | ||
| // The webhook payload | ||
| String notificationRequestJson = "NOTIFICATION_REQUEST_JSON"; | ||
|
|
||
| HMACValidator hmacValidator = new HMACValidator(); | ||
|
|
||
| WebhookHandler webhookHandler = new WebhookHandler(); | ||
| NotificationRequest notificationRequest = webhookHandler.handleNotificationJson(notificationRequestJson); | ||
|
|
||
| // fetch first (and only) NotificationRequestItem | ||
| var notificationRequestItemOptional = notificationRequest.getNotificationItems().stream().findFirst(); | ||
|
|
||
| if (notificationRequestItemOptional.isPresent()) { | ||
| NotificationRequestItem notificationRequestItem = notificationRequestItemOptional.get(); | ||
| // validate the HMAC signature | ||
| if ( hmacValidator.validateHMAC(notificationRequestItem, hmacKey) ) { | ||
| // Process the notification based on the eventCode | ||
| System.out.printf("Received webhook with event %s : %n" + | ||
| "Merchant Reference: %s%n" + | ||
| "Alias : %s%n" + | ||
| "PSP reference : %s%n", | ||
| notificationRequestItem.getEventCode(), | ||
| notificationRequestItem.getMerchantReference(), | ||
| notificationRequestItem.getAdditionalData().get("alias"), | ||
| notificationRequestItem.getPspReference()); | ||
| } else { | ||
| // Non valid NotificationRequest | ||
| throw new RuntimeException("Invalid HMAC signature"); | ||
| } | ||
| } | ||
|
|
||
| ``` | ||
|
|
||
| ## Idempotency key | ||
|
|
||
| Show developers how to use an idempotency key: | ||
|
|
||
| ```java | ||
|
|
||
| import java.util.UUID; | ||
| import com.adyen.model.checkout.PaymentRequest; | ||
| import com.adyen.model.checkout.PaymentResponse; | ||
| import com.adyen.RequestOptions; | ||
|
|
||
| // Create a PaymentRequest | ||
| PaymentRequest paymentRequest = new PaymentRequest(); | ||
| // ... set amount, merchant account, payment method, etc. | ||
|
|
||
| // Generate a random idempotency key | ||
| RequestOptions requestOptions = new RequestOptions() | ||
| .idempotencyKey(UUID.randomUUID().toString()); | ||
|
|
||
| // Make the payment request with idempotency | ||
| PaymentResponse paymentResponse = paymentsApi.payments(paymentRequest, requestOptions); | ||
|
|
||
| System.out.println("Payment response: " + paymentResponse); | ||
|
|
||
| ``` | ||
| Notes for developers: | ||
|
|
||
| - UUID.randomUUID() generates a random UUID (version 4), suitable for idempotency keys. | ||
| - Always use a new key for each logically unique request. | ||
| - This is important to prevent duplicate payments if the request is retried due to network issues or timeouts. | ||
|
|
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.