1. Prerequisites
Access to an Adyen merchant account
Store ID provided by ValPay/Adyen (required for all transactions)
API credentials (API key, merchant account, client key)
Ability to make HTTP requests from your backend
Ability to serve static files and run JavaScript on your frontend
2. Configuration
Store your Adyen API key, merchant account, client key, and Store ID securely (e.g., environment variables or a secure vault). Depending on your setup and use case you might have multiple Merchant Accounts and Store IDs to manage.
Example configuration (pseudocode):
ADYEN_API_KEY = "your-adyen-api-key"
MERCHANT_ACCOUNT = "your-merchant-account"
CLIENT_KEY = "your-client-key"
STORE_ID = "your-store-id" # Obtain from ValPay/Adyen
RETURN_URL = "https://yourdomain.com/checkout/return"
3. Risk Flag Handling
Test Environment:
Set the risk flag to OFF to avoid unnecessary declines during testing.
Production Environment:
Set the risk flag to ON to enable fraud checks.
How to set (pseudocode):
if ENVIRONMENT == "production":
riskFlag = true
else:
riskFlag = false
The risk flag is typically included in the payment session creation payload as:
`additionalData["riskdata.skipRisk"] = "true"`
(for skipping risk in test)
4. Create a Payment Session (Backend)
To use the Web Drop-in, you must first create a payment session on your backend by calling Adyen's `/sessions` endpoint.
Sample pseudocode:
headers = {
"X-API-Key": ADYEN_API_KEY
}
body = {
"merchantAccount": MERCHANT_ACCOUNT,
"amount": {"currency": "USD", "value": 1000},
"reference": "YOUR_ORDER_REFERENCE",
"returnUrl": RETURN_URL,
"countryCode": "US",
"channel": "Web",
"shopperInteraction": "Ecommerce",
"shopperLocale": "en-US",
"store": STORE_ID,
// Only for test: skip risk if needed
"additionalData": riskFlag ? null : { "riskdata.skipRisk": "true" }
}
response = http_post("https://checkout-test.adyen.com/v71/sessions", headers, body)
sessionId = response["id"]
sessionData = response["sessionData"]
Important:
Always include the Store ID.
Set `riskdata.skipRisk` to `true` in test, omit or set to `false` in production.
Use the correct endpoint for test (`checkout-test.adyen.com`) and production (`checkout-live.adyen.com`).
5. Frontend: Mounting the Web Drop-in
On your frontend, use Adyen's Web Drop-in JavaScript SDK. You will need the `clientKey` and the session object returned from your backend.
Include Adyen's SDK:
html
<link rel="stylesheet" href="https://checkoutshopper-test.adyen.com/checkoutshopper/sdk/5.x.x/adyen.css" />
<script src="https://checkoutshopper-test.adyen.com/checkoutshopper/sdk/5.x.x/adyen.js"></script>
Mount the Drop-in (pseudocode):
js
const checkout = await AdyenCheckout({
environment: 'test', // or 'live' for production
clientKey: 'YOUR_CLIENT_KEY',
session: {
id: 'SESSION_ID_FROM_BACKEND',
sessionData: 'SESSION_DATA_FROM_BACKEND'
},
paymentMethodsConfiguration: {
card: {
hasHolderName: true, // Show cardholder name field
holderNameRequired: true, // Make cardholder name required
billingAddressRequired: true // Show and require billing address
}
// Add other payment method configs as needed
},
onPaymentCompleted: (result) => { /* handle success */ },
onError: (error) => { /* handle error */ }
});
checkout.create('dropin').mount('#dropin-container');
Field options for card payments:
- `hasHolderName`: Show/hide the cardholder name field
- `holderNameRequired`: Make cardholder name required (only applies if `hasHolderName` is true)
- `billingAddressRequired`: Show/require billing address fields
6. Testing
Use Adyen's test card numbers and scenarios to validate your integration: https://docs.adyen.com/development-resources/test-cards/test-card-numbers/
Ensure the risk flag is OFF in test and ON in production.
Verify that Store ID is always included in requests.
7. Go Live Checklist
Switch to production API keys, client key, and endpoints.
Set the risk flag to ON (do not skip risk).
Double-check Store ID and merchant account values.
Secure all credentials.
8. Additional Notes
Never expose API keys or sensitive data in client-side code (only client key is safe for frontend).
More information about Sessions and Drop-In can be found in Adyen’s site https://docs.adyen.com/online-payments/build-your-integration/sessions-flow/?integration=Drop-in&platform=Web&version=6.28.0
Refer to Adyen's official documentation (https://docs.adyen.com/ ) for up-to-date API details and advanced features.
For ValPay-specific requirements, visit https://intercom.help/valpay-partner/en/ or contact support.
This guide is intended to be adaptable to any programming language or framework. Adjust code samples as needed for your environment.