[Tech Spec] Wellsfargo — CreateClientAuthenticationToken

[shuklatushar226]

Wellsfargo — CreateClientAuthenticationToken

Complexity: low
Generated by: Grace pipeline run run-2026-05-13T20-26-07-750Z-ee57f9

Summary

Implement CreateClientAuthenticationToken payment method for Wellsfargo connector. Wellsfargo CreateClientAuthenticationToken — Technical Specification

Scope

Wellsfargo CreateClientAuthenticationToken — Technical Specification

CONNECTOR: Wellsfargo
FLOW: CreateClientAuthenticationToken
STATUS: SUCCESS
TECHSPEC_PATH: techspecs/Wellsfargo_CreateClientAuthenticationToken_spec.md
REASON:

---

1. Connector Profile

Field	Value
Connector name	Wellsfargo
Primary flow scope	CreateClientAuthenticationToken (Flex Microform SDK session)
API family	Cybersource REST API (Wells Fargo uses Cybersource backend infrastructure)
Production host	https://api.cybersource.com
Sandbox host	https://apitest.cybersource.com
Regional hosts	None (single global endpoint)
API version	microform/v2
Content-Type (request)	application/json;charset=utf-8
Content-Type (response)	application/jwt (raw JWT string)

Wells Fargo's payment processing infrastructure is powered by Cybersource (a Visa company). The Flex Microform endpoint path and authentication scheme are identical to Cybersource's. The CreateClientAuthenticationToken flow creates a server-side Flex Microform v2 session that returns a capture_context JWT for client-side PCI-compliant card data collection.

---

2. Authentication

Scheme: HTTP Signature — HMAC-SHA256

Credentials Required

Field	Description
api_key	The Shared Secret Key ID (appears as keyid in the Signature header)
merchant_account	Merchant ID — sent as the v-c-merchant-id header
api_secret	Base64-encoded HMAC-SHA256 secret key used to sign the canonical string

Signature Construction

1. Canonical string (newline-separated):

   host: {host}
   date: {RFC 7231 date}
   (request-target): post /microform/v2/sessions
   digest: SHA-256={base64(sha256(request_body))}
   v-c-merchant-id: {merchant_account}
   

2. HMAC-SHA256: sign canonical string with base64decode(api_secret) using HMAC-SHA256.
3. Encode: base64-encode the raw HMAC

Out of Scope

Not specified in techspec

Technical Constraints

• Follow existing connector patterns in the codebase

---

Full Tech Spec

Wellsfargo CreateClientAuthenticationToken — Technical Specification

CONNECTOR: Wellsfargo
FLOW: CreateClientAuthenticationToken
STATUS: SUCCESS
TECHSPEC_PATH: techspecs/Wellsfargo_CreateClientAuthenticationToken_spec.md
REASON:

---

1. Connector Profile

Field	Value
Connector name	Wellsfargo
Primary flow scope	CreateClientAuthenticationToken (Flex Microform SDK session)
API family	Cybersource REST API (Wells Fargo uses Cybersource backend infrastructure)
Production host	https://api.cybersource.com
Sandbox host	https://apitest.cybersource.com
Regional hosts	None (single global endpoint)
API version	microform/v2
Content-Type (request)	application/json;charset=utf-8
Content-Type (response)	application/jwt (raw JWT string)

Wells Fargo's payment processing infrastructure is powered by Cybersource (a Visa company). The Flex Microform endpoint path and authentication scheme are identical to Cybersource's. The CreateClientAuthenticationToken flow creates a server-side Flex Microform v2 session that returns a capture_context JWT for client-side PCI-compliant card data collection.

---

2. Authentication

Scheme: HTTP Signature — HMAC-SHA256

Credentials Required

Field	Description
api_key	The Shared Secret Key ID (appears as keyid in the Signature header)
merchant_account	Merchant ID — sent as the v-c-merchant-id header
api_secret	Base64-encoded HMAC-SHA256 secret key used to sign the canonical string

Signature Construction

