web
You’re offline. This is a read only version of the page.
close

What can we help you with?

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


6

05/15/2026 17:22 PM

2.0

Migrating to Microform v2 for PCI DSS 4.0.1 Compliance

Introduction

This article provides internal support guidance for clients migrating from Microform v1 or v0.11 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.

Use this article when supporting merchants or developer integrations that currently rely on Microform v1 or v0.11 and need to upgrade to remain PCI DSS compliant. The content covers compliance deadlines, server-side and client-side migration steps, transient token response changes, and answers to common client questions.

⚠ Compliance Deadlines: Clients using Microform v1 or v0.11 must upgrade to Microform v2 before April 1, 2025 to remain PCI DSS compliant. Microform v1 and lower will reach end of life on October 1, 2025, after which existing v1 and v0.11 integrations will no longer function.

Comprehensive Overview

Microform v2 introduces three core changes that clients must implement during migration:

  • Updated server-side capture context request requiring clientVersion and allowedCardNetworks.
  • 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.

Migration Procedure

1. Generate the server-side capture context.

a. Send an authenticated POST request to the /sessions endpoint to create the session (capture context):

  • Test: POST: https://apitest.cybersource.com/microform/v2/sessions
  • Production: POST: https://api.cybersource.com/microform/v2/sessions

b. Update the request body. With Microform v1, the request contained only the target origin. With Microform v2, the request must also include at least one accepted card network and the clientVersion.

Current Integration (Microform v1 or v0.11)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.

2. Set 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 VersionScript Tag
Current Integration Microform v1
<script src="https://flex.cybersource.com/cybersource/microform/bundle/v1/flex-microform.min.js"></script>
Current Integration Microform v0.11
<script src="https://flex.cybersource.com/cybersource/assets/microform/0.11/flex-microform.min.js"></script>
After Migration to Microform v2
<script src="[Insert clientLibrary value here]" integrity="[Insert clientLibraryIntegrity value here]" crossorigin="anonymous"> </script>

3. Handle the updated transient token response.

a. Update integration logic to parse the new transient token response format. Microform v2 includes card detection and identifies the card type upon entry.

b. Review the detectedCardTypes array in the response. The format supports multiple card types so clients can choose which detected types to process.

Current Integration (Microform v1 or v0.11)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" } } } } }

Identifying the Current Microform Version

Use the following indicators to determine which Microform version a client is using:

VersionHow to Identify
Microform v0.11The transient token response returns "type": "mf-0.11.0".
Microform v1The Generate Capture Context request includes "clientVersion": "v1". The transient token response returns "type": "mf-1.0.0".
Microform v2The Generate Capture Context request includes "clientVersion": "v2" along with allowedCardNetworks. The transient token response returns "type": "mf-2.0.0".

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?
    • 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 April 1, 2025. Migration to Microform v2 is required to use the SRI value and remain compliant. Microform v1 and lower reach end of life on October 1, 2025, after which v1 and v0.11 integrations 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 continue to function as normal until end of life. However, to remain PCI DSS compliant, clients must upgrade to Microform v2 by April 1, 2025. Regardless of the current version, all clients must update how they load the Microform JavaScript library by dynamically loading it, decoding the JWT from the /sessions response, and using the clientLibrary and clientLibraryIntegrity


Was this article helpful?


Articles Recommended for You