[Tech Spec] Wellsfargo — CreateClientAuthenticationToken

# Wellsfargo — CreateClientAuthenticationToken

**Complexity:** low
**Generated by:** Grace pipeline run `run-2026-05-13T09-42-39-016Z-f7d82b`

## Summary

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

## Scope

# Technical Specification — Wellsfargo: CreateClientAuthenticationToken

## 1. Connector Profile

| Field | Value |
|---|---|
| Connector Name | Wellsfargo |
| Primary Flow Scope | CreateClientAuthenticationToken (SDK Capture Context) |
| API Family | CyberSource REST API — Flex Microform v2 |
| Production Host | `https://api.cybersource.com` |
| Sandbox Host | `https://apitest.cybersource.com` |
| Content-Type | `application/json` (request) / `application/jwt` or `application/json` (response) |

Wells Fargo's payment processing backend is built on the CyberSource platform. The `CreateClientAuthenticationToken` flow calls the CyberSource **Flex Microform v2 Sessions** endpoint to obtain a short-lived JWT *capture context* that initialises the Flex Microform JavaScript SDK on the client side, enabling PCI-descoped card tokenisation in the browser.

---

## 2. Authentication

| Attribute | Value |
|---|---|
| Scheme | HTTP Signature — HMAC-SHA256 |
| Credentials | `api_key` (Key Serial Number), `api_secret` (Base64-encoded shared secret), `merchant_account` (Merchant ID) |
| Signed Headers (POST) | `host`, `date`, `(request-target)`, `digest`, `v-c-merchant-id` |
| Signature Header Format | `keyid="{api_key}", algorithm="HmacSHA256", headers="host date (request-target) digest v-c-merchant-id", signature="{base64_hmac}"` |
| Digest Header | `SHA-256={base64(sha256(request_body))}` (omitted for GET) |
| Date Format | RFC 1123 (e.g. `Thu, 13 May 2026 09:00:00 GMT`) via `v-c-date` / `date` header |

**Implementation notes**:
- Decode the `api_secret` from Base64 before using it as the HMAC key.
- The `(request-target)` line must match the exact resource path including leading slash; trailing slashes matter.
- HTTP Signature is **scheduled for deprecation in September 2026**; CyberSource requires migration to JWT-based authentication (Message-Level Encryption) by that date.
- For the Flex Microform session endpoint, the connector currently uses HTTP Signature identical to

## Out of Scope

Not specified in techspec

## Technical Constraints

- Follow existing connector patterns in the codebase

---

## Full Tech Spec

# Technical Specification — Wellsfargo: CreateClientAuthenticationToken

## 1. Connector Profile

| Field | Value |
|---|---|
| Connector Name | Wellsfargo |
| Primary Flow Scope | CreateClientAuthenticationToken (SDK Capture Context) |
| API Family | CyberSource REST API — Flex Microform v2 |
| Production Host | `https://api.cybersource.com` |
| Sandbox Host | `https://apitest.cybersource.com` |
| Content-Type | `application/json` (request) / `application/jwt` or `application/json` (response) |

Wells Fargo's payment processing backend is built on the CyberSource platform. The `CreateClientAuthenticationToken` flow calls the CyberSource **Flex Microform v2 Sessions** endpoint to obtain a short-lived JWT *capture context* that initialises the Flex Microform JavaScript SDK on the client side, enabling PCI-descoped card tokenisation in the browser.

---

## 2. Authentication

| Attribute | Value |
|---|---|
| Scheme | HTTP Signature — HMAC-SHA256 |
| Credentials | `api_key` (Key Serial Number), `api_secret` (Base64-encoded shared secret), `merchant_account` (Merchant ID) |
| Signed Headers (POST) | `host`, `date`, `(request-target)`, `digest`, `v-c-merchant-id` |
| Signature Header Format | `keyid="{api_key}", algorithm="HmacSHA256", headers="host date (request-target) digest v-c-merchant-id", signature="{base64_hmac}"` |
| Digest Header | `SHA-256={base64(sha256(request_body))}` (omitted for GET) |
| Date Format | RFC 1123 (e.g. `Thu, 13 May 2026 09:00:00 GMT`) via `v-c-date` / `date` header |

**Implementation notes**:
- Decode the `api_secret` from Base64 before using it as the HMAC key.
- The `(request-target)` line must match the exact resource path including leading slash; trailing slashes matter.
- HTTP Signature is **scheduled for deprecation in September 2026**; CyberSource requires migration to JWT-based authentication (Message-Level Encryption) by that date.
- For the Flex Microform session endpoint, the connector currently uses HTTP Signature identical to all other Wellsfargo flows.

---

## 3. Supported Flows

| Flow | HTTP | Path | Notes |
|---|---|---|---|
| **CreateClientAuthenticationToken** | POST | `/microform/v2/sessions` | Returns JWT capture context for Flex Microform SDK. Response `Content-Type: application/jwt` (raw JWT string) or `application/json` with `captureContext` field. |
| Authorize | POST | `/pts/v2/payments` | Card authorization |
| Capture | POST | `/pts/v2/payments/{id}/captures` | Capture a previously authorized payment |
| Void | POST | `/pts/v2/payments/{id}/voids` | Void an authorized payment |
| Refund | POST | `/pts/v2/refunds/payments/{id}` | Refund a captured payment |
| PSync | GET | `/pts/v2/payments/{id}` | Retrieve payment status |
| RSync | GET | `/pts/v2/refunds/{id}` | Retrieve refund status |
| SetupMandate | POST | `/pts/v2/payments` | Zero-amount mandate setup |

---

