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 v0.4 and lower; 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 v0.4 or lower:
Key things to consider with migration to Microform v2:
- Microform v2 supports both primary account number (PAN) and/ or card verification number (CVN).
- The client will no longer receive a permanent token but a transient token regardless of whether they are using secure storage or TMS.
- Going forward you will use the transient token in call to payments API to create the payment and payment credentials all in one authorization with TOKEN_CREATE at the same time.
To migrate please do the following:
1. Generate the server-side capture context
a. A new endpoint is to be leveraged for generation of Capture context
From | Test: POST: https://apitest.cybersource.com/flex/v1/keys Prod: POST https://api.cybersource.com/flex/v1/keys |
To | Prod: POST: https://api.cybersource.com/microform/v2/sessions
|
b. In Microform v0.4 and lower, the request includes the encryptionType and targetOrigin. Now, it will contain an array of target origins, at least one accepted card network, and the clientVersion in the request body.
Current Integration Microform v0.4 |
|
After migration to Microform v2 |
|
2. Validate the Capture Context
a. Pass the key ID (kid) (that you 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}
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.
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. 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 v0.4 |
|
After migration to Microform v2 |
|
e. Create the HTML placeholder objects to attach to the microforms. Within your HTML checkout, replace the payment card tag with a simple container. Do the same for the CVN (which you won’t have had 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 that was generated in the previous step to the microform object.
const flex = new Flex(captureContext);
g. Initiate the microform object with styling to match your web page.
h. After you create a new Flex object, you can begin creating your Microform. You will pass your baseline styles and ensure that the button matches your 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.
Current Integration Microform v0.4 | Request a permanent token and validate its integrity using the public key. |
After migration to Microform v2 |
|
a. 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 types listed in the response.
Current Integration Microform v0.4 |
|
After migration to Microform v2 |
|
6. Using the Transient Token
With your transient token ready, determine your next steps based on your specific use cases. See below.
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:
a. The consumer provides payment information during the checkout process and authorizes the payment for immediate processing.
b. After the transaction, the payment details are NOT stored for future use.
Microform Integration:
Current Integration Microform v0.4 | A permanent token is generated during guest checkout. This token should be removed, as you are not saving payment details for future use. |
After migration to Microform v2 | 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 any payment details for future use.
Process:
a. The consumer provides payment information during the checkout process and authorizes the payment immediately.
b. After the transaction, the payment details are stored for future use as part of the account creation.
Microform Integration:
Current Integration Microform v0.4 | A permanent token is automatically created during checkout to process the payment and store payment details for future use. |
After migration to Microform v2 | The payment is processed using a transient token, which expires after 15 minutes. To retain the payment details for future use, a permanent token must be generated. Moving forward, you will 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 that bot detection is in place and that you have restricted the number of cards that can be linked to the consumer’s account 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:
a. Initial Payment: The customer initiates the first transaction by entering their payment details and consenting to recurring charges. This initial transaction is a CIT.
b. Recurring Payments: All subsequent charges are then processed automatically by the merchant at the scheduled intervals without requiring customer interaction.
Microform Integration:
Current Integration Microform v0.4 | A permanent token is automatically created during checkout to process the payment and store payment details for future use. |
After migration to Microform v2 | The payment is processed using a transient token, which expires after 15 minutes. To retain the payment details for future use, a permanent token must be generated. Moving forward, you will 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 that bot detection is in place and that you have restricted the number of cards that can be linked to the consumer’s account to protect against card enumeration attacks. |
Use Case Four: Stored Payment Method for Future Purchases (MIT)
Description: The customer saves their payment details for “1-click” future purchase or easy reordering during account creation.
Process:
a. Initial Setup: During account creation, the consumer authorises the merchant to save their payment method information for future use with a $0 authorization.
b. Future Payments: The merchant can then use this stored payment method to process transactions in situations like automatic replenishment or “1-click” purchases, often without requiring the customer to re-enter details.
Microform Integration:
Current Integration Microform v0.4 | A permanent token is automatically created during checkout to process the payment and store payment details for future use. |
After migration to Microform v2 | The payment is processed using a transient token, which expires after 15 minutes. To retain the payment details for future use, a permanent token must be generated. Moving forward, you will 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 that bot detection is in place and that you have restricted the number of cards that can be linked to the consumer’s account to protect against card enumeration attacks.
|
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?
For Microform v0.4 and lower, the current version is specified in the Flex Microform js script:
<script src="https://flex.cybersource.com/cybersource/assets/microform/0.4/flex-microform.min.js"></script>
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 v0.4 or lower, v0.11 or v1 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.
What actions should I take if I am using one of the legacy Cybersource SDKs for server-side setup?
If you are using a legacy version of the Cybersource SDK, follow step one above for Generating the server-side capture context. It is recommended to stop using the legacy Cybersource SDKs: