FlexFactor Authorization, Capture, and MIT Webhook Lifecycle

OpenPath now supports FlexFactor authorization and capture as separate
operations, including the asynchronous merchant-initiated transaction (MIT)
authorization lifecycle.

This update adds:

customer-initiated transaction (CIT) authorization and capture;
asynchronous MIT authorization;
signed order.capturerequired webhook processing;
order-inquiry recovery when a webhook is missed or an MIT result is
uncertain;
cancel-versus-refund routing for void requests;
an optional FlexFactor webhook signing secret in the OpenPath gateway
configuration UI.

There are no breaking changes to existing FlexFactor sale and refund
integrations. The provider continues to appear as FlexCharge in
client.openpath.io for compatibility with existing gateway records.

Availability requirement

FlexFactor must enable the authorize capability for the applicable sandbox
and production accounts. This capability is not enabled by default.

Before enabling authorization in production, run a credentialed sandbox
authorization and confirm that FlexFactor returns CAPTUREREQUIRED. An HTTP
200 response by itself does not confirm that authorization is enabled.

Rollout warning

Credentialed sandbox validation on an account that had not been confirmed as
authorize-enabled returned APPROVED, and order inquiry showed COMPLETED.
That is purchase-style behavior, not an authorization hold. Do not release
authorization/capture for an account until the same request returns
CAPTUREREQUIRED.

How the updated flow works

OpenPath operation	FlexFactor behavior	OpenPath result
Sale	Sends `transactionType: PURCHASE` to `/v1/evaluate`.	Continues through the existing purchase flow.
CIT Authorization	Sends `transactionType: AUTHORIZATION` to `/v1/evaluate`.	`CAPTUREREQUIRED` is treated as an approved authorization that is ready for capture.
MIT Authorization	Sends `transactionType: AUTHORIZATION` with MIT fields to `/v1/evaluate`.	`SUBMITTED` is stored as pending while OpenPath waits for `order.capturerequired`.
Capture	Sends the retained FlexFactor `orderId`, amount in cents, ISO currency, and an idempotency key to `/v1/capture`.	Completes the previously authorized transaction.
Void before capture	Resolves the original authorization and calls `/v1/orders/{orderId}/cancel`.	Cancels the uncaptured authorization.
Void after capture or sale	Resolves the original settled transaction and calls `/v1/orders/{orderId}/refund`.	Refunds the settled transaction.

OpenPath retains both orderId and orderSessionKey from FlexFactor.
orderId is the primary identifier for capture, cancel, refund, webhook
correlation, and order inquiry.

Asynchronous MIT authorization

OpenPath submits the MIT authorization to FlexFactor.
FlexFactor returns SUBMITTED.
OpenPath stores the transaction as pending and retains the FlexFactor
identifiers.
FlexFactor sends an order.capturerequired webhook.
OpenPath verifies the webhook signature and merchant ID, correlates the
event to one pending MIT authorization, and marks that authorization ready
for capture.
A later OpenPath capture uses the same retained FlexFactor orderId.

Webhook deliveries are processed idempotently. Replaying the same event, or
delivering a second capture-required event after the authorization is already
ready, does not apply the state transition twice.

Configure the FlexFactor gateway

Sign in to client.openpath.io.
Open the gateway/connector configuration that uses FlexCharge.
Confirm the existing FlexFactor values:
- Site ID
- API Secret
- API Key
- Merchant ID
- Tokenization Key
- Sandbox setting
Enter the Base64 subscriber key from the FlexFactor Merchant Portal in
Webhook Signing Secret (optional).
Save the gateway.

The signing-secret field is shown only when FlexCharge is selected and is
stored as a gateway attribute. It is masked in the UI.

The field is optional so existing gateways that do not use webhook-driven
flows can remain unchanged. It is functionally required for asynchronous MIT
authorization: OpenPath rejects webhook deliveries when the gateway has no
single, non-empty signing secret.

Create or update the FlexFactor webhook

Use a separate webhook endpoint for each OpenPath gateway because the gateway
ID selects the credentials, merchant ID, and signing secret used to validate
the event.

