Automated release commit on 15-MAY-2026

Author: aastgoel

MLE.md

@@ -11,6 +11,17 @@ MLE supports both **Request Encryption** (encrypting outgoing request payloads)
 - **Request MLE**: Only supported with `JWT (JSON Web Token)` authentication type
 - **Response MLE**: Only supported with `JWT (JSON Web Token)` authentication type
 
+### MLE with JWT Key Types
+
+MLE works with both JWT key types:
+
+| JWT Key Type | MLE Support | Request MLE Certificate Source |
+|---|---|---|
+| `P12` (default) | Supported | Auto-extracted from the P12 file (using `requestMleKeyAlias`), or from a separate file via `mleForRequestPublicCertPath` |
+| `SHARED_SECRET` | Supported | **Must** be provided via `mleForRequestPublicCertPath` (since there is no P12 file to extract from) |
+
+> **Important:** When using `jwtKeyType=SHARED_SECRET` with MLE, the `mleForRequestPublicCertPath` property is **required** for request MLE. The SDK cannot auto-extract the MLE certificate from a P12 file because shared secret authentication does not use one. The request MLE public certificate can be downloaded from the CyberSource Business Center ([Test](https://businesscentertest.cybersource.com/ebc2) | [Production](https://businesscenter.cybersource.com/ebc2)).
+
 <br/>
 
 ## Configuration
@@ -300,6 +311,58 @@ $merchantConfig->setRequestMleKeyAlias('New_Alias');
 $merchantConfig->setMleKeyAlias('Old_Alias');  // This delegates to setRequestMleKeyAlias, both will have value 'Old_Alias'
 ```
 
+### (ix) Request MLE with Shared Secret (JWT Symmetric Key) Authentication
+
+```php
+// MLE with JWT SHARED_SECRET authentication — requires mleForRequestPublicCertPath
+$merchantConfig = new MerchantConfiguration();
+
+// JWT authentication with SHARED_SECRET key type
+$merchantConfig->setAuthenticationType('JWT');
+$merchantConfig->setMerchantID('your_merchant_id');
+$merchantConfig->setRunEnvironment('apitest.cybersource.com');
+$merchantConfig->setJwtKeyType('SHARED_SECRET');
+$merchantConfig->setApiKeyID('your_key_id');
+$merchantConfig->setSecretKey('your_base64_encoded_shared_secret');
+
+// Request MLE settings
+$merchantConfig->setEnableRequestMLEForOptionalApisGlobally(true);
+// mleForRequestPublicCertPath is REQUIRED for SHARED_SECRET since there is no P12 file
+$merchantConfig->setMleForRequestPublicCertPath('/path/to/mle/public/cert.pem');
+$merchantConfig->setRequestMleKeyAlias('CyberSource_SJC_US');  // Optional, defaults to CyberSource_SJC_US
+```
+
+> **Note:** When using `jwtKeyType=SHARED_SECRET`, the MLE certificate cannot be auto-extracted from a P12 file. You **must** provide the certificate via `mleForRequestPublicCertPath`. The request MLE public certificate can be downloaded from the CyberSource Business Center ([Test](https://businesscentertest.cybersource.com/ebc2) | [Production](https://businesscenter.cybersource.com/ebc2)).
+
+### (x) Response MLE with MetaKey
+
+When using MetaKey (`useMetaKey=true`) with Response MLE, the response MLE private key and KID must belong to the **portfolio (parent account)**, not the transacting merchant.
+
+```php
+// MetaKey + Response MLE — portfolio's response MLE key is required
+$merchantConfig = new MerchantConfiguration();
+
+// JWT authentication with MetaKey
+$merchantConfig->setAuthenticationType('JWT');
+$merchantConfig->setJwtKeyType('SHARED_SECRET');
+$merchantConfig->setMerchantID('your_transacting_merchant_id');
+$merchantConfig->setApiKeyID('your_metakey_portfolio_KeyId');
+$merchantConfig->setSecretKey('your_metakey_portfolio_shared_secret_key');
+$merchantConfig->setPortfolioID('your_portfolio_id');
+$merchantConfig->setUseMetaKey(true);
+$merchantConfig->setRunEnvironment('apitest.cybersource.com');
+
+// Response MLE — use the portfolio's response MLE key, not the transacting merchant's
+$merchantConfig->setEnableResponseMleGlobally(true);
+$merchantConfig->setResponseMlePrivateKeyFilePath('/path/to/portfolio/response/mle/private/key.p12');
+$merchantConfig->setResponseMlePrivateKeyFilePassword('portfolio_private_key_password');
+// responseMleKID is optional when using a CyberSource-generated P12 file (auto-fetched from P12)
+// Required when using PEM files or responseMlePrivateKey object
+// $merchantConfig->setResponseMleKID('your_portfolio_response_mle_kid');
+```
+
+> **Important:** In MetaKey mode, the portfolio is the transaction submitter. The response is encrypted using the portfolio's MLE certificate, so the decryption key must also be the portfolio's.
+
 <br/>
 
 ## 5. JSON Configuration Examples
@@ -414,7 +477,8 @@ For Response MLE private key files, the following formats are supported:
 - If `enableRequestMLEForOptionalApisGlobally` is set to `true`, it enables request MLE for all APIs that have optional MLE support
 - APIs with mandatory MLE requirements are enabled by default unless `disableRequestMLEForMandatoryApisGlobally` is set to `true`
 - If `mapToControlMLEonAPI` doesn't contain a specific API, the global setting applies
-- For HTTP Signature authentication, request MLE will fall back to non-encrypted requests with a warning
+- When using `jwtKeyType=SHARED_SECRET`, the `mleForRequestPublicCertPath` parameter is **required** because the SDK cannot auto-extract the MLE certificate from a P12 file. See [Example (ix)](#ix-request-mle-with-shared-secret-jwt-symmetric-key-authentication) for a complete configuration.
+- For HTTP Signature authentication, request MLE will fall back to non-encrypted requests with a warning. **Note:** HTTP Signature is being deprecated — migrate to JWT with Shared Secret (`jwtKeyType=SHARED_SECRET`) to enable full MLE support using the same credentials. See [Example (ix)](#ix-request-mle-with-shared-secret-jwt-symmetric-key-authentication) for details.
 
 ### (ii) Response MLE
 - Response MLE requires either `responseMlePrivateKey` object OR `responseMlePrivateKeyFilePath` (not both)
@@ -423,6 +487,7 @@ For Response MLE private key files, the following formats are supported:
   - **Required** when using PEM format files (`.pem`, `.key`, `.p8`)
   - **Required** when using `responseMlePrivateKey` object directly
   - When both auto-fetched and user-provided values exist, the user-provided value takes precedence
+- **MetaKey (`useMetaKey=true`):** When Response MLE is used with MetaKey, the `responseMlePrivateKeyFilePath` (or `responseMlePrivateKey` object) and `responseMleKID` must belong to the **portfolio (parent account)** — not the transacting merchant. This is because in MetaKey mode the portfolio is the transaction submitter, and the response is encrypted using the portfolio's MLE certificate.
 - If an API expects a mandatory MLE response but the map specifies non-MLE response, the API might return an error
 - Both the private key object and file path approaches are mutually exclusive
 - Password-protected private keys enhance security
@@ -464,6 +529,10 @@ The SDK provides specific error messages for common MLE issues:
 For comprehensive examples and sample implementations, please refer to:
 [CyberSource PHP Sample Code Repository (on GitHub)](https://github.com/CyberSource/cybersource-rest-samples-php/tree/master/Samples/MLEFeature)
 
+For MLE with JWT Shared Secret (HS256) authentication specifically, see:
+- [JWT Shared Secret Auth Samples](https://github.com/CyberSource/cybersource-rest-samples-php/tree/master/Samples/JwtSharedSecretAuth) — includes a payment sample with MLE enabled
+- [JwtSharedSecretConfiguration.php](https://github.com/CyberSource/cybersource-rest-samples-php/tree/master/Resources/JwtSharedSecretConfiguration.php) — configuration with MLE enabled
+
 <br/>
 
 ## 10. Additional Information

README.md

@@ -29,7 +29,7 @@ override the new secure-http default setting)*.
 {
   "require": {
     "php": ">=8.0.0", 
-    "cybersource/rest-client-php": "0.0.72"
+    "cybersource/rest-client-php": "0.0.73"
   }
 }
 ```
@@ -63,6 +63,10 @@ The API Reference Guide provides examples of what information is needed for a pa
 
 To learn more about how to use CyberSource's REST API SDKs, please use [Developer Center REST API SDKs](https://developer.cybersource.com/hello-world/rest-api-sdks.html).
 
+## Security Guidance
+
+* It is strongly recommended to use HTTPS for any proxy servers in your environment to protect secrets during transit.
+
 ### Example using Sample Code Application
 
 * Add the [CyberSource REST client](https://github.com/CyberSource/cybersource-rest-samples-php/blob/ea6dc700c833fc41f493147cdc8f1c4b5616683b/composer.json#L23) as a dependency in your php project.
@@ -107,6 +111,123 @@ This feature provides an implementation of Message Level Encryption (MLE) for AP
 
 More information about this new MLE feature can be found in this file : [MLE.md](MLE.md)
 
+### JWT Authentication with Symmetric Key (Shared Secret / HS256 HMAC-SHA256) Support
+
+[![Generic badge](https://img.shields.io/badge/JWT_SHARED_SECRET-NEW-GREEN.svg)](https://shields.io/)
+
+> **⚠️ HTTP Signature Deprecation Notice:** HTTP Signature authentication (`HTTP_SIGNATURE`) is being deprecated. JWT with Shared Secret (HS256 / HMAC-SHA256) is the **recommended migration path** — it uses the **same** `merchantKeyId` and `merchantsecretKey` credentials, requires only two property changes, and enables MLE (Message Level Encryption) support that HTTP Signature does not provide.
+
+JWT authentication now supports two key types, configurable via the `jwtKeyType` property:
+
+| `jwtKeyType` | Algorithm | Credentials Required |
+|---|---|---|
+| `P12` (default) | RS256 (asymmetric, RSA-SHA256) | `keysDirectory`, `keyFileName`, `keyAlias`, `keyPass` |
+| `SHARED_SECRET` | HS256 (symmetric, HMAC-SHA256) | `merchantKeyId`, `merchantsecretKey` |
+
+The default value is `P12`, which preserves full backward compatibility with existing configurations.
+
+#### Configuration for JWT with P12 (default — no changes needed)
+
+```php
+$config = new CyberSource\Authentication\Core\MerchantConfiguration();
+$config->setAuthenticationType('JWT');
+$config->setMerchantID('your_merchant_id');
+$config->setRunEnvironment('apitest.cybersource.com');
+// jwtKeyType defaults to P12 if omitted
+$config->setKeyAlias('your_merchant_id');
+$config->setKeyPassword('your_merchant_id');
+$config->setKeyFileName('your_merchant_id');
+$config->setKeysDirectory('/path/to/p12/directory');
+```
+
+#### Configuration for JWT with Shared Secret
+
+```php
+$config = new CyberSource\Authentication\Core\MerchantConfiguration();
+$config->setAuthenticationType('JWT');
+$config->setMerchantID('your_merchant_id');
+$config->setRunEnvironment('apitest.cybersource.com');
+$config->setJwtKeyType('SHARED_SECRET');
+$config->setApiKeyID('your_key_id');
+$config->setSecretKey('your_base64_encoded_shared_secret');
+```
+
+> **Note:** When `jwtKeyType` is set to `SHARED_SECRET`, the P12-related properties (`keysDirectory`, `keyFileName`, `keyAlias`, `keyPass`) are not required and will be ignored. Conversely, when using `P12`, the `merchantKeyId` and `merchantsecretKey` properties are not required for JWT authentication.
+
+#### JSON Configuration for JWT with P12
+
+```json
+{
+    "authenticationType": "jwt",
+    "merchantID": "your_merchant_id",
+    "runEnvironment": "apitest.cybersource.com",
+    "keyAlias": "your_merchant_id",
+    "keyPass": "your_merchant_id",
+    "keyFileName": "your_merchant_id",
+    "keysDirectory": "path/to/p12/directory"
+}
+```
+
+#### JSON Configuration for JWT with Shared Secret
+
+```json
+{
+    "authenticationType": "jwt",
+    "merchantID": "your_merchant_id",
+    "runEnvironment": "apitest.cybersource.com",
+    "jwtKeyType": "SHARED_SECRET",
+    "merchantKeyId": "your_key_id",
+    "merchantsecretKey": "your_base64_encoded_shared_secret"
+}
+```
+
+#### Migrating from HTTP Signature to JWT with Shared Secret (HS256 / HMAC-SHA256)
+
+If you are currently using HTTP Signature authentication, migrating to JWT with Shared Secret (symmetric key, HS256 / HMAC-SHA256) requires only **two property changes** — your credentials remain the same:
+
+```php
+// BEFORE (HTTP Signature — deprecated)
+$config->setAuthenticationType('HTTP_SIGNATURE');
+$config->setApiKeyID('your_key_id');
+$config->setSecretKey('your_shared_secret');
+
+// AFTER (JWT with Shared Secret / HS256 HMAC-SHA256 — recommended)
+$config->setAuthenticationType('JWT');                 // changed
+$config->setJwtKeyType('SHARED_SECRET');                // added — uses HS256 (HMAC-SHA256)
+$config->setApiKeyID('your_key_id');                    // same
+$config->setSecretKey('your_shared_secret');             // same
+```
+
+#### Using MLE with Shared Secret Credentials
+
+MLE (Message Level Encryption) is fully supported with the `SHARED_SECRET` key type. This allows merchants who use shared secret credentials (instead of a P12 certificate) to still leverage MLE for secure communication.
+
+When using `jwtKeyType=SHARED_SECRET` with MLE, you must provide the MLE public certificate separately via the `mleForRequestPublicCertPath` property, since there is no P12 file to auto-extract the MLE certificate from. The request MLE public certificate can be downloaded from the CyberSource Business Center:
+
+- **Test**: <https://businesscentertest.cybersource.com/ebc2>
+- **Production**: <https://businesscenter.cybersource.com/ebc2>
+
+```php
+$config = new CyberSource\Authentication\Core\MerchantConfiguration();
+$config->setAuthenticationType('JWT');
+$config->setMerchantID('your_merchant_id');
+$config->setRunEnvironment('apitest.cybersource.com');
+$config->setJwtKeyType('SHARED_SECRET');
+$config->setApiKeyID('your_key_id');
+$config->setSecretKey('your_base64_encoded_shared_secret');
+
+// Request MLE configuration
+$config->setEnableRequestMLEForOptionalApisGlobally(true);
+$config->setMleForRequestPublicCertPath('/path/to/mle/public/cert.pem');
+
+// Response MLE is also supported — see MLE.md for full configuration
+// $config->setEnableResponseMleGlobally(true);
+// $config->setResponseMlePrivateKeyFilePath('/path/to/private/key.p12');
+// $config->setResponseMlePrivateKeyFilePassword('password');
+```
+
+For more details on MLE configuration options (including Response MLE), see [MLE.md](MLE.md).
+
 ### MetaKey Support
 
 A Meta Key is a single key that can be used by one, some, or all merchants (or accounts, if created by a Portfolio user) in the portfolio.
@@ -115,8 +236,100 @@ The Portfolio or Parent Account owns the key and is considered the transaction s
 
 MIDs continue to be able to create keys for themselves, even if a Meta Key is generated.
 
+MetaKey works with all three authentication types: HTTP Signature, JWT (P12), and JWT with Shared Secret.
+
+#### MetaKey with HTTP Signature (⚠️ Deprecated)
+
+```php
+$config->setAuthenticationType('HTTP_SIGNATURE');
+$config->setMerchantID('your_transacting_merchant_id');
+$config->setApiKeyID('your_metakey_portfolio_KeyId');
+$config->setSecretKey('your_metakey_portfolio_shared_secret_key');
+$config->setPortfolioID('your_portfolio_id');
+$config->setUseMetaKey(true);
+```
+
+#### MetaKey with JWT (P12)
+
+```php
+$config->setAuthenticationType('JWT');
+$config->setMerchantID('your_transacting_merchant_id');
+$config->setKeyAlias('your_portfolio_id');
+$config->setKeyPassword('your_metakey_portfolio_p12File_password');
+$config->setKeyFileName('your_metakey_portfolio_p12FileName');
+$config->setKeysDirectory('/path/to/p12/directory');
+$config->setPortfolioID('your_portfolio_id');
+$config->setUseMetaKey(true);
+```
+
+#### MetaKey with JWT Shared Secret (Recommended)
+
+```php
+$config->setAuthenticationType('JWT');
+$config->setJwtKeyType('SHARED_SECRET');
+$config->setMerchantID('your_transacting_merchant_id');
+$config->setApiKeyID('your_metakey_portfolio_KeyId');
+$config->setSecretKey('your_metakey_portfolio_shared_secret_key');
+$config->setPortfolioID('your_portfolio_id');
+$config->setUseMetaKey(true);
+```
+
+> **Note:** MetaKey with JWT Shared Secret uses the same MetaKey credentials as HTTP Signature but authenticates via JWT, enabling MLE support.
+
+#### Response MLE with MetaKey
+
+When Response MLE is enabled (`enableResponseMleGlobally=true`) and MetaKey is in use (`useMetaKey=true`), the Response MLE configuration must use the **portfolio's** response MLE key — not the transacting merchant's. Specifically:
+
+- `responseMlePrivateKeyFilePath` (or the `responseMlePrivateKey` object) must point to the **portfolio's** response MLE private key.
+- `responseMleKID` — the KID value associated with the **portfolio's** response MLE certificate.
+  - **Optional** when `responseMlePrivateKeyFilePath` points to a CyberSource-generated P12 file — the SDK will automatically fetch the KID from the P12 file.
+  - **Required** when using PEM format files (`.pem`, `.key`, `.p8`) or when providing `responseMlePrivateKey` object directly.
+
+```php
+$config = new CyberSource\Authentication\Core\MerchantConfiguration();
+$config->setAuthenticationType('JWT');
+$config->setJwtKeyType('SHARED_SECRET');
+$config->setMerchantID('your_transacting_merchant_id');
+$config->setApiKeyID('your_metakey_portfolio_KeyId');
+$config->setSecretKey('your_metakey_portfolio_shared_secret_key');
+$config->setPortfolioID('your_portfolio_id');
+$config->setUseMetaKey(true);
+$config->setRunEnvironment('apitest.cybersource.com');
+
+// Response MLE — use the portfolio's response MLE key, not the transacting merchant's
+$config->setEnableResponseMleGlobally(true);
+$config->setResponseMlePrivateKeyFilePath('/path/to/portfolio/response/mle/private/key.p12');
+$config->setResponseMlePrivateKeyFilePassword('portfolio_private_key_password');
+// responseMleKID is optional when using a CyberSource-generated P12 file (auto-fetched from P12)
+// Required when using PEM files or responseMlePrivateKey object
+// $config->setResponseMleKID('your_portfolio_response_mle_kid');
+```
+
+> **Important:** The response MLE private key (and KID, if applicable) must belong to the portfolio (parent account), since in MetaKey mode the portfolio is the transaction submitter and the response is encrypted using the portfolio's MLE certificate. See [MLE.md](MLE.md) for full details on when `responseMleKID` is required vs optional.
+
 Further information on MetaKey can be found in [New Business Center User Guide](https://developer.cybersource.com/library/documentation/dev_guides/Business_Center/New_Business_Center_User_Guide.pdf).
 
+### OAuth Support
+
+OAuth enables service providers to securely share access to customer data without sharing password data.
+
+The CyberSource OAuth2.0 Authorization Server (or API Auth Service) will issue access tokens (based on merchant user credentials) to CyberSource or third-party Applications. These applications can access CyberSource APIs on the merchant's behalf, using the access tokens.
+
+During application registration, third-party application developers are issued a `client_id` and optionally a `client_secret` (if they can be considered a confidential client, for example a web application).
+
+These values will be used when the merchant application wants to request an access token and/or a refresh token. This is explained in more detail in [Requesting the Access and Refresh Tokens](https://developer.cybersource.com/api/developer-guides/OAuth/cybs_extend_intro/obtaining_access_refresh_tokens.html).
+
+For more detailed information on OAuth, refer to the documentation at [Cybersource OAuth 2.0](https://developer.cybersource.com/api/developer-guides/OAuth/cybs_extend_intro.html).
+
+In order to use OAuth, set the run environment to OAuth enabled URLs. OAuth only works in these run environments.
+
+```php
+// For TESTING use
+$config->setRunEnvironment('api-matest.cybersource.com');
+// For PRODUCTION use
+// $config->setRunEnvironment('api-ma.cybersource.com');
+```
+
 ## Additional Information
 
 ### PHP_APCU PHP Extension

composer.json

@@ -1,6 +1,6 @@
 {
     "name": "cybersource/rest-client-php",
-    "version": "0.0.72",
+    "version": "0.0.73",
     "description": "Client SDK for CyberSource REST APIs",
     "keywords": [
         "cybersource", "payments", "ecommerce", "merchant", "merchants", "authorize", "visa", "payment", "payment-gateway", "payment-integration", "payment-module", "payment-processing", "payment-service", "payment-methods"