How to Migrate Microform from v1 and lower to v2
Microform V1 and V0.11 UPDATES TO MEET PCI DSS 4.0.1 REQUIREMENTS
KA-07550
19
11/22/2024 18:23 PM
1.0
Overview
Microform v2 is being upgraded to comply with the new Payment Card Industry Data Security Standard guidelines (PCI DSS 4.0.1), specifically requirement 6.4.3. PCI DSS is a widely accepted set of policies and procedures intended to optimize the security of credit, debit and cash card transactions. This update is designed to improve security for payment card transactions, safeguarding sensitive information, maintaining trust in electronic payment systems, and reducing the likelihood of a data breach.
What action is required?
If you are using Microform v1 or v0.11; to comply with the new regulations, you must upgrade to Microform v2 before April 1, 2025.
Microform v1 and lower will reach end of life by July 1, 2025.
Migration steps for those currently using Microform v1 or v0.11 to v2:
To comply with PCI DSS V4.0.1, it is essential to update your Microform implementation from versions v1 or v0.11 to Microform v2. The main changes are when generating the server-side capture context and the client-side setup as follows:
a. Continue to send an authenticated POST request to the /sessions end point to create your session (capture context):
Test:
POST: https://apitest.cybersource.com/microform/v2/sessions
Production:
POST: https://api.cybersource.com/microform/v2/sessions
b. With Microform v1, the request contained only the target origin. Now, it will also include at least one accepted card network and the clientVersion in the body content of the request.
Current Integration Microform v1OR v0.11
|
|
After migration to Microform v2 |
|
b. Pass the capture context response data object to the front-end application after validating the capture context.
a. Add the Microform JavaScript library to your page by dynamically loading it on the front-end.
b. Decode the JWT from your /sessions response (capture context).
c. Use the “clientLibrary” and “clientLibraryIntegrity” values to create your script tags. Ensure that you do this for every transaction as these values can be unique per transaction.
d. Ensure that you do NOT hard code these values, as doing so can lead to Microform front end errors.
Current Integration Microform v1
|
|
Current Integration Microform v0.11 |
|
After migration to Microform v2 |
|
3. 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. Clients can choose which card types to process based on the detected card types listed in the response.
Current Integration Microform v1 OR v0.11 |
|
After migration to Microform v2 |
|
Resources
PCI DSS Summary of Changes: v4.0.1:
Microform V2 documentation:
List of card types:
https://developer.cybersource.com/docs/cybs/en-us/payments/developer/ctv/rest/payments/payments-intro/payments-intro-cards-types.html
Q&A
What is PCI DSS?
See https://docs-prv.pcisecuritystandards.org/PCI%20DSS/Standard/PCI-DSS-v4_0_1.pdf
How do I know what version of Microform I am using?
Microform v0.11:
For Microform v0.11, the type property will be returned in the transient token response e.g. "type": "mf-0.11.0"
Microform v1:
For Microform v1, the current version of Microform that you are currently using will be specified in the clientVersion field within the Generate Capture Context request. For example:
{"clientVersion": "v1",
"targetOrigins": ["https://www.example.com"]
}
The type property will be returned in the transient token response e.g. "type": "mf-1.0.0"
Microform v2:
For Microform v2, the current version of Microform that you are currently using will be specified in the clientVersion field within the Generate Capture Context request. For example:
{"targetOrigins": ["https://www.example.com"],
"allowedCardNetworks": ["VISA"],
"clientVersion": "v2"}
The type property will be returned in the transient token response e.g. "type": "mf-2.0.0"
If I am currently using Microform v1 or lower, can I continue to use this version and continue to be PCI DSS Compliant?
If integrated with Microform v1 or lower you will NOT be able to avail of the SRI value feature and will no longer be PCI-DSS compliant from April 1, 2025. To avail of the SRI value and remain PCI-DSS compliant you will need to migrate from older versions of the product to Microform v2.
Microform v1 and lower will be deprecated and reach end of life by July 1st 2025. From this point on, your integration with Microform v1 or v0.11 will no longer work.
What type of transactions does this impact?
This feature impacts all transactions processed through Microform.
Is this a backwards breaking change?
Your existing Microform integration will continue to work as normal, however in order to remain PCI DSS compliant you must upgrade to Microform v2 by April 1, 2025.
Microform v1 and lower will be deprecated and reach end of life by July 1st 2025.
Regardless of what version of Microform you are currently using you will need to change how you are loading the Microform JavaScript library as follows:
Add the Microform JavaScript library to your page by dynamically loading it on the front-end.
Decode the JWT from your /sessions response (capture context).
Use the “clientLibrary” and “clientLibraryIntegrity” values to create your script tags.
Ensure that you do this for every transaction as these values can be unique per transaction. Ensure that you d
o NOT hard code these values, as doing so can lead to Microform front end errors.
Was this article helpful?