1. Find the OpenPath gateway ID

Open the FlexCharge gateway in client.openpath.io and note its numeric
gateway ID. Use that value as {gatewayId} below.

2. Set the callback URL

In the FlexFactor Merchant Portal, go to Developers > Webhooks and create
or edit the endpoint for the correct environment.

Use this HTTPS callback:

https://api.openpath.io/platform/webhook/flexfactor/{gatewayId}

3. Subscribe to the event

Select:

order.capturerequired

OpenPath acknowledges other validly signed FlexFactor events without changing
an authorization, but this release processes only order.capturerequired.

4. Save the subscriber key in OpenPath

Copy the Base64 subscriber key/signing secret from the FlexFactor Merchant
Portal and paste it into Webhook Signing Secret (optional) on the matching
FlexCharge gateway in client.openpath.io. Save the gateway.

Also confirm that the gateway's Merchant ID exactly matches the Mid
included in FlexFactor webhook payloads.

5. Test delivery

Send a sandbox event or complete a sandbox MIT authorization. A valid
order.capturerequired delivery should receive HTTP 200 promptly; OpenPath
queues the state transition for background processing.

OpenPath validates:

x-fc-authorization;
x-fc-nonce;
x-fc-date;
the optional x-fc-content-sha512 content hash when supplied;
the HMAC-SHA512 signature using the Base64 subscriber key;
the webhook Mid against the configured gateway Merchant ID;
the event IdempotencyKey;
correlation by FlexFactor and OpenPath order identifiers.

If inbound traffic is restricted, allow the current FlexFactor webhook source
IPs documented for the selected environment. IP filtering is defense in depth
and does not replace signature validation.

Rotate or replace the signing secret

OpenPath accepts one webhook signing secret per gateway.

Obtain or generate the replacement subscriber key in the FlexFactor
Merchant Portal.
Update Webhook Signing Secret (optional) on the matching OpenPath
gateway.
Save the gateway.
Activate or save the corresponding FlexFactor webhook endpoint.
Send a test event and confirm HTTP 200.

Coordinate steps 2 through 4 closely. Deliveries signed with the old key will
return HTTP 401 after OpenPath is updated, while deliveries signed with the
new key will return HTTP 401 until OpenPath is updated.

Never place the subscriber key in a callback URL, request payload, log message,
ticket, or release note.

Recover a missed MIT webhook

An authenticated operational endpoint can enqueue an order inquiry for a
pending MIT authorization:

POST /platform/flexfactor/gateways/{gatewayId}/authorizations/{transactionId}/recover
Authorization: Bearer <openpath-access-token>

The endpoint returns HTTP 202 with a background job ID. OpenPath retrieves
the current FlexFactor order using the retained orderId.

Draft, Onhold, or Processing remains pending.
Capturerequired marks the authorization ready for capture.
Terminal states that do not require capture do not approve the
authorization.

Recovery is safe to invoke more than once. It does not capture, cancel, or
refund the order.

Operational responses

HTTP response	Meaning
`200`	The webhook was authenticated and acknowledged. Target events are queued for processing.
`202`	A recovery inquiry was accepted and queued.
`400`	The webhook body is malformed or missing required event metadata.
`401`	Required signature headers are missing, the signature is invalid, or the webhook merchant ID does not match the gateway.
`404`	The gateway does not exist or is not a FlexFactor/FlexCharge gateway.
`500`	The gateway has no single usable webhook signing secret.

Monitor pending MIT authorizations, webhook authentication failures,
uncorrelated events, duplicate events, order-inquiry results, and the elapsed
time between SUBMITTED and CAPTUREREQUIRED.

Compatibility and scope

Existing FlexFactor Sale and Refund behavior remains supported.
Existing FlexCharge provider names and gateway records do not need to be
renamed.
Sandbox defaults to https://api-sandbox.flexfactor.io/v1.
Production defaults to https://api.flexfactor.io/v1.
Explicit legacy base URL overrides remain supported during migration.
This release does not send transaction copies to /transmit.

FlexFactor Auth, Capture