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
For information on JSON Web Tokens, see JSON Web Tokens.
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 launching
Unified Checkout
on 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 the
allowedCardNetworks
field 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 with
Microform Integration
to accept card or check information, you must include at least one card network in the
allowedCardNetworks
field in the capture context request.
Allowed Payment Types
You can specify the type of
Microform Integration
you want to accept in the capture context. You can accept card and check information.
Use the
allowedPaymentTypes
field to define the payment type:
  • CARD
  • CHECK
The
allowedPaymentTypes
field is optional. When this field is provided in the capture context, the
Microform Integration
defaults the field to
CARD
and 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/sessions
Test:
POST
https://apitest.cybersource.com
/microform/v2/sessions

Required 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 contain
https
.
For a complete list of fields you can include in your request, see the
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" }