> ## Documentation Index
> Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Flow Configuration
> Define the sequence of payment operations using the Commerce V1 flow specification.
Commerce V1 orchestrates payment processing through flow specifications — directed graphs of typed nodes connected by UUIDs. Each flow defines the operations, branching logic, and state transitions for a specific payment type such as a sale or refund.
## Flow structure
A flow is a JSON object with the following top-level fields:
| Field | Type | Description |
| ------- | --------------- | ------------------------------------------ |
| `name` | `string` | Human-readable name for the flow |
| `start` | `string (uuid)` | The `id` of the first node to execute |
| `nodes` | `array` | List of node objects that make up the flow |
Each node has a `type` and a `data` object. The fields in `data` differ by node type.
## Node types
### Start
Marks the entry point of the flow. Every flow must have exactly one start node, and the top-level `start` field must reference its `id`.
Unique identifier for this node.
The node to route to when the flow begins.
### Transaction
Pauses the flow and dispatches a CloudEvent to your processor integration. The flow resumes when your integration responds with a [Finish](/products/commerce/v1/eventing-reference/inbound/finish) event.
Unique identifier for this node.
The `ce-type` of the [Custom Transaction Event](/products/commerce/v1/eventing-reference/outbound/custom-transaction-event) sent to your integration.
A key passed to your integration to select which operation to perform.
Seconds before the transaction is considered failed.
The gateway node to route to after the transaction completes.
### Gateway
Evaluates the [`result`](/products/commerce/v1/eventing-reference/inbound/finish#param-result) from your integration's [Finish](/products/commerce/v1/eventing-reference/inbound/finish) event and routes the flow to the appropriate next node. If no rule matches, the flow execution fails.
Unique identifier for this node.
Routing rules evaluated against the [Finish](/products/commerce/v1/eventing-reference/inbound/finish) event's [`result`](/products/commerce/v1/eventing-reference/inbound/finish#param-result).
Result value to match.
The node to route to when `on` matches.
### Requirement
Signals that an external action must be completed before the flow can continue — for example, a 3DS authentication challenge presented to the cardholder. The flow pauses until it receives a confirmation event routed through the next gateway.
Unique identifier for this node.
The type of requirement to fulfill.
| Value | Description |
| --------------- | --------------------------------- |
| `TDS` | 3D Secure redirect |
| `ManualCapture` | Payment requires a manual capture |
The gateway node to route to after the requirement is signaled.
Seconds before the requirement is considered failed.
### Transition
Sets the flow's outcome state and then routes to the next node. Use this node to record whether a flow path ended in success or failure before reaching the end.
Unique identifier for this node.
The payment state to set. Allowed values:
| Value | Description |
| ------------ | --------------------------- |
| `accepted` | Payment has been accepted |
| `authorized` | Payment has been authorized |
| `completed` | Payment has been completed |
| `failed` | Payment has failed |
The node to route to after the state is set.
### End
Marks a terminal point in the flow. A flow can have multiple end nodes — for example, one per outcome path.
Unique identifier for this node.
## Schema
Download the JSON Schema (Draft 2020-12): [flow.schema.json](/static/flow.schema.json)
## Examples
The payment flow handles a card sale with optional 3DS v1 authentication. If the processor requires 3DS, the flow pauses for the cardholder challenge and then confirms authentication before completing the sale.
```json payment-flow.json theme={null}
{
"$schema": "https://developer.hellgate.io/static/flow.schema.json",
"name": "Payment",
"start": "1AC4F68E-85AA-4301-B250-AA95847118AF",
"nodes": [
{
"type": "start",
"data": {
"id": "1AC4F68E-85AA-4301-B250-AA95847118AF",
"next": "FDBE34A3-ADB1-47E5-803C-8F821F9A354D"
}
},
{
"type": "transaction",
"data": {
"configuration": "Configuration",
"id": "FDBE34A3-ADB1-47E5-803C-8F821F9A354D",
"startEventType": "Process Sale",
"next": "4E1DFC5F-0227-42DD-885D-AD637FD20A1E",
"timeOut": 600
}
},
{
"type": "gateway",
"data": {
"id": "4E1DFC5F-0227-42DD-885D-AD637FD20A1E",
"continuesWith": [
{
"to": "4EACEC4E-F7C6-4F65-822D-5BD53D19071F",
"on": "Sale Success"
},
{
"to": "A850F940-2FBD-431C-B58F-A55A0507C827",
"on": "Sale Failed"
},
{
"to": "8F7EB14C-F3E5-4743-A262-B47B1D1749F4",
"on": "Require 3DSv1"
}
]
}
},
{
"type": "requirement",
"data": {
"id": "8F7EB14C-F3E5-4743-A262-B47B1D1749F4",
"requires": "3DS_V1",
"next": "4BDE7A74-C503-4E91-8F88-F8489B7B38FB",
"timeOut": 600
}
},
{
"type": "gateway",
"data": {
"id": "4BDE7A74-C503-4E91-8F88-F8489B7B38FB",
"continuesWith": [
{
"to": "82A88E99-BD8D-42C1-9B74-B448EBA277D7",
"on": "CONFIRM_3DS_V1"
}
]
}
},
{
"type": "transaction",
"data": {
"configuration": "Configuration",
"id": "82A88E99-BD8D-42C1-9B74-B448EBA277D7",
"startEventType": "Confirm 3DSv1",
"next": "BFB5566B-4B38-496F-BCEE-E0A425A8917B",
"timeOut": 600
}
},
{
"type": "gateway",
"data": {
"id": "BFB5566B-4B38-496F-BCEE-E0A425A8917B",
"continuesWith": [
{
"to": "4EACEC4E-F7C6-4F65-822D-5BD53D19071F",
"on": "Sale Success"
},
{
"to": "A850F940-2FBD-431C-B58F-A55A0507C827",
"on": "Sale Failed"
}
]
}
},
{
"type": "transition",
"data": {
"id": "4EACEC4E-F7C6-4F65-822D-5BD53D19071F",
"next": "44E45CB8-6D12-430E-8A78-C9FBFB8E42C1",
"targetState": "Completed"
}
},
{
"type": "transition",
"data": {
"id": "A850F940-2FBD-431C-B58F-A55A0507C827",
"next": "44E45CB8-6D12-430E-8A78-C9FBFB8E42C1",
"targetState": "Failed"
}
},
{
"type": "end",
"data": {
"id": "44E45CB8-6D12-430E-8A78-C9FBFB8E42C1"
}
}
]
}
```
The refund flow handles a refund operation. Both success and failure outcomes route to the same end node.
```json refund-flow.json theme={null}
{
"$schema": "https://developer.hellgate.io/static/flow.schema.json",
"name": "refund",
"start": "4FA3D72D-7DBA-47DD-A21D-CE491B074D08",
"nodes": [
{
"type": "start",
"data": {
"id": "4FA3D72D-7DBA-47DD-A21D-CE491B074D08",
"next": "D8AE63DE-7467-45AE-AD6C-4DAD3D465237"
}
},
{
"type": "transaction",
"data": {
"configuration": "Configuration",
"id": "D8AE63DE-7467-45AE-AD6C-4DAD3D465237",
"startEventType": "Process Refund",
"next": "59576DDC-57BE-4153-8E9D-AE4D7B5CDBDB",
"timeOut": 600
}
},
{
"type": "gateway",
"data": {
"id": "59576DDC-57BE-4153-8E9D-AE4D7B5CDBDB",
"continuesWith": [
{
"to": "0E0171A2-DCCB-48D5-871F-534CCA6FB042",
"on": "Refund Success"
},
{
"to": "0E0171A2-DCCB-48D5-871F-534CCA6FB042",
"on": "Refund Failed"
}
]
}
},
{
"type": "end",
"data": {
"id": "0E0171A2-DCCB-48D5-871F-534CCA6FB042"
}
}
]
}
```