Checkout icon

Secure communication for agentic payments

Secure your API requests for agentic payments with JSON Web Signature (JWS) and JSON Web Encryption (JWE).

View source

To improve the security of your API request for agentic commerce, add message-level encryption (MLE). For the request to share the shopper's payment credentials with Adyen, you sign the JSON payload with JSON Web Signature (JWS) and encrypt the payload with JSON Web Encryption (JWE).

If your integration uses the Agentic Commerce Protocol (ACP), we recommend that you use HMAC-SHA256 signatures (sign the Timestamp and the payload) instead. ACP supports this natively.

If you do this, the instructions for JWS and JWE do not apply to you.

Requirements

Requirement Description
Integration type Make sure that you have one of the following agent platform integrations with Adyen:
User role Make sure that your Adyen credential (API key) has the following user role:
  • Agentic Commerce
Key pairs An RSA key pair for JWS signing (PS512). Keep the private key secure on your platform. Adyen provides the encryption certificate (X.509). Do not reuse keys across integrations.
Setup steps Before you begin, reach out to your Adyen Account Manager or our Support Team for the following:
  • Enable message-level encryption for your account.

How it works

MLE provides additional security when your agent platform makes an API request to share payment credentials with Adyen. You sign and encrypt the request payload before sending it to Adyen. Adyen decrypts and verifies the payload, then processes the request.

You must do the following when you make the request to share payment credentials:

  1. Sign the raw JSON payload with your private key to create a JWS token.
  2. Encrypt the JWS token with the Adyen public key to create a JWE token.
  3. Send the JWE token as the request body with Content-Type: application/jose.
  4. Adyen decrypts the JWE token, verifies the JWS signature, and processes the request.

The response format is the same as for standard requests to the endpoint.

Configure your keys

Configure the cryptographic keys that you use for signing and encryption:

  1. In your Customer Area, go to Developers > API credentials.
  2. Select the API credential for your agentic commerce integration.
  3. In the JWS public key field, paste your public signing key. Adyen uses this key to verify your request signatures.

  4. In the Client side encryption section, select download X509 Certificate. You use this certificate to encrypt the payload.

    Do not reuse this certificate for other integrations.

Implement MLE in your request

The maximum request body size is 1 MB. Using unsupported algorithms results in an HTTP 401 Unauthorized error.

The endpoint for the request to share the shopper's payment creditials depends on the protocol your integration uses:

Protocol Endpoint
UCP https://commerce-suite-test.adyen.com/commerce-suite/ucp/v1/handler/tokenize
ACP https://pal-test.adyen.com/paltokenization/servlet/Recurring/Agentic/acp/v1/agentic_commerce/delegate_payment

To share payment credentials with MLE, do the following:

  1. Sign the JSON payload.

    Create a JWS with the PS512 (RSA_PSS_USING_SHA512) algorithm and your private signing key. The input is your raw JSON request body.

    You get a string that represents the JWS. This is your signed payload.

  2. Encrypt the signed payload.

    Create a JWE with the Adyen CSE public key from the X.509 certificate that you downloaded. Use the following:

    • Key encryption: RSA-OAEP-256
    • Content encryption: A256GCM

    You get an encrypted JWE payload.

  3. In the request to tokenize (UCP) or delegate payment (ACP), include the following:

    Header:

    Parameter Required Value
    Content-Type Required application/jose
    Authorization Required Bearer <YOUR_AGENTIC_TOKEN>

    Body:

    Body Required Value
    Request body Required The encrypted JWE payload.