Concept

The first step in Microform integration is to request a capture context from Cybersource. Capture context is a digitally signed JWT.

Capture context is requested from Flex API, which is is a simple API that allows for multiparty communication model, where one party sends (usually from the front-end, e.g. cardholder's browser or mobile app) information to Cybersource in exchange for a token. The other party (usually a merchant) receives the token directly from the front-end and uses it later. Data the token represents is kept securely in Cybersource. Capture Context enables that interaction model and adds crucial security to it.

Capture Context provides:

  • Authentication
  • One-time encryption keys
  • Trusted endpoints and other information to be used by Microform

Capture Context is signed so that the receiving party can verify it is coming from Cybersource, including automated verification by Microform

Format

As mentioned at the start Capture Context is a signed JWT. Flex API uses a private key to sign JWT content, while public keys (shared separately) are used by merchants and Microform to validate Capture Context.

JWT stands for JSON Web Token. It is an open, industry standard RFC 7519 method for representing claims securely between two parties. JWT consists of a header, payload, and a signature. See more at https://jwt.io and https://tools.ietf.org/html/rfc7519.

Common JWT claims:

  • jti - unique id
  • iat - time at which JWT was generated
  • exp - time at which JWT will expire
  • iss - issuer of the JWT, i.e. merchant, normally, we put some sort of a key id here. Cardinal's JWT use this for the org ID, for example

Front-end specific claims:

  • ctx[].type - type of the front-end application
  • ctx[].data - capture context data, i.e. target origin

Flex API specific claims:

  • flx.origin - points to Flex API server that will handle encrypted data
  • flx.path - defines the tokenization path for flex.origin service
  • flx.jwk - this is the public encryption/signing key
  • flx.data - capture context data, i.e. target origin

Here's an example of decoded Capture Context JWT for Microform.

Header:

Key (shared separately) for validation of Capture Context is selected via the 'kid' claim.

Payload:

Request and response for Microform

Request to generate capture context must be sent from secure merchant environment (i.e. server). This request will be authenticated through CGK with an HTTP Signature or a Bearer Token, the two authentication methods supported by Cybersource RESTful APIs.

Sequence diagram

Request body:

Response body: