Skip to content

Commit f01a5b7

Browse files
gcatanesegemini-code-assist[bot]
gcatanese
and
gemini-code-assist[bot]
authored
Add agents.md (#1566)
* Add agents.md (draft) * Update agents.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Update agents.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Update agents.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Update agents.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Update agents.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Update agents.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Update agents.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Update agents.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Update agents.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Update agents.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
1 parent 37e01ca commit f01a5b7

File tree

1 file changed

+234
-0
lines changed

1 file changed

+234
-0
lines changed

‎agents.md‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# Adyen Java API Library for AI Assistants
2+
3+
This file gives guidance to AI-based coding assistants (like Copilot or ChatGPT) to help developers use the **Adyen Java API Library**.
4+
5+
The goal is to provide **simple, working examples** that help developers quickly get started with setup, making requests, and handling responses.
6+
7+
---
8+
9+
## General Rules
10+
11+
- Always use classes from the `com.adyen` package (not internal or test code).
12+
- Show **minimal, copy-pasteable examples**.
13+
- Use `Environment.TEST` in all examples.
14+
- Get credentials (API key, merchant account) from **environment variables** — never hardcode secrets.
15+
- 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
16+
- If developers need more details, link to:
17+
- [Adyen Java API Library](https://github.com/Adyen/adyen-java-api-library)
18+
- [Adyen API Explorer](https://docs.adyen.com/api-explorer/)
19+
- [Adyen Java Sample Application](https://github.com/adyen-examples/adyen-java-spring-online-payments)
20+
21+
## What is the Adyen Java API Library?
22+
23+
The Adyen Java API Library is a client SDK that allows developers to integrate with Adyen from Java applications. It provides:
24+
25+
- Simplified access to Adyen APIs (Checkout, Terminal API, Platforms and Financial Services).
26+
- Request and response models for all API endpoints, so you don’t have to manually construct JSON.
27+
- Helpers for security and HTTP calls, including setting API keys, idempotency keys, and headers.
28+
- Error handling utilities to manage API exceptions in a structured way.
29+
30+
It supports the following Adyen APIs:
31+
32+
- **Checkout** https://docs.adyen.com/api-explorer/Checkout/latest/overview
33+
- **Terminal API** https://docs.adyen.com/api-explorer/terminal-api/1/overview
34+
- **Management API** https://docs.adyen.com/api-explorer/Management/
35+
- **Legal Entity Management API** https://docs.adyen.com/api-explorer/legalentity/
36+
- **Balance Platform Configuration API** https://docs.adyen.com/api-explorer/balanceplatform/
37+
- **Transfers API** https://docs.adyen.com/api-explorer/transfers/
38+
- **Webhooks** https://docs.adyen.com/api-explorer/Webhooks/1/overview
39+
- **Balance Platform Configuration webhooks** https://docs.adyen.com/api-explorer/balanceplatform-webhooks/
40+
- **Transfers Webhooks** https://docs.adyen.com/api-explorer/transfer-webhooks/
41+
42+
43+
## Installation
44+
45+
Show developers how to add the library:
46+
47+
**Maven**
48+
49+
```xml
50+
51+
<dependency>
52+
<groupId>com.adyen</groupId>
53+
<artifactId>adyen-java-api-library</artifactId>
54+
<version>LATEST_VERSION</version>
55+
</dependency>
56+
```
57+
58+
```gradle
59+
implementation 'com.adyen:adyen-java-api-library:LATEST_VERSION'
60+
61+
```
62+
63+
## Setup
64+
65+
Show developers how to setup the client:
66+
67+
```java
68+
69+
import com.adyen.Client;
70+
import com.adyen.enums.Environment;
71+
import com.adyen.service.checkout.PaymentsApi;
72+
import com.adyen.model.checkout.*;
73+
74+
// Setup Client
75+
Client client = new Client(new Config()
76+
.environment(Environment.TEST)
77+
.apiKey(System.getenv("ADYEN_API_KEY"))
78+
);
79+
80+
// Setup Service
81+
PaymentsApi paymentsApi = new PaymentsApi(client);
82+
```
83+
84+
## Make a payment with Checkout
85+
86+
Show developers how to make a payment with the Checkout API:
87+
88+
```java
89+
90+
import com.adyen.Client;
91+
import com.adyen.Config;
92+
import com.adyen.enums.Environment;
93+
import com.adyen.service.checkout.PaymentsApi;
94+
import com.adyen.model.checkout.*;
95+
96+
// Setup Client
97+
Client client = new Client(new Config()
98+
.environment(Environment.TEST)
99+
.apiKey(System.getenv("ADYEN_API_KEY"))
100+
);
101+
102+
// Setup Service
103+
PaymentsApi paymentsApi = new PaymentsApi(client);
104+
105+
// Create PaymentRequest
106+
CardDetails cardDetails =
107+
new CardDetails()
108+
.type(CardDetails.TypeEnum.SCHEME)
109+
.encryptedCardNumber("5136333333333335")
110+
.holderName("John Doe")
111+
.cvc("737")
112+
.encryptedExpiryMonth("08")
113+
.encryptedExpiryYear("2018");
114+
PaymentRequest paymentRequest =
115+
new PaymentRequest()
116+
.merchantAccount("YOUR_MERCHANT_ACCOUNT")
117+
.reference("YOUR_REFERENCE")
118+
.amount(new Amount()
119+
.currency("EUR")
120+
.value(1000L))
121+
.returnUrl("https://your-company.example.org/checkout?shopperOrder=12xy..")
122+
.paymentMethod(new CheckoutPaymentMethod(cardDetails));
123+
124+
// Make a call to the /payments endpoint
125+
PaymentResponse paymentResponse = paymentsApi.payments(paymentRequest);
126+
```
127+
128+
## Error handling
129+
130+
Show developers how to handle errors: use a try-catch block to handle API errors.
131+
Catch the `ApiException` to inspect the response and handle specific cases:
132+
133+
134+
```java
135+
// Setup Client
136+
Client client = new Client(new Config()
137+
.environment(Environment.TEST)
138+
.apiKey(System.getenv("ADYEN_API_KEY"))
139+
);
140+
141+
142+
// Setup Service
143+
PaymentLinksApi paymentLinksApi = new PaymentLinksApi(client);
144+
145+
// Get Payment link
146+
try {
147+
paymentLinksApi.getPaymentLink("1234");
148+
} catch (ApiException e) {
149+
// Obtain response
150+
int statusCode = e.getStatusCode();
151+
String responseBody = e.getResponseBody();
152+
// Check ApiError object
153+
ApiError apiError = e.getError();
154+
String errorCode = apiError.getErrorCode();
155+
List<com.adyen.model.InvalidField> invalidFields = apiError.getInvalidFields();
156+
}
157+
158+
```
159+
160+
## Webhook processing
161+
162+
Show developers how to handle webhooks:
163+
164+
```java
165+
import java.util.List;
166+
import com.adyen.util.HMACValidator;
167+
import com.adyen.notification.WebhookHandler;
168+
import com.adyen.model.notification.NotificationRequest;
169+
import com.adyen.model.notification.NotificationRequestItem;
170+
171+
String hmacKey = System.getenv("ADYEN_HMAC_KEY");
172+
// The webhook payload
173+
String notificationRequestJson = "NOTIFICATION_REQUEST_JSON";
174+
175+
HMACValidator hmacValidator = new HMACValidator();
176+
177+
WebhookHandler webhookHandler = new WebhookHandler();
178+
NotificationRequest notificationRequest = webhookHandler.handleNotificationJson(notificationRequestJson);
179+
180+
// fetch first (and only) NotificationRequestItem
181+
var notificationRequestItemOptional = notificationRequest.getNotificationItems().stream().findFirst();
182+
183+
if (notificationRequestItemOptional.isPresent()) {
184+
NotificationRequestItem notificationRequestItem = notificationRequestItemOptional.get();
185+
// validate the HMAC signature
186+
if ( hmacValidator.validateHMAC(notificationRequestItem, hmacKey) ) {
187+
// Process the notification based on the eventCode
188+
System.out.printf("Received webhook with event %s : %n" +
189+
"Merchant Reference: %s%n" +
190+
"Alias : %s%n" +
191+
"PSP reference : %s%n",
192+
notificationRequestItem.getEventCode(),
193+
notificationRequestItem.getMerchantReference(),
194+
notificationRequestItem.getAdditionalData().get("alias"),
195+
notificationRequestItem.getPspReference());
196+
} else {
197+
// Non valid NotificationRequest
198+
throw new RuntimeException("Invalid HMAC signature");
199+
}
200+
}
201+
202+
```
203+
204+
## Idempotency key
205+
206+
Show developers how to use an idempotency key:
207+
208+
```java
209+
210+
import java.util.UUID;
211+
import com.adyen.model.checkout.PaymentRequest;
212+
import com.adyen.model.checkout.PaymentResponse;
213+
import com.adyen.RequestOptions;
214+
215+
// Create a PaymentRequest
216+
PaymentRequest paymentRequest = new PaymentRequest();
217+
// ... set amount, merchant account, payment method, etc.
218+
219+
// Generate a random idempotency key
220+
RequestOptions requestOptions = new RequestOptions()
221+
.idempotencyKey(UUID.randomUUID().toString());
222+
223+
// Make the payment request with idempotency
224+
PaymentResponse paymentResponse = paymentsApi.payments(paymentRequest, requestOptions);
225+
226+
System.out.println("Payment response: " + paymentResponse);
227+
228+
```
229+
Notes for developers:
230+
231+
- UUID.randomUUID() generates a random UUID (version 4), suitable for idempotency keys.
232+
- Always use a new key for each logically unique request.
233+
- This is important to prevent duplicate payments if the request is retried due to network issues or timeouts.
234+

0 commit comments

Comments
 (0)