1. Canonical string (newline-separated):

   host: {host}
   date: {RFC 7231 date}
   (request-target): post /microform/v2/sessions
   digest: SHA-256={base64(sha256(request_body))}
   v-c-merchant-id: {merchant_account}
   

2. HMAC-SHA256: sign canonical string with base64decode(api_secret) using HMAC-SHA256.
3. Encode: base64-encode the raw HMAC bytes → signature_value.
4. Header value:

   keyid="{api_key}", algorithm="HmacSHA256", headers="host date (request-target) digest v-c-merchant-id", signature="{signature_value}"
   

Required Headers

Header	Value
Content-Type	application/json;charset=utf-8
Accept	application/hal+json;charset=utf-8
v-c-merchant-id	{merchant_account}
Date	RFC 7231 UTC date string (e.g. Thu, 14 May 2026 10:00:00 GMT)
Host	apitest.cybersource.com (sandbox) or api.cybersource.com (production)
Signature	Constructed as above
Digest	SHA-256={base64(sha256(body))} — required on POST/PATCH

Implementation notes:

• The api_secret stored in config is base64-encoded; it must be base64-decoded before use as the HMAC key.
• The Digest header is required for POST requests only.
• The date used in the signature must match the Date header exactly.
• Accept should be application/hal+json;charset=utf-8 (existing Wellsfargo convention).

---

3. Supported Flows

Flow	HTTP	Path	Notes
CreateClientAuthenticationToken	POST	/microform/v2/sessions	Returns raw JWT (capture_context) for Flex Microform SDK initialization
Authorize	POST	/pts/v2/payments/	Card authorization
Capture	POST	/pts/v2/payments/{id}/captures	Post-authorization capture
Void	POST	/pts/v2/payments/{id}/reversals	Authorization reversal
Refund	POST	/pts/v2/payments/{id}/refunds	Post-capture refund
PSync	GET	/pts/v2/payments/{id}	Payment status sync
RSync	GET	/tss/v2/transactions/{id}	Refund status sync via TSS
SetupMandate	POST	/pts/v2/payments/	Zero-amount mandate setup with TOKEN_CREATE action
Webhooks	N/A	N/A	Not currently implemented

Scope of this spec: CreateClientAuthenticationToken only.

---

4. Request Schema Highlights

Endpoint

POST {base_url}microform/v2/sessions

Request Body

{
  "targetOrigins": ["https://your-merchant-site.com"],
  "clientVersion": "0.11",
  "allowedCardNetworks": ["VISA", "MASTERCARD", "AMEX", "DISCOVER"],
  "fields": {
    "paymentInformation": {
      "card": {
        "number": {},
        "securityCode": {}
      }
    }
  }
}

Field Reference

Field	Type	Required	Notes
targetOrigins	string[]	Required	Array of allowed origins for the Flex Microform. Derived from the merchant's return_url scheme+host. Must exactly match the page origin where Flex Microform is rendered.
clientVersion	string	Required	Flex Microform library version string. Use "0.11".
allowedCardNetworks	string[]	Optional	Networks to accept. Values: VISA, MASTERCARD, AMEX, DISCOVER. Omit to accept all.
fields	object	Required	Declares which tokenization fields are exposed in the microform UI. Standard value enables number and securityCode capture.

Idempotency

• No idempotency key required for this endpoint (session tokens are short-lived, ~15 minutes).
• Each call generates a new capture_context; duplicate calls are safe.

Source of targetOrigins

