Migrating to Microform v2 for PCI DSS 4.0.1 Compliance
Microform V1 and V0.11 UPDATES TO MEET PCI DSS 4.0.1 REQUIREMENTS
KA-07550
212
06/26/2026 16:33 PM
3.0
Migrating to Microform v2 for PCI DSS 4.0.1 Compliance
Introduction
This article provides internal support guidance for clients migrating from any legacy version of Microform (v0.4 and lower, v0.11, or v1) to Microform v2. The upgrade aligns Microform with Payment Card Industry Data Security Standard (PCI DSS) 4.0.1, specifically requirement 6.4.3, which strengthens script integrity controls for payment pages. This update is designed to improve security for payment card transactions, safeguard sensitive information, maintain trust in electronic payment systems, and reduce the likelihood of a data breach.
Use this article when supporting merchants or developer integrations that currently rely on a legacy Microform version and need to upgrade to remain PCI DSS compliant. The content covers compliance deadlines, server-side and client-side migration steps, transient token handling, use case scenarios, legacy SDK guidance, and answers to common client questions.
⚠ Compliance Deadlines: Clients using any legacy version of Microform must upgrade to Microform v2 before August 31, 2026 to remain PCI DSS compliant. Microform v1 and lower will reach end of life on January 31, 2027, after which existing legacy integrations will no longer function.
Comprehensive Overview
Microform v2 introduces several core changes that clients must implement during migration:
- Updated server-side capture context request requiring
clientVersionandallowedCardNetworks. - A new endpoint for capture context generation (
/microform/v2/sessions). - Dynamic loading of the Microform JavaScript library using Subresource Integrity (SRI) values returned in the capture context.
- A new transient token response format that supports card detection and multiple detected card types.
- Replacement of permanent tokens with transient tokens, regardless of whether secure storage or Token Management Service (TMS) is used.
- Support for both Primary Account Number (PAN) and/or Card Verification Number (CVN).
- Use of the transient token in a call to the Payments API to create the payment and payment credentials in one authorization with
TOKEN_CREATE.
Identifying the Current Microform Version
Use the following indicators to determine which Microform version a client is using:
| Version | How to Identify |
|---|---|
| Microform v0.4 (and lower) | The version is specified in the Flex Microform JS script tag, e.g.,<script src="https://flex.cybersource.com/cybersource/assets/microform/0.4/flex-microform.min.js"></script> |
| Microform v0.11 | The transient token response returns "type": "mf-0.11.0". |
| Microform v1 | The Generate Capture Context request includes "clientVersion": "v1". The transient token response returns "type": "mf-1.0.0". |
| Microform v2 | The Generate Capture Context request includes "clientVersion": "v2" along with allowedCardNetworks. The transient token response returns "type": "mf-2.0.0". |
Migration Procedure
Step 1: Generating the Server-Side Capture Context
a. A new endpoint must be used for capture context generation.
| Environment | Legacy Endpoint (v0.4 and lower) | Microform v2 Endpoint |
|---|---|---|
| Test | POST: https://apitest.cybersource.com/flex/v1/keys | POST: https://apitest.cybersource.com/microform/v2/sessions |
| Production | POST: https://api.cybersource.com/flex/v1/keys | POST: https://api.cybersource.com/microform/v2/sessions |
b. Update the request body. With legacy versions of Microform, the request contained only the encryptionType and targetOrigin. With Microform v2, the request must include an array of target origins, at least one accepted card network, and the clientVersion.
| Current Integration (Legacy Microform) | After Migration to Microform v2 |
|---|---|
{ "targetOrigins": ["https://www.test.com"] } | { "clientVersion": "v2", "targetOrigins": [ "https://www.test.com" ], "allowedCardNetworks": [ "VISA", "MAESTRO", "MASTERCARD", "AMEX", "DISCOVER", "DINERSCLUB", "JCB", "CUP", "CARTESBANCAIRES" ] } |
c. Validate the capture context, then pass the capture context response data object to the front-end application.
Step 2: Validating the Capture Context
a. Pass the key ID (kid) (obtained from the capture context header) as a path parameter, and send a GET request to the /public-keys endpoint:
- Test: https://apitest.cybersource.com/flex/v2/public-keys/{kid}
- Production: https://api.cybersource.com/flex/v2/public-keys/{kid}
b. The resource returns the public key. Use this public RSA key to validate the capture context.
c. Pass the capture context response data object to the front-end application.
Step 3: Setting Up the Client Side
a. Add the Microform JavaScript library to the page by dynamically loading it on the front-end.
b. Decode the JSON Web Token (JWT) from the /sessions response (capture context).
c. Use the clientLibrary and clientLibraryIntegrity values from the decoded JWT to construct the script tag. Generate these values for every transaction, as they can be unique per transaction.
d. Do not hard code the clientLibrary or clientLibraryIntegrity values. Hard coding these values can cause Microform front-end errors.
| Integration Version | Script Tag |
|---|---|
| Microform v0.4 | <script src="https://flex.cybersource.com/cybersource/assets/microform/0.4/flex-microform.min.js"></script> |
| Microform v0.11 | <script src="https://flex.cybersource.com/cybersource/assets/microform/0.11/flex-microform.min.js"></script> |
| Microform v1 | <script src="https://flex.cybersource.com/cybersource/microform/bundle/v1/flex-microform.min.js"></script> |
| Microform v2 | <script src="[Insert clientLibrary value here]" integrity="[Insert clientLibraryIntegrity value here]" crossorigin="anonymous"></script> |
e. Create the HTML placeholder objects to attach to the microforms. Within the HTML checkout, replace the payment card tag with a simple container. Do the same for the CVN (which would not have existed with Microform v0.4 or lower). Microform Integration uses the container to render an iframe for secured credit card input.
f. Invoke the Flex SDK by passing the capture context generated in the previous step to the microform object:
const flex = new Flex(captureContext);
g. Initiate the microform object with styling to match the web page.
h. After creating a new Flex object, begin creating the Microform. Pass baseline styles and ensure the button matches the merchant page:
const microform = flex.microform({ styles: myStyles });
i. Create and attach the microform fields to the HTML objects through the Microform Integration JavaScript library.
j. Create a function for the customer to submit their payment information and invoke the tokenization request to Microform Integration for the transient token.
Step 4: Validating the Transient Token
| Current Integration (Legacy Microform) | After Migration to Microform v2 |
|---|---|
| Request a permanent token and validate its integrity using the public key. | Request a transient token and validate its integrity using the public key embedded within the capture context created at the beginning of this flow. This verifies that Cybersource issued the token and that no data tampering occurred during transit. |
Use the capture context public key to cryptographically validate the JWT provided from a successful microform.createToken call. After validating the transient token, it can be used in place of the PAN with payment services for 15 minutes.
Step 5: Handling the Updated Transient Token Response
Microform v2 includes card detection support and identifies the card type upon entry. Consequently, the transient token response format has changed to accommodate multiple card types. Review the detectedCardTypes array in the response. The format supports multiple card types so clients can choose which detected types to process.
| Current Integration (Legacy Microform) | After Migration to Microform v2 |
|---|---|
{ "jti": "408H4LHTRUSHXQZWLKDIN22ROVXJFLU6VLU00ZWL8PYJOZQWGPS9CUWNASNR59K4", "iat": 1558612859, "exp": 1558613759, "data": { "number": "444433XXXXXX1111", "type": "001", "expirationMonth": "06", "expirationYear": "2025" } } | { "iss": "Flex/08", "exp": 1730827036, "type": "mf-2.0.0", "iat": 1730826137, "jti": "1C4ROM9R1WRA63HXOZN6EM5MPZMP7D96TLET7ZVIF2YXP877FGTL672A531CB95B", "content": { "paymentInformation": { "card": { "expirationYear": { "value": "2025" }, "number": { "detectedCardTypes": [ "001", "036" ], "maskedValue": "XXXXXXXXXXXX1111", "bin": "411111" }, "securityCode": {}, "expirationMonth": { "value": "12" } } } } } |
Step 6: Using the Transient Token by Use Case
With the transient token ready, determine the next steps based on the specific use case.
Use Case One: Guest Checkout with One-Time Payment
Description: A consumer makes a one-time purchase without creating an account or saving any payment details for future use.
Process:
- Provide payment information during checkout and authorize the payment for immediate processing.
- Do NOT store payment details for future use after the transaction.
| Current Integration (Legacy Microform) | After Migration to Microform v2 |
|---|---|
| A permanent token is generated during guest checkout. This token should be removed, as payment details are not being saved for future use. | Payments are processed with a transient token that expires in 15 minutes, eliminating the need for permanent token deletion in guest checkout or one-time purchases. |
Use Case Two: Initial Payment with Account Creation at Checkout
Description: The consumer purchases an item and creates an account as part of the checkout process, saving payment details for future use.
Process:
- Provide payment information during checkout and authorize the payment immediately.
- Store payment details for future use as part of account creation.
| Current Integration (Legacy Microform) | After Migration to Microform v2 |
|---|---|
| A permanent token is automatically created during checkout to process the payment and store payment details for future use. | The payment is processed using a transient token that expires after 15 minutes. To retain the payment details for future use, a permanent token must be generated. Use the transient token to make a call to the Payments API to create both the payment and the payment credentials simultaneously under the authorization with TOKEN_CREATE. |
Note: Ensure bot detection is in place and that the number of cards that can be linked to the consumer’s account is restricted to protect against card enumeration attacks.
Use Case Three: Subscription Payments (MIT after initial CIT)
Description: A customer signs up for a subscription service, agreeing to recurring payments (e.g., monthly or annually).
Process:
- Initial Payment: The customer initiates the first transaction by entering payment details and consenting to recurring charges. This initial transaction is a Customer-Initiated Transaction (CIT).
- Recurring Payments: All subsequent charges are processed automatically by the merchant at scheduled intervals without requiring customer interaction (Merchant-Initiated Transactions / MIT).
| Current Integration (Legacy Microform) | After Migration to Microform v2 |
|---|---|
| A permanent token is automatically created during checkout to process the payment and store payment details for future use. | The payment is processed using a transient token that expires after 15 minutes. To retain the payment details for future use, a permanent token must be generated. Use the transient token to make a call to the Payments API to create both the payment and the payment credentials simultaneously under the authorization with TOKEN_CREATE. |
Note: Ensure bot detection is in place and that the number of cards that can be linked to the consumer’s account is restricted to protect against card enumeration attacks.
Use Case Four: Stored Payment Method for Future Purchases (MIT)
Description: The customer saves payment details for "1-click" future purchase or easy reordering during account creation.
Process:
- Initial Setup: During account creation, the consumer authorizes the merchant to save payment method information for future use with a $0 authorization.
- Future Payments: The merchant uses the stored payment method to process transactions in situations like automatic replenishment or "1-click" purchases, often without requiring the customer to re-enter details.
| Current Integration (Legacy Microform) | After Migration to Microform v2 |
|---|---|
| A permanent token is automatically created during checkout to process the payment and store payment details for future use. | The payment is processed using a transient token that expires after 15 minutes. To retain the payment details for future use, a permanent token must be generated. Use the transient token to make a call to the Payments API to create both the payment and the payment credentials simultaneously under the authorization with TOKEN_CREATE. |
Note: Ensure bot detection is in place and that the number of cards that can be linked to the consumer’s account is restricted to protect against card enumeration attacks.
Guidance for Legacy Cybersource SDK Users
For clients using a legacy version of the Cybersource SDK for server-side setup, follow Step 1 above for generating the server-side capture context. It is recommended to stop using the following legacy Cybersource SDKs:
- Maven Central:
com.github.javadev:flex-server-sdk @cybersource/flex-sdk-node– npm- NuGet Gallery:
CyberSource.Flex.Server 0.2.2
Potential Client Questions and Resolutions
What is PCI DSS?
PCI DSS is a widely accepted set of policies and procedures intended to optimize the security of credit, debit, and cash card transactions. Refer the client to the official PCI Security Standards documentation for the full v4.0.1 standard.
How do I know what version of Microform I am using?
For Microform v0.4 and lower, the version is specified in the Flex Microform JS script tag (e.g., https://flex.cybersource.com/cybersource/assets/microform/0.4/flex-microform.min.js). For v0.11, v1, and v2, check the clientVersion field in the Generate Capture Context request and the type property in the transient token response. Microform v0.11 returns mf-0.11.0, Microform v1 returns mf-1.0.0, and Microform v2 returns mf-2.0.0.
If I am currently using Microform v1 or lower, can I continue to use this version and remain PCI DSS compliant?
No. Integrations on Microform v1 or lower cannot use the SRI value feature and will no longer be PCI DSS compliant from August 31, 2026. Migration to Microform v2 is required to use the SRI value and remain compliant. Microform v1 and lower will be deprecated and reach end of life on January 31, 2027, after which integrations using v0.4 or lower, v0.11, or v1 will stop working.
What types of transactions does this impact?
This change impacts all transactions processed through Microform.
Is this a backwards breaking change?
Existing Microform integrations will continue to function as normal until end of life. However, to remain PCI DSS compliant, clients must upgrade to Microform v2 by August 31, 2026. Microform v1 and lower will be deprecated and reach end of life on January 31, 2027. Regardless of the current version, all clients must update how they load the Microform JavaScript library by dynamically loading it on the front-end, decoding the JWT from the /sessions response, and using the clientLibrary and clientLibraryIntegrity values to create script tags. These values must be generated for every transaction (as they can be unique per transaction) and must NOT be hard coded, since hard coding can lead to Microform front-end errors.
What actions should I take if I am using one of the legacy Cybersource SDKs for server-side setup?
If using a legacy version of the Cybersource SDK, follow Step 1 above for generating the server-side capture context. It is recommended to stop using the legacy Cybersource SDKs (com.github.javadev:flex-server-sdk on Maven Central, @cybersource/flex-sdk-node on npm, and CyberSource.Flex.Server 0.2.2 on NuGet Gallery).
Additional Resources
Was this article helpful?