Skip to content

Commit b82ed02

Browse files
gnongsiegnongsie
authored
Merge pull request #196 from CyberSource/release/15-MAY-2026
Automated release commit on 15-MAY-2026
2 parents e2144b0 + 127bf64 commit b82ed02

588 files changed

Lines changed: 51497 additions & 27984 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎MLE.md‎

Lines changed: 66 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,17 @@ MLE supports both **Request Encryption** (encrypting outgoing request payloads)
1111
- **Request MLE**: Only supported with `JWT (JSON Web Token)` authentication type
1212
- **Response MLE**: Only supported with `JWT (JSON Web Token)` authentication type
1313

14+
### MLE with JWT Key Types
15+
16+
MLE works with both JWT key types:
17+
18+
| JWT Key Type | MLE Support | Request MLE Certificate Source |
19+
|---|---|---|
20+
| `P12` (default) | Supported | Auto-extracted from the P12 file (using `requestMleKeyAlias`), or from a separate file via `mleForRequestPublicCertPath` |
21+
| `SHARED_SECRET` | Supported | **Must** be provided via `mleForRequestPublicCertPath` (since there is no P12 file to extract from) |
22+
23+
> **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)).
24+
1425
<br/>
1526

1627
## Configuration
@@ -292,6 +303,58 @@ var merchantConfig = {
292303
};
293304
```
294305

306+
### (ix) Request MLE with Shared Secret (JWT Symmetric Key) Authentication
307+
308+
```javascript
309+
// MLE with JWT SHARED_SECRET authentication — requires mleForRequestPublicCertPath
310+
var merchantConfig = {
311+
// JWT authentication with SHARED_SECRET key type
312+
authenticationType: 'jwt',
313+
jwtKeyType: 'SHARED_SECRET',
314+
merchantID: 'your_merchant_id',
315+
runEnvironment: 'apitest.cybersource.com',
316+
merchantKeyId: 'your_key_id',
317+
merchantsecretKey: 'your_base64_encoded_shared_secret',
318+
319+
// Request MLE settings
320+
enableRequestMLEForOptionalApisGlobally: true,
321+
// mleForRequestPublicCertPath is REQUIRED for SHARED_SECRET since there is no P12 file
322+
mleForRequestPublicCertPath: '/path/to/mle/public/cert.pem',
323+
requestMleKeyAlias: 'CyberSource_SJC_US' // Optional, defaults to CyberSource_SJC_US
324+
};
325+
```
326+
327+
> **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)).
328+
329+
### (x) Response MLE with MetaKey
330+
331+
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.
332+
333+
```javascript
334+
// MetaKey + Response MLE — portfolio's response MLE key is required
335+
var merchantConfig = {
336+
// JWT authentication with MetaKey
337+
authenticationType: 'jwt',
338+
jwtKeyType: 'SHARED_SECRET',
339+
merchantID: 'your_transacting_merchant_id',
340+
merchantKeyId: 'your_metakey_portfolio_KeyId',
341+
merchantsecretKey: 'your_metakey_portfolio_shared_secret_key',
342+
portfolioID: 'your_portfolio_id',
343+
useMetaKey: true,
344+
runEnvironment: 'apitest.cybersource.com',
345+
346+
// Response MLE — use the portfolio's response MLE key, not the transacting merchant's
347+
enableResponseMleGlobally: true,
348+
responseMlePrivateKeyFilePath: '/path/to/portfolio/response/mle/private/key.p12',
349+
responseMlePrivateKeyFilePassword: 'portfolio_private_key_password'
350+
// responseMleKID is optional when using a CyberSource-generated P12 file (auto-fetched from P12)
351+
// Required when using PEM files or responseMlePrivateKey object
352+
// responseMleKID: 'your_portfolio_response_mle_kid'
353+
};
354+
```
355+
356+
> **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.
357+
295358
<br/>
296359

297360
## 5. Common Pitfalls
@@ -612,7 +675,8 @@ For Response MLE private key files, the following formats are supported:
612675
- If `enableRequestMLEForOptionalApisGlobally` is set to `true`, it enables request MLE for all APIs that have optional MLE support
613676
- APIs with mandatory MLE requirements are enabled by default unless `disableRequestMLEForMandatoryApisGlobally` is set to `true`
614677
- If `mapToControlMLEonAPI` doesn't contain a specific API, the global setting applies
615-
- For HTTP Signature authentication, request MLE will fall back to non-encrypted requests with a warning
678+
- 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.
679+
- 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.
616680

617681
### (ii) Response MLE
618682
- Response MLE requires either `responseMlePrivateKey` object OR `responseMlePrivateKeyFilePath` (not both)
@@ -622,6 +686,7 @@ For Response MLE private key files, the following formats are supported:
622686
- **Required** when using PEM format files (`.pem`, `.key`, `.p8`)
623687
- **Required** when using `responseMlePrivateKey` object directly
624688
- When both auto-fetched and user-provided values exist, the user-provided value takes precedence
689+
- **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.
625690
- If an API expects a mandatory MLE response but the map specifies non-MLE response, the API might return an error
626691
- Both the private key object and file path approaches are mutually exclusive
627692

‎README.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,130 @@ Follow the first step mentioned in [Getting Started with CyberSource REST SDKs](
2525

2626
Follow the second step mentioned in [Getting Started with CyberSource REST SDKs](https://developer.cybersource.com/hello-world/rest-api-sdks.html#gettingstarted) to configure the SDK by inputting your credentials.
2727

28+
> **⚠️ HTTP Signature Deprecation Notice:** HTTP Signature authentication is being deprecated. **JWT with Shared Secret** 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.
29+
30+
## Authentication Configuration
31+
32+
To set your API credentials for an API request, configure the following information in your configuration object:
33+
34+
### For HTTP Signature authentication (⚠️ Deprecated — migrate to JWT with Shared Secret)
35+
36+
```javascript
37+
var merchantConfig = {
38+
authenticationType: 'http_signature',
39+
merchantID: 'testrest',
40+
runEnvironment: 'apitest.cybersource.com',
41+
merchantKeyId: 'your_merchant_key_id',
42+
merchantsecretKey: 'your_merchant_secret_key',
43+
enableLog: true,
44+
logDirectory: './log',
45+
logFilename: 'cybs'
46+
};
47+
```
48+
49+
### For JWT authentication (with P12 certificate)
50+
51+
```javascript
52+
var merchantConfig = {
53+
authenticationType: 'jwt',
54+
merchantID: 'testrest',
55+
runEnvironment: 'apitest.cybersource.com',
56+
keyAlias: 'testrest',
57+
keyPass: 'testrest',
58+
keyFileName: 'testrest',
59+
keysDirectory: './resource',
60+
enableLog: true,
61+
logDirectory: './log',
62+
logFilename: 'cybs'
63+
};
64+
```
65+
66+
### For JWT authentication with Shared Secret (Recommended migration from HTTP Signature)
67+
68+
Uses the **same** `merchantKeyId` and `merchantsecretKey` credentials as HTTP Signature. Only two properties change:
69+
70+
```javascript
71+
var merchantConfig = {
72+
authenticationType: 'jwt',
73+
jwtKeyType: 'SHARED_SECRET',
74+
merchantID: 'testrest',
75+
runEnvironment: 'apitest.cybersource.com',
76+
merchantKeyId: 'your_merchant_key_id',
77+
merchantsecretKey: 'your_merchant_secret_key',
78+
enableLog: true,
79+
logDirectory: './log',
80+
logFilename: 'cybs'
81+
};
82+
```
83+
84+
### For using MetaKey
85+
86+
MetaKey can be used for HTTP Signature, JWT (P12), and JWT with Shared Secret authentication.
87+
88+
#### For HTTP Signature Authentication (⚠️ Deprecated)
89+
90+
```javascript
91+
var merchantConfig = {
92+
authenticationType: 'http_signature',
93+
merchantID: '<transacting merchantID>',
94+
merchantKeyId: '<MetaKey Portfolio KeyId>',
95+
merchantsecretKey: '<MetaKey Portfolio Shared Secret Key>',
96+
useMetaKey: true,
97+
portfolioID: '<Portfolio ID>'
98+
};
99+
```
100+
101+
#### For JWT Authentication (P12)
102+
103+
```javascript
104+
var merchantConfig = {
105+
authenticationType: 'jwt',
106+
merchantID: '<transacting merchantID>',
107+
keyAlias: '<Portfolio ID>',
108+
keyPass: '<MetaKey Portfolio P12 File Password>',
109+
keyFileName: '<MetaKey Portfolio P12 File Name>',
110+
keysDirectory: '<keysDirectory>',
111+
useMetaKey: true
112+
};
113+
```
114+
115+
#### For JWT Authentication with Shared Secret (Recommended)
116+
117+
```javascript
118+
var merchantConfig = {
119+
authenticationType: 'jwt',
120+
jwtKeyType: 'SHARED_SECRET',
121+
merchantID: '<transacting merchantID>',
122+
merchantKeyId: '<MetaKey Portfolio KeyId>',
123+
merchantsecretKey: '<MetaKey Portfolio Shared Secret Key>',
124+
useMetaKey: true,
125+
portfolioID: '<Portfolio ID>'
126+
};
127+
```
128+
129+
#### Response MLE with MetaKey
130+
131+
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:
132+
133+
- `responseMlePrivateKeyFilePath` (or the `responseMlePrivateKey` object) must point to the **portfolio's** response MLE private key.
134+
- `responseMleKID` — the KID value associated with the **portfolio's** response MLE certificate.
135+
- **Optional** when `responseMlePrivateKeyFilePath` points to a CyberSource-generated P12 file (SDK auto-fetches from P12).
136+
- **Required** when using PEM format files (`.pem`, `.key`, `.p8`) or when providing `responseMlePrivateKey` object directly.
137+
138+
```javascript
139+
var merchantConfig = {
140+
// ... other MetaKey configuration ...
141+
enableResponseMleGlobally: true,
142+
responseMlePrivateKeyFilePath: '/path/to/portfolio/response/mle/private/key.p12',
143+
responseMlePrivateKeyFilePassword: 'portfolio_private_key_password'
144+
// responseMleKID is optional when using a CyberSource-generated P12 file (auto-fetched from P12)
145+
// Required when using PEM files or responseMlePrivateKey object
146+
// responseMleKID: '<Portfolio Response MLE KID>'
147+
};
148+
```
149+
150+
> **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.
151+
28152
## How to Use
29153

30154
To get started using this SDK, it's highly recommended to download our sample code repository:

‎docs/AccountValidationsRequest.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,6 @@ Name | Type | Description | Notes
66
**clientReferenceInformation** | [**Bavsv1accountvalidationsClientReferenceInformation**](Bavsv1accountvalidationsClientReferenceInformation.md) | | [optional]
77
**processingInformation** | [**Bavsv1accountvalidationsProcessingInformation**](Bavsv1accountvalidationsProcessingInformation.md) | |
88
**paymentInformation** | [**Bavsv1accountvalidationsPaymentInformation**](Bavsv1accountvalidationsPaymentInformation.md) | |
9+
**tokenInformation** | [**Bavsv1accountvalidationsTokenInformation**](Bavsv1accountvalidationsTokenInformation.md) | | [optional]
910

1011

‎docs/Acpv1mppcredentialsChallenge.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# CyberSource.Acpv1mppcredentialsChallenge
2+
3+
## Properties
4+
Name | Type | Description | Notes
5+
------------ | ------------- | ------------- | -------------
6+
**id** | **String** | Unique challenge identifier issued by the merchant server. |
7+
**realm** | **String** | Merchant realm (typically the API domain). |
8+
**amount** | **String** | Amount in the smallest currency unit (e.g., '4999' = $49.99). |
9+
**currency** | **String** | Three-letter ISO 4217 currency code, lowercase (e.g., 'usd'). |
10+
**acceptedNetworks** | **[String]** | Card networks accepted by the merchant (e.g., ['visa', 'mastercard']). |
11+
**merchantId** | **String** | Merchant identifier (maps to 'recipient' in MPP spec request object). |
12+
**merchantName** | **String** | Human-readable merchant name. |
13+
**encryptionJwk** | [**Acpv1mppcredentialsChallengeEncryptionJwk**](Acpv1mppcredentialsChallengeEncryptionJwk.md) | |
14+
15+

‎docs/Acpv1mppcredentialsChallengeEncryptionJwk.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# CyberSource.Acpv1mppcredentialsChallengeEncryptionJwk
2+
3+
## Properties
4+
Name | Type | Description | Notes
5+
------------ | ------------- | ------------- | -------------
6+
**kty** | **String** | Key type. MUST be 'RSA'. |
7+
**kid** | **String** | Key ID. Identifies the key within a JWKS. |
8+
**use** | **String** | Public key use. MUST be 'enc'. |
9+
**alg** | **String** | Algorithm. MUST be 'RSA-OAEP-256'. |
10+
**n** | **String** | RSA modulus (Base64urlUInt-encoded per RFC 7518 Section 6.3.1.1). |
11+
**e** | **String** | RSA public exponent (Base64urlUInt-encoded per RFC 7518 Section 6.3.1.2). |
12+
13+

‎docs/Acpv1tokensAssuranceData.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,12 @@
33
## Properties
44
Name | Type | Description | Notes
55
------------ | ------------- | ------------- | -------------
6-
**verificationType** | **String** | Type of the verification data. Possible values: - `CARDHOLDER` (Default) - `DEVICE` | [optional]
7-
**verificationEntity** | **String** | Entity performing the verification. Possible value: - `10` - VISA (Default) | [optional]
8-
**verificationEvents** | **[String]** | Event where the verification occurred. Possible values: - `01` - Payment transaction - `02` - Add card/Card enrollment - `03` - Profile access - `04` - Account verification | [optional]
9-
**verificationMethod** | **String** | Method of the verification. Possible values: - `02` - App-based authentication - `04` - One-time passcode - `21` - Visa Token Service step-up: Device binding - `22` - Visa Token Service step-up: Cardholder verification - `23` - FIDO2 |
10-
**verificationResults** | **String** | Result of the verification. Possible values: - `01` - Verified - `02` - Not Verified - `03` - Not performed - `04` - Not required - `21` - Not allowed |
11-
**verificationTimestamp** | **String** | Date and time the verification occurred. UTC time in Unix epoch format. |
6+
**verificationType** | **String** | Optional. Type of the verification data. Possible values: - `CARDHOLDER` (Default) - `DEVICE` | [optional]
7+
**verificationEntity** | **String** | Optional. Entity performing the verification. Possible value: - `10` - VISA (Default) | [optional]
8+
**verificationEvents** | **[String]** | Optional. Event where the verification occurred. Possible values: - `01` - Payment transaction - `02` - Add card/Card enrollment - `03` - Profile access - `04` - Account verification | [optional]
9+
**verificationMethod** | **String** | Required. Method of the verification. Possible values: - `02` - App-based authentication - `04` - One-time passcode - `21` - Visa Token Service step-up: Device binding - `22` - Visa Token Service step-up: Cardholder verification - `23` - FIDO2 |
10+
**verificationResults** | **String** | Required. Result of the verification. Possible values: - `01` - Verified - `02` - Not Verified - `03` - Not performed - `04` - Not required - `21` - Not allowed |
11+
**verificationTimestamp** | **String** | Required. Date and time the verification occurred. UTC time in Unix epoch format. |
1212
**authenticationContext** | [**Acpv1tokensAuthenticationContext**](Acpv1tokensAuthenticationContext.md) | | [optional]
1313
**authenticatedIdentities** | [**Acpv1tokensAuthenticatedIdentities**](Acpv1tokensAuthenticatedIdentities.md) | | [optional]
1414
**additionalData** | **String** | Additional data related to assurance. | [optional]

‎docs/AuthReversalRequest.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Name | Type | Description | Notes
99
**orderInformation** | [**Ptsv2paymentsidreversalsOrderInformation**](Ptsv2paymentsidreversalsOrderInformation.md) | | [optional]
1010
**pointOfSaleInformation** | [**Ptsv2paymentsidreversalsPointOfSaleInformation**](Ptsv2paymentsidreversalsPointOfSaleInformation.md) | | [optional]
1111
**paymentInformation** | [**Ptsv2paymentsidreversalsPaymentInformation**](Ptsv2paymentsidreversalsPaymentInformation.md) | | [optional]
12+
**deviceInformation** | [**Ptsv2paymentsidreversalsDeviceInformation**](Ptsv2paymentsidreversalsDeviceInformation.md) | | [optional]
1213
**processorInformation** | [**Ptsv2paymentsProcessorInformationReversal**](Ptsv2paymentsProcessorInformationReversal.md) | | [optional]
1314

1415

‎docs/BatchesApi.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -153,7 +153,7 @@ No authorization required
153153
### HTTP request headers
154154

155155
- **Content-Type**: application/json;charset=utf-8
156-
- **Accept**: application/json;charset=utf-8
156+
- **Accept**: application/json, application/json;charset=utf-8
157157

158158
<a name="postBatch"></a>
159159
# **postBatch**

‎docs/Bavsv1accountvalidationsPaymentInformation.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33
## Properties
44
Name | Type | Description | Notes
55
------------ | ------------- | ------------- | -------------
6-
**bank** | [**Bavsv1accountvalidationsPaymentInformationBank**](Bavsv1accountvalidationsPaymentInformationBank.md) | |
6+
**customer** | [**Bavsv1accountvalidationsPaymentInformationCustomer**](Bavsv1accountvalidationsPaymentInformationCustomer.md) | | [optional]
7+
**paymentInstrument** | [**Bavsv1accountvalidationsPaymentInformationPaymentInstrument**](Bavsv1accountvalidationsPaymentInformationPaymentInstrument.md) | | [optional]
8+
**instrumentIdentifier** | [**Bavsv1accountvalidationsPaymentInformationInstrumentIdentifier**](Bavsv1accountvalidationsPaymentInformationInstrumentIdentifier.md) | | [optional]
9+
**bank** | [**Bavsv1accountvalidationsPaymentInformationBank**](Bavsv1accountvalidationsPaymentInformationBank.md) | | [optional]
710

811

‎docs/Bavsv1accountvalidationsPaymentInformationBank.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
## Properties
44
Name | Type | Description | Notes
55
------------ | ------------- | ------------- | -------------
6-
**routingNumber** | **String** | Bank routing number. This is also called the transit number. Non-Negative Integer |
6+
**routingNumber** | **String** | Bank routing number. This is also called the transit number. Non-Negative String, containing only digits. |
77
**account** | [**Bavsv1accountvalidationsPaymentInformationBankAccount**](Bavsv1accountvalidationsPaymentInformationBankAccount.md) | |
88

99

0 commit comments

Comments
 (0)