Skip to content

Transactions API

CertusOrdo's Key Differentiator

Transaction rollback is what competitors don't offer.

Begin Transaction

Starts a transaction and captures pre-state.

POST /transactions/begin

Headers

Header Required Description
Authorization Yes Bearer JWT token

Request

{
  "pre_state": {
    "account_id": "ACC001",
    "balance": 1000.00
  },
  "action_type": "transfer_funds",
  "session_id": "f2cc7759-b324-4a4c-943a-cf5a3e090061",
  "rollback_confidence": "guaranteed"
}
Field Required Description
pre_state Yes State snapshot before action
action_type Yes Category of action
session_id No Link to session
rollback_confidence No guaranteed, high, medium, low, irreversible

Response

{
  "id": "txn-uuid",
  "agent_id": "agent-uuid",
  "session_id": "session-uuid",
  "sequence_number": 1,
  "action_type": "transfer_funds",
  "pre_state_snapshot": {
    "account_id": "ACC001",
    "balance": 1000.00
  },
  "status": "pending",
  "rollback_confidence": "guaranteed",
  "created_at": "2025-01-16T14:30:00Z"
}

Example

txn = client.transactions.begin(
    pre_state={"account_id": "ACC001", "balance": 1000.00},
    action_type="transfer_funds"
)

curl -X POST \
  -H "Authorization: Bearer eyJhbG..." \
  -H "Content-Type: application/json" \
  -d '{"pre_state": {"balance": 1000}, "action_type": "transfer"}' \
  https://web-production-b910f.up.railway.app/transactions/begin

Commit Transaction

Completes a transaction and captures post-state.

POST /transactions/{id}/commit

Request

{
  "post_state": {
    "account_id": "ACC001",
    "balance": 750.00
  }
}

Response

{
  "id": "txn-uuid",
  "status": "completed",
  "pre_state_snapshot": {
    "account_id": "ACC001",
    "balance": 1000.00
  },
  "post_state_snapshot": {
    "account_id": "ACC001",
    "balance": 750.00
  },
  "completed_at": "2025-01-16T14:31:00Z"
}

Rollback Transaction

THE MOAT

This is what competitors don't offer.

Reverses a transaction and returns the pre-state.

POST /transactions/{id}/rollback

Request

{
  "reason": "Transfer failed - destination account frozen"
}

Response

{
  "id": "txn-uuid",
  "status": "rolled_back",
  "pre_state_snapshot": {
    "account_id": "ACC001",
    "balance": 1000.00
  },
  "rollback_reason": "Transfer failed - destination account frozen",
  "rolled_back_at": "2025-01-16T14:32:00Z"
}

Use pre_state_snapshot to restore your system to its original state.

Example

rollback = client.transactions.rollback(
    txn.id,
    reason="Payment gateway timeout"
)

# Restore your system
original_state = rollback.pre_state_snapshot
restore_account(original_state)

curl -X POST \
  -H "Authorization: Bearer eyJhbG..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "Error occurred"}' \
  https://web-production-b910f.up.railway.app/transactions/txn-uuid/rollback

List Transactions

GET /transactions

Query Parameters

Parameter Type Description
status string pending, completed, failed, rolled_back
session_id UUID Filter by session
agent_id UUID Filter by agent

Get Transaction

GET /transactions/{id}

Returns full transaction details including pre/post state snapshots.

List Rollbackable Transactions

GET /transactions/rollbackable

Returns transactions that can still be rolled back.