API integration means you build your own checkout UI and call the Adyen Checkout API directly, without an Adyen UI library. It gives you the most control and carries the highest PCI scope, because you may handle raw card data.
What API Integration is for
This option uses the Advanced flow. Your server makes three Checkout API requests instead of the single request used by the Sessions flow.
/paymentMethods: get the list of payment methods available for the transaction./payments: submit the payment with the shopper's payment details./payments/details: submit the result of any additional action, for example 3D Secure, to get the final outcome.
You render the payment form yourself, so you control the entire shopper experience. See Sessions vs Advanced Flow for how this compares to the session-based integrations.
When to use it
You need full control over the checkout UI that the prebuilt Drop-in and Components do not give you.
You require Advanced flow capabilities, for example changing the order of payment methods per transaction, or inserting your own steps before payment.
If you want lower effort and lower PCI scope, use Drop-in Integration, Components Integration, or Hosted Checkout.
PCI and card data
Because you build the UI, you may handle raw card data, which gives this integration the highest PCI scope. To reduce that scope and meet Adyen's requirements:
Do not send the raw card number (PAN) to Adyen. Encrypt the card details first.
For a custom card UI, encrypt the card details, for example with JSON Web Encryption (JWE), and send the encrypted object to your server, then include it in the
/paymentsrequest. Adyen never shares decryption keys, so only Adyen can decrypt the details.Confirm which PCI DSS requirements apply to your situation. See PCI Considerations.
Code sample
The Advanced flow uses three Checkout API calls. Include your Store ID on every Valpay transaction.
1. Get the payment methods available for the transaction.
POST https://checkout-test.adyen.com/v71/paymentMethods
X-API-Key: YOUR_API_KEY
{
"merchantAccount": "YOUR_MERCHANT_ACCOUNT",
"amount": { "currency": "USD", "value": 1000 },
"countryCode": "US",
"channel": "Web"
}
2. Submit the payment with the encrypted payment details. Card details are encrypted on the client before they reach your server, so you never handle the raw card number. Use Adyen's custom card integration to produce the encrypted fields.
POST https://checkout-test.adyen.com/v71/payments
X-API-Key: YOUR_API_KEY
{
"merchantAccount": "YOUR_MERCHANT_ACCOUNT",
"amount": { "currency": "USD", "value": 1000 },
"reference": "ORDER-12345",
"returnUrl": "https://your-site.com/checkout/return",
"store": "YOUR_STORE_ID",
"paymentMethod": {
"type": "scheme",
"encryptedCardNumber": "...",
"encryptedExpiryMonth": "...",
"encryptedExpiryYear": "...",
"encryptedSecurityCode": "..."
}
}
3. Submit the result of any additional action. If the payment requires an action such as 3D Secure, complete it with the shopper, then send the result.
POST https://checkout-test.adyen.com/v71/payments/details
X-API-Key: YOUR_API_KEY
{
// the action result returned to your returnUrl
"details": { ...action result... }
}
Treat the Adyen webhook, for example an AUTHORISATION notification, as the authoritative result. For the full list of request and response fields, see Adyen's Advanced flow guide and Checkout API reference.
Credentials, your merchant account, and your Store ID are provided securely by Valpay. Contact Valpay Support for credentials or troubleshooting.