On This Page
Capture Context API
The capture context request is a signed JSON Web Token
(JWT) that includes all of the merchant-specific parameters. This request tells the
frontend JavaScript library how to behave within your payment experience. The request
provides authentication, one‑time keys, the target origin to the
Microform Integration
integration in addition to allowed card networks and payment
types (card or check). The capture context request includes these elements:- allowedCardNetworks
- allowedPaymentTypes
- clientVersion
- targetOrigins
- Target Origin
- The target origin is defined by the scheme (protocol), hostname (domain) and port number (if used).You must use the https:// protocol. Sub‑domains must also be included in the target origin.Any valid top‑level domain is supported such as .com, .co.uk, and.gov.br. Wildcards are not supported.For example, if you are launchingUnified Checkouton example.com, the target origin could be any of the following:You can define the payment cards and digital payments that you want to accept in the capture context.
- Allowed Card Networks
- Use theallowedCardNetworksfield to define the card types.These card networks are available for card entry:
- American Express
- Cartes Bancaires
- Carnet
- China UnionPay
- Diners Club
- Discover
- EFTPOS
- ELO
- JCB
- JCrew
- Mada
- Maestro
- Mastercard
- Meeza
- Visa
When you integrate withMicroform Integrationto accept card or check information, you must include at least one card network in theallowedCardNetworksfield in the capture context request. - Allowed Payment Types
- You can specify the type ofMicroform Integrationyou want to accept in the capture context. You can accept card and check information.
- Use theallowedPaymentTypesfield to define the payment type:
- CARD
- CHECK
allowedPaymentTypesfield is optional. When this field is provided in the capture context, theMicroform Integrationdefaults the field toCARDand is returned in the response regardless.
IMPORTANT
When integrating with
Cybersource
APIs, Cybersource
recommends that you
dynamically parse the response for the fields that you are looking for. Additional
fields may be added in the future. You must ensure that your integration can
handle new fields that are returned in the response. While the underlying data
structures will not change, you must also ensure that your integration can
handle changes to the order in which the data is returned.
Cybersource
uses semantic versioning practices, which enables you to
retain backwards compatibility as new fields are introduced in minor version
updates.Endpoint
Production:
POST
https://api.cybersource.com
/microform/v2/sessionsTest:
POST
https://apitest.cybersource.com
/microform/v2/sessionsRequired Fields for Requesting the Capture
Context
Your capture context request for accepting card and check
information must include these fields:
- This field is required only for accepting card information.
- This field is required only for accepting check information.
- The URL in this field value must containhttps.
Cybersource
REST API
Reference.REST Example: Requesting the Capture Context
Capture Context Request for Accepting Card and Check Information
{ "clientVersion": "v2", "targetOrigins": [ "https://www.example.com", "https://www.basket.example.com", "https://ecom.example.com" ], "allowedCardNetworks": [ "VISA", "MASTERCARD", "AMEX", "CARTESBANCAIRES", "CARNET", "CUP", "DINERSCLUB", "DISCOVER", "EFTPOS", "ELO", "JCB", "JCREW", "MADA", "MAESTRO", "MEEZA" ], "allowedPaymentTypes": [ "CARD", "CHECK" ] }
Successful Encrypted JWT Response for Accepting Card and Check
Information
eyJraWQiOiJqNCIsImFsZyI6IlJTMjU2In0.eyJmbHgiOnsicGF0aCI6Ii9mbGV4L3YyL3Rva2VucyIsImRhdGEiOiJ4Sy9RZzJzcWNiajNaODdIS0VwZGpSQUFFUEJLenFVaUlrdXdrelRadVNQeG9GWDNOK0VtT3k2ZGlBSXhwMHhvQStJc1Y5czlZZmRZVUJmbDFpV01kRVVmekhMTmhLQ1ZiOFAzSHg0bTQxejl6aEVcdTAwM2QiLCJvcmlnaW4iOiJodHRwczovL3N0YWdlZmxleC5jeWJlcnNvdXJjZS5jb20iLCJqd2siOnsia3R5IjoiUlNBIiwiZSI6IkFRQUIiLCJ1c2UiOiJlbmMiLCJuIjoiaTI5NmZmbUdiVkVRbG5zanNrQnBrajRCU1pRbE9Vd2Z2SUpsdUNIaHVkTEsxQmk4MEtpOVVfb0h2Mmxsd0NJSXFUMHdJWTBvaS1HM0xVc09BUUpjNUpwX08tY1VIdzFjeXV3aDVtWXZkUWZFM0JlcnRUcDZHQ1JLcFVyUjlDOGZoaTNfV1lQTDMwNjMxMGJXajh4OXY0UnlpR1BYUHdnUlJhVDlmbXJRV1diTHZaeFNZQ0Zpal9lSEZaYXQxa1JNdG5pTk5IUTNlV1ViWUV5QWZPSExOWDhUUmN6cjYybkdpeGh4NEFNYVB5YlEtTy0wM1pjRER4UldTLTI0UGhheVVYRjZnVlAydzNHc2hhOFQxSklnYlZSc253bHVuZ01jRExtZFI1cF9ITFlRdnNyX3BFS3pZd2tDQmFOUXA0ZjRkbXhyaVIyT2IyUU5fMXRkU2FUVzN3Iiwia2lkIjoiMDBXSXlhTndYcUJhdHNuYkVmMVNFTjFncHREbDExOUYifX0sImN0eCI6W3siZGF0YSI6eyJjbGllbnRMaWJyYXJ5SW50ZWdyaXR5Ijoic2hhMjU2LXZkWWkxaDV1ZTNwcm5iVC8xYThJSkxlUkNrSGVqSHBkRGR3My95RkxaREFcdTAwM2QiLCJjbGllbnRMaWJyYXJ5IjoiaHR0cHM6Ly9zdGFnZWZsZXguY3liZXJzb3VyY2UuY29tL21pY3JvZm9ybS9idW5kbGUvdjIuNS4xL2ZsZXgtbWljcm9mb3JtLm1pbi5qcyIsImFsbG93ZWRDYXJkTmV0d29ya3MiOlsiVklTQSIsIk1BU1RFUkNBUkQiLCJBTUVYIiwiTUFFU1RSTyIsIkRJU0NPVkVSIiwiRElORVJTQ0xVQiIsIkpDQiIsIkNVUCIsIkNBUlRFU0JBTkNBSVJFUyJdLCJ0YXJnZXRPcmlnaW5zIjpbImh0dHBzOi8vdGhlLXVwLWRlbW8uYXBwc3BvdC5jb20iXSwibWZPcmlnaW4iOiJodHRwczovL3N0YWdlZmxleC5jeWJlcnNvdXJjZS5jb20iLCJhbGxvd2VkUGF5bWVudFR5cGVzIjpbIkNBUkQiLCJDSEVDSyJdfSwidHlwZSI6Im1mLTIuMS4wIn1dLCJpc3MiOiJGbGV4IEFQSSIsImV4cCI6MTczMzQ5MDQwNywiaWF0IjoxNzMzNDg5NTA3LCJqdGkiOiJZcHdxWlNaTTZ1T1FBV1RoIn0.f24avtv-oUGfSaGqlQZfOZ4B6A-6E6yWymdgUtZmDDOVNanx5uLt5fxSBzAdmtC4em0kORatiS5pMhE66bCJT-ujIMHtdPITq9JJuE4Tm-NdfzznXlhz-qMM_setgmDXYLIIAeaUmSVebMwWqxBVmpQHRIBq2plwfB5dAH411aO-U1_DDJi14sIOLzUr_xhgfLJWsJ_B3gZkSaHrRaHWpnO-okCanTrVKCaFP1X5rKUilGII4wcJLdUyU3f9zFwteQ7wFfG81mRRWz4Gb4YgLt43TCD-jSigCAtgX_mqRyMqzCJtZXkf0Nf-o0bJLAc8-ce8MmeZD8H4uG42Eu-0UA
Decrypted Capture Context Header for Accepting Card and Check
Information
{ "kid": "j4", "alg": "RS256" }
Decrypted Capture Context Body with Selected Fields for Accepting Card
and Check Information
{ "flx": { "path": "/flex/v2/tokens", "data": "xK/Qg2sqcbj3Z87HKEpdjRAAEPBKzqUiIkuwkzTZuSPxoFX3N+EmOy6diAIxp0xoA+IsV9s9YfdYUBfl1iWMdEUfzHLNhKCVb8P3Hx4m41z9zhE=", "origin": "https://stageflex.cybersource.com", "jwk": { "kty": "RSA", "e": "AQAB", "use": "enc", "n": "i296ffmGbVEQlnsjskBpkj4BSZQlOUwfvIJluCHhudLK1Bi80Ki9U_oHv2llwCIIqT0wIY0oi-G3LUsOAQJc5Jp_O-cUHw1cyuwh5mYvdQfE3BertTp6GCRKpUrR9C8fhi3_WYPL306310bWj8x9v4RyiGPXPwgRRaT9fmrQWWbLvZxSYCFij_eHFZat1kRMtniNNHQ3eWUbYEyAfOHLNX8TRczr62nGixhx4AMaPybQ-O-03ZcDDxRWS-24PhayUXF6gVP2w3Gsha8T1JIgbVRsnwlungMcDLmdR5p_HLYQvsr_pEKzYwkCBaNQp4f4dmxriR2Ob2QN_1tdSaTW3w", "kid": "00WIyaNwXqBatsnbEf1SEN1gptDl119F" } }, "ctx": [ { "data": { "clientLibraryIntegrity": "CLIENT LIBRARY INTEGRITY VALUE GOES HERE", "clientLibrary": "CLIENT LIBRARY VALUE GOES HERE", "allowedCardNetworks": [ "VISA", "MASTERCARD", "AMEX", "MAESTRO", "DISCOVER", "DINERSCLUB", "JCB", "CUP", "CARTESBANCAIRES" ], "targetOrigins": [ "https://the-up-demo.appspot.com" ], "mfOrigin": "https://stageflex.cybersource.com", "allowedPaymentTypes": [ "CARD", "CHECK" ] }, "type": "mf-2.1.0" } ], "iss": "Flex API", "exp": 1733490407, "iat": 1733489507, "jti": "YpwqZSZM6uOQAWTh" }
Capture Context Request for Accepting Card Information
{ "clientVersion": "v2", "targetOrigins": [ "https://www.example.com", "https://www.basket.example.com", "https://ecom.example.com" ], "allowedCardNetworks": [ "VISA", "MASTERCARD", "AMEX", "CARTESBANCAIRES", "CARNET", "CUP", "DINERSCLUB", "DISCOVER", "EFTPOS", "ELO", "JCB", "JCREW", "MADA", "MAESTRO", "MEEZA" ], "allowedPaymentTypes": [ "CARD" ] }
Successful Encrypted JWT Response for Accepting Card Information
eyJraWQiOiJqNCIsImFsZyI6IlJTMjU2In0.eyJmbHgiOnsicGF0aCI6Ii9mbGV4L3YyL3Rva2VucyIsImRhdGEiOiJ1Q0RERW94M2dDQk1VaHI2T1ZDVGt4QUFFS1pHSTRHcDFvQ2pyYXlVb1MxQzdGOXE2WFpyYXhGbGxMVDMvenE2cjFnNXoxS1U2UDZseldqRVFTVVJoZUtxUThoVWJkZVNNdmt5SERTTXUwV01tMzhcdTAwM2QiLCJvcmlnaW4iOiJodHRwczovL3N0YWdlZmxleC5jeWJlcnNvdXJjZS5jb20iLCJqd2siOnsia3R5IjoiUlNBIiwiZSI6IkFRQUIiLCJ1c2UiOiJlbmMiLCJuIjoiMXNDY3NZNC1WZTNWU0VKekhnelJ5WjVDOURrM0VHZ2ZPOGd5SDc5bVJfSlN6NzdmWTdfV1loM3psdTkyTFVfeU5KVTBUMzdOQmVzd0szU2c0YnRNaU41Q0FCbWNXLWNSckhta2k0MVZoNUZRMmtjcWZSSlgxNVhZN1A3R25GTnd4QzVkUG9UM29NM1czRFVHaUMyYW56enhIN3pNNlA3N2hFbnc2TkZHSXlBdXhJRWFwRG9DaXlEVW5NdFRwV2lBV3YzTF9OVHZOaHRkVE4tNm1GRWU1RmdVYmlzeWtrTzlWMHZaS0d6SWRWWmdTdE42cHlnUGhVbnlNXzJIVmIxQmkyWjNKaElhZDFLUW02SGl0NklwYjNyUTBHRWZsN0ZWOUV3NGZyNzJpekQ0WVg2WHo0V3ZuMzlLN3J3WkhCRXdNM3l5Wl9ELTBUbjM1MFhvUlBUVjB3Iiwia2lkIjoiMDB4V1A1eUh1UE1kNkFkNHdwVzNzQkt1bWFaQ01zYWMifX0sImN0eCI6W3siZGF0YSI6eyJjbGllbnRMaWJyYXJ5SW50ZWdyaXR5Ijoic2hhMjU2LXZkWWkxaDV1ZTNwcm5iVC8xYThJSkxlUkNrSGVqSHBkRGR3My95RkxaREFcdTAwM2QiLCJjbGllbnRMaWJyYXJ5IjoiaHR0cHM6Ly9zdGFnZWZsZXguY3liZXJzb3VyY2UuY29tL21pY3JvZm9ybS9idW5kbGUvdjIuNS4xL2ZsZXgtbWljcm9mb3JtLm1pbi5qcyIsImFsbG93ZWRDYXJkTmV0d29ya3MiOlsiVklTQSIsIk1BU1RFUkNBUkQiLCJBTUVYIiwiTUFFU1RSTyIsIkRJU0NPVkVSIiwiRElORVJTQ0xVQiIsIkpDQiIsIkNVUCIsIkNBUlRFU0JBTkNBSVJFUyJdLCJ0YXJnZXRPcmlnaW5zIjpbImh0dHBzOi8vdGhlLXVwLWRlbW8uYXBwc3BvdC5jb20iXSwibWZPcmlnaW4iOiJodHRwczovL3N0YWdlZmxleC5jeWJlcnNvdXJjZS5jb20iLCJhbGxvd2VkUGF5bWVudFR5cGVzIjpbIkNBUkQiXX0sInR5cGUiOiJtZi0yLjEuMCJ9XSwiaXNzIjoiRmxleCBBUEkiLCJleHAiOjE3MzY0MzA0MTQsImlhdCI6MTczNjQyOTUxNCwianRpIjoiZDVZbzVhNU0wWFBPQ1BxZiJ9.G4Ea-gIk6SG5ULE4NE5OsdPI41YaAuTEMHDstBgkFzczIWwzJScvXs4hgWiyA-1ZLGITedlumGj-0x8jxmYTWeTm7D0fP8RL0w148EpDLMD8xMHpAJMdMqZTmYHyichsy8uOZKVOn9NbnuQqfDeQS_rLpJV3tMe2NwJL3RdBXdJ894ihKpFP2yXE1wQeLekNiYJ6s-Uuxwf0jf2CSN_TJAjnfVR6bqlpWbUpiUaBLcqDsHHe_pcrd5g2r-1LEfCiOV9RIw7844XKFNLQZvt_alQjItuMy8M9LVhnlRWCSnTKB1iV1RUxuTWtMzTvHmQWPx4nShqzE3j0Hp61c0PmBw
Decrypted Capture Context Body with Selected Fields for Accepting Card
Information
{ "flx": { "path": "/flex/v2/tokens", "data": "gEQUL6QggbM2m8R3/KhDLxAAEOmhvNFhDd+amn9NHURTfjqqN8+7dy/YKQXz0Ik2yhRVQ8omdKZ8VojIYkwOB9yUo/8LdddXruIQ3O5dSfmbW6A=", "origin": "https://stageflex.cybersource.com", "jwk": { "kty": "RSA", "e": "AQAB", "use": "enc", "n": "vHtaFM0e1ljAQ1Lnza95LdsBh10p78lz13rUdMe29vBESIeI912Fix514WXa97Ijh-pBuonFRcsyL0_-CF98rdhow6sZMhPdyOA9ud-PcAOwSHm-HrUUU_XkHGUVslBINAFOpOCYZh9qZ7jk6-5-Gk6MeyD4ok0BNz4XIKht_hj8yJQhphPz17hjguL9KPqK45HTl_D3SEStkbSaPK4fe-glMv2YJRh3nvdQYXkm-0cDmx4nets_4SH8U5DUwoFAB-Zh30-KHHe2nGbCYNrh7oUOEoC7mmF90HG0jwsbI5KSNDStckQ8pEZhpppVWyPh0CjzOmDidlkjUZ8hMJARWw", "kid": "008vKoQ3ycDeaUxLN6bPlfk9cjIjqSrb" } }, "ctx": [ { "data": { "clientLibraryIntegrity": " CLIENT LIBRARY INTEGRITY VALUE GOES HERE", "clientLibrary": "CLIENT LIBRARY VALUE GOES HERE", "allowedCardNetworks": [ "VISA", "MASTERCARD", "AMEX", "MAESTRO", "DISCOVER", "DINERSCLUB", "JCB", "CUP", "CARTESBANCAIRES" ], "targetOrigins": [ "https://example.com" ], "mfOrigin": "https://example.com", "allowedPaymentTypes": [ "CARD" ] }, "type": "mf-2.1.0" } ] }
Capture Context Request for Accepting Check Information
{ "clientVersion": "v2", "targetOrigins": [ "https://www.example.com", "https://www.basket.example.com", "https://ecom.example.com" ], "allowedPaymentTypes": ["CHECK"] }
Successful Encrypted JWT Response for Accepting Check Information
eyJraWQiOiJqNCIsImFsZyI6IlJTMjU2In0.eyJmbHgiOnsicGF0aCI6Ii9mbGV4L3YyL3Rva2VucyIsImRhdGEiOiJtdnkwVk9OVk40bzA4bTRGQjhmU3FCQUFFS0JWOTdlNnR2VDd4cHdqaFkwMDRydFJ1dGI0R2YwWlNwNGdNeEkvanBVSWxFblZKa2JtUVNHaWFnUEdGc0NPazdMbHJGTHFKcXN2eitoTHhrY08xRkFcdTAwM2QiLCJvcmlnaW4iOiJodHRwczovL3N0YWdlZmxleC5jeWJlcnNvdXJjZS5jb20iLCJqd2siOnsia3R5IjoiUlNBIiwiZSI6IkFRQUIiLCJ1c2UiOiJlbmMiLCJuIjoidmRpN0gtM1MzMTkyZlc5WC1BTmpvdjlFdXU4ZGxPOTBtU2gyUGVyMF9PdHZ4YlJITTBrakZpTHlKaGQwUUR3VlNWbUlhRFc2aGtCa1k2Ui1lcWRnaTdUVUNGZEQ3UUU1ckNkZGhZZTIycTh0RUNQZkpOWWJ6STZZTVBxTkFyYWc5LUhhWVo1X2tOX0JvMm5EclN4RFJ0MHBDbGxyd2d2Q1ZLb2M0RWF6ZE93QUE4dnI2VVh4Ty1SWVI2Z1R5VEZia244Q2hDVHNvWDByam5VWVI1VjdRaE95YzMzWEJUTVNDYTVBOHFQNDZnZXpvQjZ0dDA0SlQtRVVMWE9vYndVcVdvd0E3TTJzWUYydkFoQkVuMmt0REJFWVJSN3E0aWEyVHRIS1JPUW9FTjhZNjNiNFNaTGZDQk82cEc2QXpnSWpya3RkQXhIOXR0WURYdFJYS1YxeTN3Iiwia2lkIjoiMDBiQlN1d3VpdGtYeExROGFISWloMm5qMFhQNFpXYUsifX0sImN0eCI6W3siZGF0YSI6eyJjbGllbnRMaWJyYXJ5SW50ZWdyaXR5Ijoic2hhMjU2LXZkWWkxaDV1ZTNwcm5iVC8xYThJSkxlUkNrSGVqSHBkRGR3My95RkxaREFcdTAwM2QiLCJjbGllbnRMaWJyYXJ5IjoiaHR0cHM6Ly9zdGFnZWZsZXguY3liZXJzb3VyY2UuY29tL21pY3JvZm9ybS9idW5kbGUvdjIuNS4xL2ZsZXgtbWljcm9mb3JtLm1pbi5qcyIsInRhcmdldE9yaWdpbnMiOlsiaHR0cHM6Ly90aGUtdXAtZGVtby5hcHBzcG90LmNvbSJdLCJtZk9yaWdpbiI6Imh0dHBzOi8vc3RhZ2VmbGV4LmN5YmVyc291cmNlLmNvbSIsImFsbG93ZWRQYXltZW50VHlwZXMiOlsiQ0hFQ0siXX0sInR5cGUiOiJtZi0yLjEuMCJ9XSwiaXNzIjoiRmxleCBBUEkiLCJleHAiOjE3MzM0OTAxODEsImlhdCI6MTczMzQ4OTI4MSwianRpIjoiSXdEdHAxZkVZM2QwYUh6OSJ9.arokacvdTSUIehBY0ICi__2szuCdrvykJZq4T69n4OcWGym5PErJO0moJD-QYynhFj7_0k-G39qbkNJydB3UyF2qJSaqwZiopO27kuqk8u9Z0cY-V9Nu04JgaV4s18doxnzx6vdTCC3krrIcxeINi23Qu-Szcpg7aaGvPVXMC0DVC14WUQiGJkOakJ54jWtl2VoFAgYziUMcYYpk4hxLVxurBtT7lvrfCXKoyWtxiUxoEpOc_Td_qi5nA8ByWUaieQmp1Zej61khQJ_hmXtlsAt4BqxeJWoJeR_5Sjz0vD5y4-oAeNNrAulDem7CKiRJQbI9fyqT-H5Cmjd6YQchxQ
Decrypted Capture Context Body with Selected Fields for Accepting Check
Information
{ "flx": { "path": "/flex/v2/tokens", "data": "mvy0VONVN4o08m4FB8fSqBAAEKBV97e6tvT7xpwjhY004rtRutb4Gf0ZSp4gMxI/jpUIlEnVJkbmQSGiagPGFsCOk7LlrFLqJqsvz+hLxkcO1FA=", "origin": "https://example.com", "jwk": { "kty": "RSA", "e": "AQAB", "use": "enc", "n": "vdi7H-3S3192fW9X-ANjov9Euu8dlO90mSh2Per0_OtvxbRHM0kjFiLyJhd0QDwVSVmIaDW6hkBkY6R-eqdgi7TUCFdD7QE5rCddhYe22q8tECPfJNYbzI6YMPqNArag9-HaYZ5_kN_Bo2nDrSxDRt0pCllrwgvCVKoc4EazdOwAA8vr6UXxO-RYR6gTyTFbkn8ChCTsoX0rjnUYR5V7QhOyc33XBTMSCa5A8qP46gezoB6tt04JT-EULXOobwUqWowA7M2sYF2vAhBEn2ktDBEYRR7q4ia2TtHKROQoEN8Y63b4SZLfCBO6pG6AzgIjrktdAxH9ttYDXtRXKV1y3w", "kid": "00bBSuwuitkXxLQ8aHIih2nj0XP4ZWaK" } }, "ctx": [ { "data": { "clientLibraryIntegrity": "CLIENT LIBRARY INTEGRITY VALUE GOES HERE", "clientLibrary": "CLIENT LIBRARY VALUE GOES HERE ", "targetOrigins": [ "https://the-up-demo.appspot.com" ], "mfOrigin": "https://stageflex.cybersource.com", "allowedPaymentTypes": [ "CHECK" ] }, "type": "mf-2.1.0" } ], "iss": "Flex API", "exp": 1733490181, "iat": 1733489281, "jti": "IwDtp1fEY3d0aHz9" }