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 a fully authenticated POST request from your backend system to the
/sessions
API:- Test:https://apitest.cybersource.com/flex/v2/sessions
- Production:https://api.cybersource.com/flex/v2/sessions
The resource returns a capture context, which is a JWT date element containing the
keys necessary to encrypt the payment data.
Payment API Fields
This is the list of possible fields to capture and tokenize.
- orderInformation.amountDetails.currency
- orderInformation.amountDetails.totalAmount
- orderInformation.billTo.address1
- orderInformation.billTo.address2
- orderInformation.billTo.administrativeArea
- orderInformation.billTo.buildingNumber
- orderInformation.billTo.company
- orderInformation.billTo.country
- orderInformation.billTo.district
- orderInformation.billTo.email
- orderInformation.billTo.firstName
- orderInformation.billTo.lastName
- orderInformation.billTo.locality
- orderInformation.billTo.phoneNumber
- orderInformation.billTo.postalCode
- orderInformation.shipTo.address1
- orderInformation.shipTo.address2
- orderInformation.shipTo.administrativeArea
- orderInformation.shipTo.buildingNumber
- orderInformation.shipTo.company
- orderInformation.shipTo.country
- orderInformation.shipTo.district
- orderInformation.shipTo.firstName
- orderInformation.shipTo.lastName
- orderInformation.shipTo.locality
- orderInformation.shipTo.postalCode
- paymentInformation.card.expirationMonth
- paymentInformation.card.expirationYear
- paymentInformation.card.number
- paymentInformation.card.securityCode
- paymentInformation.card.type
This example shows the 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", "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" }
Related Information
REST Example: Generating the Capture Context
Minimum Request
1234567891011121314151617181920{ "paymentInformation" : { "card" : { "number" : { }, "securityCode" : { "required" : false }, "expirationMonth" : { "required" : false }, "expirationYear" : { "required" : false }, "type" : { "required" : false } } } }
Maximum Request
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107{ "paymentInformation" : { "card" : { "number" : { }, "securityCode" : { "required" : false }, "expirationMonth" : { "required" : false }, "expirationYear" : { "required" : false }, "type" : { "required" : false } } }, "orderInformation" : { "amountDetails" : { "totalAmount" : { "required" : false }, "currency" : { "required" : false } }, "billTo" : { "address1" : { "required" : false }, "address2" : { "required" : false }, "administrativeArea" : { "required" : false }, "buildingNumber" : { "required" : false }, "country" : { "required" : false }, "district" : { "required" : false }, "locality" : { "required" : false }, "postalCode" : { "required" : false }, "email" : { "required" : false }, "firstName" : { "required" : false }, "lastName" : { "required" : false }, "phoneNumber" : { "required" : false }, "company" : { "required" : false } }, "shipTo" : { "address1" : { "required" : false }, "address2" : { "required" : false }, "administrativeArea" : { "required" : false }, "buildingNumber" : { "required" : false }, "country" : { "required" : false }, "district" : { "required" : false }, "locality" : { "required" : false }, "postalCode" : { "required" : false }, "firstName" : { "required" : false }, "lastName" : { "required" : false }, "company" : { "required" : false } } } } }
Response Payload
1eyJraWQiOiJzbiIsImFsZyI6IlJTMjU2In0.eyJmbHgiOnsicGF0aCI6Ii9mbGV4L3YyL3Rva2VucyIsImRhdGEiOiJOVGFUSDI3cVpVbE9EeFJVQkVLSXJoQUFFRkFBbHJoOHkxN2doTlpueVlWUWI4dnpCR05QV1NtbHpuelBxQzkzWGZ1TUpiK3M3RFR5a1o1USt5alBvRjAzQmxjenQ1VnZpSUdVY0toNjBjU2dzSElcdTAwM2QiLCJvcmlnaW4iOiJodHRwczovL3NsNzNmbHhhcHEwMDIudmlzYS5jb206ODQ0MyIsImp3ayI6eyJrdHkiOiJSU0EiLCJlIjoiQVFBQiIsInVzZSI6ImVuYyIsIm4iOiJwRnJBNUxzbDIycDNnTkw1aVBqQk9ZRXVYczd6OVAtZHY3QUlDVEd6bGdOeU52eWZGX3RXR2FMcVMtbGYyUWdEdlZXM2NVMG1xVnhKWExFMUZjSlpqNzFkMXNnWkIxbjRpcldzcVBxNTRjZndFeDQyNURERlphaXdRX0Z2MXYxbUFOM1RSVDJrYVFLLV8yZFlNTkxJV0hxajkzYXdfYkxUUVRfem8xamNhTFRSamU2eHo3VDRDcUlRWjZLQl9XMjF0Y3NNREdVYkotdjZ5VXBZMkVtbWNMcF92cUlwc0VCaUNOb2NER2xudk1KZFJ5aEJiOHRocWlYclpqVExvT29XdGlhSG9BbExXTDNjVW9HUlZHdFdkRWYtSS1IZlBEcE8ySEJGaUZ1bHdidjU0UGphY19zVm9HRnpHZ2xHcndJV0IyNDFjOTV1LWJaVWVkcE5fNmlnMFEiLCJraWQiOiIwMFN2SWFHSWZ5YXc4OTdyRGVHOWVGZE9ES2FDS2MxcSJ9fSwiY3R4IjpbeyJkYXRhIjp7InJlcXVpcmVkRmllbGRzIjpbInBheW1lbnRJbmZvcm1hdGlvbi5jYXJkLm51bWJlciJdLCJvcHRpb25hbEZpZWxkcyI6WyJwYXltZW50SW5mb3JtYXRpb24uY2FyZC5leHBpcmF0aW9uWWVhciIsInBheW1lbnRJbmZvcm1hdGlvbi5jYXJkLmV4cGlyYXRpb25Nb250aCIsInBheW1lbnRJbmZvcm1hdGlvbi5jYXJkLnR5cGUiLCJwYXltZW50SW5mb3JtYXRpb24uY2FyZC5zZWN1cml0eUNvZGUiXX0sInR5cGUiOiJhcGktMC4xLjAifV0sImlzcyI6IkZsZXggQVBJIiwiZXhwIjoxNjE0NzkyMjY4LCJpYXQiOjE2MTQ3OTEzNjgsImp0aSI6InJPQWtzR2NwOEJnZzZXTGoifQ.uHMrYZFoqqDiiic-s-29GAI0V5Ex1361Izzhxiqt6eMZcTW-bApAxgfTe0eBK3vi9s6VZbm1fgE1dh8BdMeo2AkF-_Q4c3wch2YPOMhcuOpstZyLj22tnrmaLXmcHwTorDBMA3fVH_8EIn8T4gonZ-ItTa05sxAk5rLVEWywlau5-Gi74tuxtDQOPIc7F9SzmqwGmLCuUZ6JuJf8bExAyL5ChiqQ9MDsbP6Q2jtDXok4VAHVkJR3uRJvmblHfgRM1LRVH8XGv9GX69b30_rQ4Md5xOugvI6Hu7X30qo9fFpfT3v9qQ6wocnJpowKe2v0u7rcid_GqqjZckbEVb47VQ