Checkout icon

Card encryption with JWE

Use JWE to encrypt card details for your custom card integration.

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:
  • Checkout webservice role (assigned by default)
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:

  1. You download your merchant account-specific X.509 certificate from the Customer Area.
  2. You compute your JSON Web Key (JWK) from your X.509 certificate.
  3. Your shopper enters their card details in your checkout.
  4. You encrypt the card details on the client side using your JWK key.
  5. You pass the encrypted card details to your server.
  6. 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:

  1. In your Customer Area, go to Developers > API credentials.
  2. Select the relevant API credential.
  3. From the Client side encryption section, under X509 Certificate, select Download.

Compute your JWK

Then, use your X509 Certificate to compute your JWK.

  1. 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.

  2. Assign the content of the X.509 Certificate to a variable.

  3. Create a public key from your X.509 certificate.

Encrypt card details

When making a payment, use the encryption key to encrypt card details.

  1. Create an object to encrypt.

    • Card details to encrypt go by keys cvc, number, expiryMonth, and expiryYear. 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.
  2. Encrypt the card detail object.

  3. Pass the encrypted object (jwe) to your server. Include the jwe object when you make a /payments request.

See also