On This Page

Generating the Capture Context

The first step to Flex API v2 is to generate the context of the customer payment information that is to be captured and tokenized.

IMPORTANT

Declaring the capture context ensures that no data can be injected into the process by a malicious actor.

To generate the capture context, use the

/sessions

API endpoint to specify the payment data to be captured. The API returns a JSON Web Token (JWT) data object that contains the authentication component of the interactions and the one-time public encryption keys to which the payment information is to be secured.

IMPORTANT

The internal data structure of the JWT can expand to contain additional data elements. Ensure that your integration and validation rules do not limit the data elements contained in responses.

Resource

Send an unauthenticated POST request from your customer’s device or browser to the

/sessions

API:

Test:

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

Production:

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

The resource returns a transient token that represents the supplied customer card data. The token can replace the payment information in any follow-on Cybersource services.

Sessions Request Payload

The body of the request specifies the fields that the integration is to capture and tokenize.

This specifies that the integration will capture and tokenize only the customer card number:

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

Sessions Response Payload

The response payload is JWT data object that specifies the capture context in two parts.

This capture context response example from a sessions API request:

eyJraWQiOiJzbiIsImFsZyI6IlJTMjU2In0.eyJmbHgiOnsicGF0aCI6Ii9mbGV4L3YyL3Rva2VucyIsImRhdGEiOiJOVGFUSDI3cVpVbE9EeFJVQkVLSXJoQUFFRkFBbHJoOHkxN2doTlpueVlWUWI4dnpCR05QV1NtbHpuelBxQzkzWGZ1TUpiK3M3RFR5a1o1USt5alBvRjAzQmxjenQ1VnZpSUdVY0toNjBjU2dzSElcdTAwM2QiLCJvcmlnaW4iOiJodHRwczovL3NsNzNmbHhhcHEwMDIudmlzYS5jb206ODQ0MyIsImp3ayI6eyJrdHkiOiJSU0EiLCJlIjoiQVFBQiIsInVzZSI6ImVuYyIsIm4iOiJwRnJBNUxzbDIycDNnTkw1aVBqQk9ZRXVYczd6OVAtZHY3QUlDVEd6bGdOeU52eWZGX3RXR2FMcVMtbGYyUWdEdlZXM2NVMG1xVnhKWExFMUZjSlpqNzFkMXNnWkIxbjRpcldzcVBxNTRjZndFeDQyNURERlphaXdRX0Z2MXYxbUFOM1RSVDJrYVFLLV8yZFlNTkxJV0hxajkzYXdfYkxUUVRfem8xamNhTFRSamU2eHo3VDRDcUlRWjZLQl9XMjF0Y3NNREdVYkotdjZ5VXBZMkVtbWNMcF92cUlwc0VCaUNOb2NER2xudk1KZFJ5aEJiOHRocWlYclpqVExvT29XdGlhSG9BbExXTDNjVW9HUlZHdFdkRWYtSS1IZlBEcE8ySEJGaUZ1bHdidjU0UGphY19zVm9HRnpHZ2xHcndJV0IyNDFjOTV1LWJaVWVkcE5fNmlnMFEiLCJraWQiOiIwMFN2SWFHSWZ5YXc4OTdyRGVHOWVGZE9ES2FDS2MxcSJ9fSwiY3R4IjpbeyJkYXRhIjp7InJlcXVpcmVkRmllbGRzIjpbInBheW1lbnRJbmZvcm1hdGlvbi5jYXJkLm51bWJlciJdLCJvcHRpb25hbEZpZWxkcyI6WyJwYXltZW50SW5mb3JtYXRpb24uY2FyZC5leHBpcmF0aW9uWWVhciIsInBheW1lbnRJbmZvcm1hdGlvbi5jYXJkLmV4cGlyYXRpb25Nb250aCIsInBheW1lbnRJbmZvcm1hdGlvbi5jYXJkLnR5cGUiLCJwYXltZW50SW5mb3JtYXRpb24uY2FyZC5zZWN1cml0eUNvZGUiXX0sInR5cGUiOiJhcGktMC4xLjAifV0sImlzcyI6IkZsZXggQVBJIiwiZXhwIjoxNjE0NzkyMjY4LCJpYXQiOjE2MTQ3OTEzNjgsImp0aSI6InJPQWtzR2NwOEJnZzZXTGoifQ.uHMrYZFoqqDiiic-s-29GAI0V5Ex1361Izzhxiqt6eMZcTW-bApAxgfTe0eBK3vi9s6VZbm1fgE1dh8BdMeo2AkF-_Q4c3wch2YPOMhcuOpstZyLj22tnrmaLXmcHwTorDBMA3fVH_8EIn8T4gonZ-ItTa05sxAk5rLVEWywlau5-Gi74tuxtDQOPIc7F9SzmqwGmLCuUZ6JuJf8bExAyL5ChiqQ9MDsbP6Q2jtDXok4VAHVkJR3uRJvmblHfgRM1LRVH8XGv9GX69b30_rQ4Md5xOugvI6Hu7X30qo9fFpfT3v9qQ6wocnJpowKe2v0u7rcid_GqqjZckbEVb47VQ

This example shows JWT decoded, containing the JSON Web Key (JWK) encryption keys:

{
  "flx" : {
    "path" : "/flex/v2/tokens",
    "data" : "NTaTH27qZUlODxRUBEKIrhAAEFAAlrh8y17ghNZnyYVQb8vzBGNPWSmlznzPqC93XfuMJb+s7DTykZ5Q+yjPoF03Blczt5VviIGUcKh60cSgsHI=",
    "origin" : "https://sl73flxapq002.visa.com:8443","origin" : "https://sl73flxapq002.bankofamerica.com:8443",
    "jwk" : {
      "kty" : "RSA",
      "e" : "AQAB",
      "use" : "enc",
      "n" : "pFrA5Lsl22p3gNL5iPjBOYEuXs7z9P-dv7AICTGzlgNyNvyfF_tWGaLqS-lf2QgDvVW3cU0mqVxJXLE1FcJZj71d1sgZB1n4irWsqPq54cfwEx425DDFZaiwQ_Fv1v1mAN3TRT2kaQK-_2dYMNLIWHqj93aw_bLTQT_zo1jcaLTRje6xz7T4CqIQZ6KB_W21tcsMDGUbJ-v6yUpY2EmmcLp_vqIpsEBiCNocDGlnvMJdRyhBb8thqiXrZjTLoOoWtiaHoAlLWL3cUoGRVGtWdEf-I-HfPDpO2HBFiFulwbv54Pjac_sVoGFzGglGrwIWB241c95u-bZUedpN_6ig0Q",
      "kid" : "00SvIaGIfyaw897rDeG9eFdODKaCKc1q"
    }
  },
  "ctx" : [ {
    "data" : {
      "requiredFields" : [ "paymentInformation.card.number" ],
      "optionalFields" : [ "paymentInformation.card.expirationYear", "paymentInformation.card.expirationMonth", "paymentInformation.card.type", "paymentInformation.card.securityCode" ]
    },
    "type" : "api-0.1.0"
  } ],
  "iss" : "Flex API",
  "exp" : 1614792268,
  "iat" : 1614791368,
  "jti" : "rOAksGcp8Bgg6WLj"
}