## 4. Request Schema Highlights — CreateClientAuthenticationToken

**Endpoint**: `POST /microform/v2/sessions`

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

| Field | Type | Required | Notes |
|---|---|---|---|
| `targetOrigins` | `string[]` | **Yes** | HTTPS origins allowed to load the Flex Microform. Up to 9 entries. Wildcards NOT supported — subdomains must be listed explicitly. Derived from `return_url` origin in the UCS `ClientAuthenticationTokenRequestData`. |
| `clientVersion` | `string` | **Yes** | Fixed as `"0.11"` in the current implementation. |
| `allowedCardNetworks` | `string[]` | Conditional | Required if accepting cards. Supported values: `VISA`, `MASTERCARD`, `AMEX`, `DISCOVER`, `MAESTRO`, `DINERSCLUB`, `JCB`, `CUP`, `CARTESBANCAIRES`. |
| `fields` | `object` | No | Declares which card data fields are tokenised (e.g. `paymentInformation.card.number`, `paymentInformation.card.securityCode`). Constrains what the Flex SDK collects on the client. |
| `transientTokenResponseOptions.includeCardPrefix` | `boolean` | No | `true` → 8-digit prefix in transient token; `false` → no prefix; omit → 6-digit prefix (PCI DSS constrained). |

**Idempotency**: No idempotency key required. Each call produces a new, single-use JWT.

---

## 5. Response Schema Highlights

The response has two possible content types:

### Case A — Raw JWT (Content-Type: `application/jwt`)

The response body is the capture context JWT string directly. The JWT has three Base64URL-encoded segments (`header.payload.signature`).

**Decoded JWT Payload Fields**:

| Field | Type | Notes |
|---|---|---|
| `jti` | `string` | Unique JWT identifier for this session. |
| `iat` | `integer` | Issued-at Unix timestamp. |
| `exp` | `integer` | Expiration Unix timestamp (short-lived; typically minutes). |
| `iss` | `string` | `"Flex API"` |
| `ctx[].data.clientLibrary` | `string` | URL of the Flex Microform JavaScript SDK to load. |
| `ctx[].data.clientLibraryIntegrity` | `string` | SRI hash for SDK integrity verification. |
| `ctx[].data.allowedCardNetworks` | `string[]` | Card networks permitted in this session. |
| `ctx[].data.targetOrigins` | `string[]` | Origins allowed for Flex Microform. |
| `flx.path` | `string` | Tokenisation endpoint path (used by Flex SDK internally). |
| `flx.data` | `string` | Encrypted payload for secure transmission. |
| `flx.jwk` | `object` | RSA public key (`kty: "RSA"`, `use: "enc"`) for client-side encryption. |
| `flx.origin` | `string` | CyberSource Flex origin. |

### Case B — JSON Object (Content-Type: `application/json`)

```json
{
"captureContext": ""
}
```

The implementation extracts `captureContext` from the JSON, then decodes the JWT payload to obtain `clientLibrary` and `clientLibraryIntegrity` from `ctx[0].data`.

**Mapped UCS Response** (`ClientAuthenticationTokenData::ConnectorSpecific`):
- `capture_context`: The full JWT string (masked/secret).
- `client_library`: SDK URL from JWT payload.
- `client_library_integrity`: SRI hash from JWT payload.

---

## 6. Error Handling

| HTTP | `status` / structure | Cause |
|---|---|---|
| 400 | `{ errorInformation: { reason, message, details: [{field, reason}] } }` | Malformed request — invalid `targetOrigins`, unsupported `allowedCardNetworks` value, missing required field |
| 401 | `{ response: { rmsg } }` | Authentication failure — invalid `api_key`, bad HMAC signature, clock skew on `date` header |
| 404 | `{ errors: [{ type, message }] }` | Endpoint not available / merchant not provisioned for Flex Microform |
| 5xx | CyberSource gateway error | Upstream outage; retry with backoff |

**UCS Error Response Mapping**:
- `AuthenticationError` variant: 401 responses with `response.rmsg` as `error_message`.
- `StandardError` variant: `errorInformation.reason` as `error_code`, `errorInformation.message` as `error_message`.
- `NotAvailableError` variant: `errors[0].type` as `error_code`, `errors[0].message` as `error_message`.

---

## 7. Webhooks / Async Notifications

Not applicable for the `CreateClientAuthenticationToken` flow. This is a synchronous token-generation endpoint — the capture context JWT is returned in the HTTP response body with no async callback.

Webhooks are available for downstream payment events (authorisation, capture, refund outcomes) on the Wellsfargo platform but are outside the scope of this flow.

---

## 8. References

1. [Flex Capture Context API Introduction (Microform v2)](https://developer.cybersource.com/docs/cybs/en-us/digital-accept-flex/developer/all/rest/digital-accept-flex/microform-integ-v2/micro-v2-reference/flex-capture-context-api-intro.html)
2. [Flex API v2 — Generate Capture Context](https://developer.cybersource.com/docs/cybs/en-us/digital-accept-flex/developer/all/rest/digital-accept-flex/flex-api-2/flex-api-2-generate-capture-context.html)
3. [CyberSource REST Getting Started](https://developer.cybersource.com/docs/cybs/en-us/platform/developer/all/rest/rest-getting-started/restgs-intro.html)
4. [HTTP Signature Messaging (Deprecating September 2026)](https://developer.cybersource.com/docs/cybs/en-us/platform/developer/all/rest/rest-getting-started/restgs-http-message-intro/restgs-http-message-conf-intro.html)
5. [CyberSource API Reference](https://developer.cybersource.com/api-reference-assets/index.html)