[Tech Spec] Wellsfargo — CreateClientAuthenticationToken

# 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

```json
{
"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`) |
| `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)**:
```json
{ "response": { "rmsg": "Authentication failed" } }
```

**Standard error (4xx/5xx)**:
```json
{
"id": "",
"status": "INVALID_DATA",
"message": "Decline - Invalid data",
"reason": "MISSING_FIELD",
"details": [
{ "field": "targetOrigins", "reason": "MISSING_FIELD" }
]
}
```

**Not-available error**:
```json
{
"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 |