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 namestringHuman-readable name for the flow startstring (uuid)The id of the first node to execute nodesarrayList 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 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.
Pauses the flow and dispatches a CloudEvent to your processor integration. The flow resumes when your integration responds with a Finish event.
Unique identifier for this node.
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.
Evaluates the resultFinish 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 event’s result The node to route to when on matches.
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 TDS3D Secure redirect ManualCapturePayment requires a manual capture
The gateway node to route to after the requirement is signaled.
Seconds before the requirement is considered failed.
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 acceptedPayment has been accepted authorizedPayment has been authorized completedPayment has been completed failedPayment has failed
The node to route to after the state is set.
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
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. { "$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. { "$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" } } ] }
