Overview
Flex API enables merchants to securely accept customer payment information captured within a native iOS or Android application on a customer’s device or within a third-party server-side model. The Flex API protects your customer's primary account number (PAN), card verification number (CVN), and other payment information by embedding it within a transient token, reducing risk and simplifying Payment Card Industry Data Security Standard (PCI DSS) compliance.
As part of our commitment to modernizing our offerings and enhancing the security of our products, we are deprecating older versions of the Flex API. This initiative is designed to improve security for payment card transactions, safeguard sensitive information, maintain trust in electronic payment systems, and reduce the likelihood of data breaches.
By upgrading to the latest versions of our Flex API product, merchants can take advantage of the latest security enhancements and technological advancements, ensuring more secure and efficient transaction processing.
What action is required?
Flex API v1 will reach end of life on July 1, 2025. You must upgrade to Flex API v2 on or before this date. Failure to do so will result in transaction failures.
Migration steps for those currently using Flex API v1:
Key things to consider with migration to Flex API v2:
Flex API v2 supports both primary account number (PAN) and/or card verification number (CVN).
Flex API v1 creates permanent tokens, v2 creates Transient Tokens which expire after fifteen minutes.
Like the v1 permanent token, you will use the Transient Token in a call to payments API to create a payment. If you wish to store the payment credentials in your token vault, combine the payment call with a Customer token create (or create an additional Payment Instrument for an existing Customer).
Integrating your system with the Flex API v2 consists of the following tasks:
Use the /sessions API endpoint to generate the capture context and establish a payment session.
Use the /public-keys{}API endpoint to validate the capture context.
Compile the payment information in the appropriate data structure and encrypt it leveraging the one-time key provided in the sessions response object, this should result in a JWE format object.
- The data must match the data you specified in Generating the Capture Context.
Send the JWE to the /tokens API endpoint to tokenize the payment information.
Validate the transient token
Use the transient token to process a payment
Migration steps:
In Flex API v2, /keys have been replaced with /sessions. Like keys, sessions are created in an authenticated call from your server. Your server should send the result to your cardholder’s device or a third-party source of payment data. The session is used to encrypt the payment data.
From
Test: POST: https://apitest.cybersource.com/flex/v1/keys
Prod: POST https://api.cybersource.com/flex/v1/keys
To
Current Integration Flex API v1 | To obtain the Flex one time use public RSA key, the body of the request is as follows: |
After migration to Flex API v2
| The v2 sessions request and response differ significantly from the v1 keys API. To enhance security, you can now control which fields are required to create a token, but you cannot opt-out of client-side encryption. |
|
Note: specifying the encryptionType is not supported in v2. The JWT response from the /sessions API will always contain a dynamic JWK which is required to be used to encrypt the payment data on the cardholder’s device or a third-party source of payment data. If you currently set v1 /keys encryptionType to “None” you will need to implement this encryption in the following step.
The capture context that you generated is a JSON Web Token (JWT) data object. The JWT is digitally signed using a public key.
Retrieve the public key ID (kid) from the response JWT header
Pass the key ID (kid) (that you obtained from the JWT header) as a path parameter, and send a GET request to the /public-keys endpoint to get the public key:
Test: https://apitest.cybersource.com/flex/v2/public-keys/{kid}
You may cache the public-key to improve performance, however as we introduce new public-keys from time to time you must ensure you dynamically retrieve unknown key IDs from the above endpoints.
The public key is returned as a JSON Web Key (JWK). Use this public RSA key to validate the capture context.
Once the transient token is validated, secure the payment information for transport as follows:
Construct the JSON payload
Use the key provided the sessions API response to generate the JWE (JSON Web Encryption Data Object)
The JWT response to the sessions endpoint should be sent to the cardholder’s device or a third-party source of payment data. The code running on the device/third-party server will encrypt payment data entered by your customer and call the v2/tokens API.
Current Integration Flex API v1 | On your customer’s device or a third-party source of payment data optionally encrypt cardholder data and call the tokens API to request a permanent token.
Sign the headers and generate signature header by:
The calculated signature should then be appended as a header in your request along with content type.
Production Endpoint: POST https://api.cybersource.com/flex/v1/tokens Test Endpoint: POST https://apitest.cybersource.com/flex/v1/tokens
|
After migration to Flex API v2 | On your customer’s device or a third-party source of payment data, create a JSON payload by encrypting the cardholder data using the JWK extracted from the /sessions response. Use the keys to generate a JWE data object and insert that object into the body of a request and send an unauthenticated POST request from your customer’s device or a third-party source of payment data to the /tokens API endpoint. This returns a transient token that represents the supplied customer card data. The token can replace the payment information in any follow-on services.
Production Endpoint: POST https://api.cybersource.com/flex/v2/tokens Test Endpoint: POST https://apitest.cybersource.com/flex/v2/tokens
|
After receiving the transient token, validate its integrity using the public key embedded within the capture context at the beginning of this flow. This verifies that no-one has tampered with the token during transit.
Use the capture context public key to cryptographically validate the JWT provided. You might have to convert the JSON Web Key (JWK) to privacy‑enhanced mail (PEM) format for compatibility with some JWT validation software libraries.
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:
The consumer provides payment information during the checkout process and authorizes the payment for immediate processing.
After the transaction, the payment details are NOT stored for future use.
Flex API Integration:
Current Integration Flex API v1 | 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 Flex API 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:
The consumer provides payment information during the checkout process and authorizes the payment immediately.
After the transaction, the payment details are stored for future use as part of the account creation.
Flex API Integration:
Current Integration Flex API v1 | A permanent token is automatically created during checkout to process the payment and store payment details for future use. |
After migration to Flex API v2 | To retain the payment details for future use, a permanent token must be created. Within 15 minutes, use the transient token to make a call to the payments API to create a combined authorization with Customer TOKEN_CREATE. The authorization is required by card scheme rules, and can be zero amount if the cardholder is not purchasing at the time of storing their credentials
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: Returning Customer wants to pay with and save a new card
Current Integration Flex API v1 | Not supported |
After migration to Flex API v2 | To use the entered payment details to create a new Payment Instrument for an existing Customer, within 15 minutes use the transient token to make a call to the payments API to create a combined authorization with Payment Instrument creation for an existing Customer. The authorization is required by card scheme rules, and can be zero amount if the cardholder is not purchasing at the time of storing their credentials
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
Q&A
What type of transactions does this impact?
This feature impacts all transactions processed through Flex API v1.
Is this a backwards breaking change?
Flex API v1 will be deprecated and reach end of life by July 1st 2025.
I use Flex API in a browser, are there alternatives?
We offer a highly customizable Visa hosted Microform Integration product to capture card, CVV and bank account details. It follows a similar flow to Flex API, but the capture and encryption of the payment data is handled in our secure iframes. This may give you better protection from attacks and simplify your integration. Please refer to the Microform v2 documentation to see if it meets your requirements.
What is the third-party server-side model?
This is an example of where a Merchant is looking for a solution to having payment information securely sent to them through a backend service. There are three parties in this model as follows:
Entity which is PCI DSS compliant and has cardholder data accessible on their server (e.g. an issuing bank)
Entity which wants to use this card data, but not be exposed to it (e.g. Merchant - who wants a Transient Token to perform the payment/create permanent token)
Flex API
The flow is:
The merchant (b) creates the Flex session and passes the JWT to the PCI DSS Compliant entity (a)
The PCI DSS Compliant entity (a) uses the JWT to encrypt the card data and send to the Flex API (c) to create the Transient Token
The PCI DSS Compliant entity (a) receives the Transient Token and passes to the merchant (b) so that they can process the payment.