`Flex API`

The Flex API enables merchants to securely accept customer payment information captured within a server-side application using a set of APIs. These APIs protect your customer's primary account number (PAN), card verification number (CVN), and other payment information by embedding it within a transient token. This allows payment data to be stored and transported and complies with the Payment Card Industry Data Security Standard (PCI DSS) policies and procedures. These transient tokens can be validated by the receiver to ensure the data integrity and protect against data injection attacks.

WARNING

Flex API is intended for server-side applications only. Do not use the Flex API in client-side applications. To add secure payments directly into client-side code, use Unified Checkout.

How It Works

Follow these steps to capture payments using the Flex API:

Establish a payment session with a predefined customer context.

Validate the JSON Web Token.

Populate the JSON Web Token with customer information.

Customer Context

An important benefit of the Flex API is managing Personal Identifiable Information (PII). You can set up your customer context to include all PII associated with transactions, protecting this information from third parties.

Establishing a Payment Session with a Capture Context

To establish a payment session, include the API fields you plan to use in that session in the body of the request. The system then returns a JSON Web Token (JWT) that includes the capture context.

To determine which fields to include in your capture context, identify the personal information that you wish to isolate from the payment session.

Capture Context Fields

When making a session request, any fields that you request to be added to the capture context are required by default. However, you can choose to make a field optional by setting the

required

parameter to

false

For example, the following code snippet includes both required and optional fields:

    "fields" : {
  "paymentInformation" : {
    "card" : {
      "number" : {
        },
      "securityCode" : {
        "required" : true
        },
    "expirationMonth" : {
      "number" : {
        "required" : false
        },
      "expirationYear" : {
        "required" : false
        }
      }
    }
  }
}

In this example, the

paymentInformation.card.number

and

paymentInformation.card.securityCode

fields are required and the

paymentInformation.card.expirationMonth

and

paymentInformation.card.expirationYear

fields are optional. The inclusion of the

paymentInformation.card.number

field in the request sets it as a required field and, therefore, you do not need to include the

paymentInformation.card.number.required

field.

Endpoint

Production:

GET https://api.cybersource.com/flex/v2/sessions

Test:

GET https://apitest.cybersource.com/flex/v2/sessions

Validating the JSON Web Token

When the system has returned the transient JWT, validate the token's authenticity. Retrieve the public key signature that is part of the transient JWT and compare that signature with the public key returned from Cybersource.

Follow these steps to validate the key:

Retrieve the public key ID (

kid

) from the transient JWT header.

Retrieve the public key from Cybersource.

Validate the public key signature.

Populating the JSON Web Token with Customer Information

As soon as the transient token is validated, you can add the customer's personal information to the token.

Follow these steps to populate the token:

Construct the JSON payload.

Generate the JSON Web Encryption (JWE) data object.