You can use JSON Web Encryption (JWE) to encrypt your shopper's card details when implementing your own UI. With JWE, you use a third-party JWT library and an Adyen-provided encryption key to encrypt card details from your shopper's device.
Requirements
Before you begin, take into account the following requirements, limitations, and preparations.
Requirement | Description |
---|---|
Integration type | Make sure you have an API only integration for Web. |
API credential roles | Make sure that you have the following role:
|
Customer Area roles | Make sure that you have the Manage API credentials role. |
Limitations | Make sure to check your PCI DSS requirements in the PCI DSS compliance guide. |
Setup steps | Before you begin:
|
JSON Web Encryption (JWE)
We offer multiple ways for you to accept card payments for different use cases and different PCI compliance levels. Card detail encryption with JWE is for when you want to have access to the unencrypted card details from your frontend, for example when:
- Offering card payments with Adyen in a multiple-payment-service-provider setup.
- Running payments through your own risk engine.
In a JWE setup, you use a third-party JWT library to encrypt card details as a JSON Web Token. The encrypted details can be safely passed to your server, where can use them for a /payments request. We never share decryption keys, so once you encrypt card details only Adyen can decrypt them to process your payment.
JWE supports multiple algorithms for encryption (enc
) and securing the JSON Web Signature (alg
). In our integration guide, we advise you use specific algorithms that meet our security standards.
How it works
Encrypting card details using JWE involves the following:
- You download your merchant account-specific X.509 certificate from the Customer Area.
- You compute your JSON Web Key (JWK) from your X.509 certificate.
- Your shopper enters their card details in your checkout.
- You encrypt the card details on the client side using your JWK key.
- You pass the encrypted card details to your server.
- You make a /payments request using the encrypted card details.
Get your X.509 certificate
Before you encrypt card details with JWE, get your X.509 Certificate:
- In your Customer Area, go to Developers > API credentials.
- Select the relevant API credential.
- From the Client side encryption section, under X509 Certificate, select Download.
Compute your JWK
Then, use your X509 Certificate to compute your JWK.
-
Install and import a third-party Javascript JWT library, for example JavaScript Object Signing and Encryption (JOSE).
The following instructions use the JavaScript (JOSE) library.
-
Assign the content of the X.509 Certificate to a variable.
-
Create a public key from your X.509 certificate.
Encrypt card details
When making a payment, use the encryption key to encrypt card details.
-
Create an object to encrypt.
- Card details to encrypt go by keys
cvc
,number
,expiryMonth
, andexpiryYear
. Go to paymentMethod and select CardDetails to learn about the card detail parameters. generationtime
is a string representing the JavaScript date object, based on ISO 8601.
- Card details to encrypt go by keys
-
Encrypt the card detail object.
-
Pass the encrypted object (
jwe
) to your server. Include thejwe
object when you make a /payments request.