• Extracted from PaymentFlowData.return_url: parse scheme + host (e.g., https://merchant.com).
• The Flex Microform JS will enforce the origin matches; mismatch causes client-side errors.

---

5. Response Schema Highlights

Content-Type

The /microform/v2/sessions endpoint returns a raw JWT string with Content-Type: application/jwt, NOT a JSON object.

Raw Response

eyJhbGciOiJSUzI1NiIsImtpZCI6InpVYzJ...{base64url-encoded JWT}

JWT Structure

The raw JWT body is the capture_context. Its decoded payload (base64url decode middle segment) contains:

Claim	Description
iss	Issuer (Flex API)
exp	Expiry timestamp (epoch, typically ~15 min from issue)
iat	Issued-at timestamp
jti	JWT ID — unique token identifier
ctx	Array of context objects; includes data.clientLibrary (URL to Flex Microform JS) and data.clientLibraryIntegrity (SRI hash)
flx	Flex-specific metadata (version, key-id, nonce)

Mapped Response in UCS

UCS Field	Source
capture_context	The entire raw JWT string (stored as Secret<String>)
client_library	Extracted from JWT payload ctx[].data.clientLibrary
client_library_integrity	Extracted from JWT payload ctx[].data.clientLibraryIntegrity

Deserialization Strategy

• The response body must be read as raw bytes and treated as a plain string (not JSON-decoded).
• UCS uses a custom Deserialize implementation that handles both:
  1. Raw string responses (standard Flex v2)
  2. JSON object responses with keyId field (legacy/alternative format)
• Both forms return the JWT in capture_context.

---

6. Error Handling

HTTP	status / Error Field	Cause
400	INVALID_DATA	Malformed request — missing targetOrigins, bad clientVersion, or invalid JSON
401	Authentication error (response.rmsg)	Invalid or missing HMAC signature; expired Date header (clock skew > 15 min); wrong api_key/api_secret
403	FORBIDDEN	Merchant account does not have Flex Microform enabled; IP allowlist violation
404	NOT_FOUND	Incorrect URL path
500	SERVER_ERROR	Transient Cybersource/Wellsfargo backend error — retry with backoff
503	SERVICE_UNAVAILABLE	Platform unavailable — retry with exponential backoff

Error Response Shapes

Authentication error (401):

{ "response": { "rmsg": "Authentication failed" } }

Standard error (4xx/5xx):

{
  "id": "<transaction-id>",
  "status": "INVALID_DATA",
  "message": "Decline - Invalid data",
  "reason": "MISSING_FIELD",
  "details": [
    { "field": "targetOrigins", "reason": "MISSING_FIELD" }
  ]
}

Not-available error:

{
  "id": "<transaction-id>",
  "errors": [
    { "type": "not_available", "message": "Service temporarily unavailable" }
  ]
}

---

7. Webhooks / Async Notifications

Attribute	Detail
Subscription	Not applicable to Flex Microform session creation
Delivery format	N/A
Verification	N/A
Retry policy	N/A
Documented gaps	Webhooks are not emitted for session creation. The capture_context JWT has its own expiry (typically 15 minutes). No async callback is defined for this flow.

The CreateClientAuthenticationToken flow is fully synchronous: the capture_context JWT is returned in the HTTP response body. No webhook subscription or callback URL is needed.

Webhook support for downstream payment events (authorization, capture, refund) is a separate concern handled by the Wellsfargo notification service, which is not yet implemented in UCS.

---

8. References

All documentation inferred from Cybersource API documentation (Wellsfargo uses the same Cybersource backend) and confirmed against the existing UCS Wellsfargo/Cybersource connector implementation:

Source	URL
Cybersource Flex Microform v2 Integration Guide	https://developer.cybersource.com/docs/cybs/en-us/digital-accept-flex/developer/all/rest/digital-accept-flex/microform-integ-v2.html
Cybersource REST API Reference — Sessions	https://developer.cybersource.com/api-reference-assets/index_v2.html#microform-integration_create-a-session
Cybersource HTTP Signature Authentication	https://developer.cybersource.com/api/developer-guides/dita-gettingstarted/authentication/httpSignatureAuthentication.html
Wells Fargo Developer Portal (uses Cybersource APIs)	https://developer.wellsfargo.com/
UCS Wellsfargo connector implementation	crates/integrations/connector-integration/src/connectors/wellsfargo.rs
UCS Cybersource reference implementation	crates/integrations/connector-integration/src/connectors/cybersource.rs