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:

{
"kid": "3g",
"alg": "RS256"
}
הההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההה
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

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

Payload:

{
"flx": {
"path": "/flex/v2/tokens",
"data": "XiPiMwi226+8LwyOaLa22xAAEHatTAKvotu/xxEPiy26iW+tOz5vZKWPIjWan8n7o/BkLECllI15K5g5tbT7LqeKeDiIcg+H9MMyf3AN
        /J1VEOaSewGO/rOg0PqaPDEUcB/O",
"origin": "https://testflex.cybersource.com",
"jwk": {
"kty": "RSA",
"e": "AQAB",
"use": "enc",
"n": "u_b-HQA2iPvn4c-wVUjtSsZH-vVxjMcwTDfp_Sq8yoh7X
          -icZ481wglLq8fYP9eDQpKwOIFGG8BvfToIG8S9HLOHtMFkaK_dBixcrDlbZKZYXF_vIvtMtKzLIGXgbLwPUd84Hptpk1hz7pBL3FM2T9W2JkKD_Ikh
          uMlt5On6xotPZiZ8mW5JAfLu8JKuMGoeyrO4Ie
          -lurFMKTAahn03t1mH6tBP_Hy4fGvzRiv8qzf6C61ZnwI9PHJEZ9HOMstM2dcR5n0UZ4gkQwo0K9KOs8M
          -s6Zeu5Zg2hz0c3tZ5LZzSDGvznLSk2JL_KrvKVmbsQK-_TA60tcdwYx60Qm1UQ",
"kid": "07wjB4pZaLPAKjxfe3Ycnl5yKWODVv3z"
}
},
"ctx": [
{
"data": {
"targetOrigins": [
"http://localhost:8082"
],
"mfOrigin": "https://testflex.cybersource.com"
},
"type": "mf-0.11.0"
}
],
"iss": "Flex API",
"exp": 1593515408,
"iat": 1593514508,
"jti": "suvxM83tDu8TWU0w"
}
הההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההה
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

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:

{
"encryptionType": "RsaOaep256",
"targetOrigin": "http://website.com/paymentpage"
}
הההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההה
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Response body:

{
"keyId": "eyJraWQiOiIzZyIsImFsZyI6IlJTMjU2In0
      .eyJmbHgiOnsicGF0aCI6Ii9mbGV4L3YyL3Rva2VucyIsImRhdGEiOiJpdllwejUwaGV2QUxRR2ZQZ1dUN3poQUFFQ29PVTh6QlIvQituMFJBQ0twUFJWZE
      k3UXc5bVZrVExwNFBKWW1VTFZQM2tHNnpZY1l4SXNVeG80K1lCazdnSWJ4L2lCUEFwTUN3YTRHbGlWUVBhK3JsK0xENlFzckVyaDdkYmpVT0loMkIiLCJvc
      mlnaW4iOiJodHRwczovL3Rlc3RmbGV4LmN5YmVyc291cmNlLmNvbSIsImp3ayI6eyJrdHkiOiJSU0EiLCJlIjoiQVFBQiIsInVzZSI6ImVuYyIsIm4iOiJt
      dzgxcGhRWnFuLUgxNjlDLUxXNGtPU2M5NkZpR2NaYkllOHFfYm5aSFBITjFZWUV1azA4MzF1Z0U5REdPNGs2Y01fenc1allWV2ZsZmxxTXVkdkZkdlQ4cTh
      TZWhHYVZzbmlCMjZVNUtNbXpGdGNIeFpISUppczJFbFNUZlgxVXNpVmJaR3liWXNadm16RlAtUWJDMWpRRVBrQ1JaVzUtTTd6MGZaalZDcE1hSWJCNUJxLW
      RnbnF0eDFoOXZsSXpSLUJEOHdyYnRuT2kxOVFURVdPa0d2NjQ2OGZORGVxZUVQOVpJNDNuWHdYU3ljTFVzZ2lBYzY4MDlEUjZwREVBd0hzd3k0SmQ5aHhBb
      G1ldzdwRWxwcm1DWFRGS3d5T2pyMXYzRms4a09ZWFJWYVlYVEFiRkpYTE1HYl9FOEFvT0d6Szg3eUk5V2M3eGZnYW5FQWp1dHciLCJraWQiOiIwODJOZHpB
      SnNiMWk4ZGMzNnFtbzVDQVBpRmpJcXVhUiJ9fSwiY3R4IjpbeyJkYXRhIjp7InRhcmdldE9yaWdpbnMiOlsiaHR0cDovL2xvY2FsaG9zdDo4MDgyIl0sIm1
      mT3JpZ2luIjoiaHR0cHM6Ly90ZXN0ZmxleC5jeWJlcnNvdXJjZS5jb20ifSwidHlwZSI6Im1mLTAuMTEuMCJ9XSwiaXNzIjoiRmxleCBBUEkiLCJleHAiOj
      E1OTI0ODAyNjEsImlhdCI6MTU5MjQ3OTM2MSwianRpIjoiR3J6RFNlRGNJc2hZSUpVUSJ9
      .ND4tjzw5G9V02nTYnSEMAruD5OJrYY1sxSF5baOnp_DveApruFkxjBdcztVsjlB5fN7HkTpwpt9ZVV3eL18tyCmPijY23TpjHsXpL5lvr1vrVVWtggzOrx
      ZQEoufoAgK2fhQJxEZ2_zX8bfgZO4Q_W3rPfvcZ1IkKR
      -qvXDK_sRJJJALC80dYUHi7Vz2G0FSVQ0ZEOwmIznJC3_wVabOUsY7hIJLJJDG2bTeK9Tw_aKm6evzf
      -9dVp8IDfIeCFwBMsJGnPySoWYCNjoGMklbjmt_ppAE_yWb2i9X2GpL_A8ceb01VlxB9bheJsvMZGcc_mINxvKPDFM3bQUxzWN5cA",
"der": null,
"jwk": null
}
הההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההה
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX