Payments API

Payments API

The goal of Payments API is to connect task budgets, funding state and payout release to verified completion. Its contract should make real-world uncertainty explicit while remaining familiar to engineers building software and agent workflows.

Budget object

A production treatment of Budget object needs both the normal path and the exception path. Human execution is reliable only when the client knows what happens when the environment does not match the request.

Funding a task

Funding a task is where the implementation should expose physical-world constraints rather than abstracting them away. If access, timing, identity or evidence changes the result, the schema should say so.

{
  "task_id": "task_123",
  "budget": {"amount": 75, "currency": "USD"},
  "funding_status": "authorized"
}

Authorization versus capture

Authorization versus capture should be documented as an explicit part of this interface. The caller needs to know which fields affect routing, which values are authoritative and which states can change after a human has accepted work.

{
  "task_id": "task_123",
  "budget": {"amount": 75, "currency": "USD"},
  "funding_status": "authorized"
}

Approval and revision

Approval and revision should be documented as an explicit part of this interface. The caller needs to know which fields affect routing, which values are authoritative and which states can change after a human has accepted work.

Worker payout state

For Worker payout state, prefer a small number of well-defined fields over free-form conventions. The physical worker may read natural-language instructions, but software should get structured values for anything that affects control flow.

Refund paths

Refund paths should be documented as an explicit part of this interface. The caller needs to know which fields affect routing, which values are authoritative and which states can change after a human has accepted work.

Spend controls

For Spend controls, prefer a small number of well-defined fields over free-form conventions. The physical worker may read natural-language instructions, but software should get structured values for anything that affects control flow.

Money Objects Need Precision

Amounts should include currency and integer minor units or another unambiguous representation. Avoid floating-point money fields. Budget, authorized amount, captured amount, refund and payout should be separate concepts.

Approval Policies

Some customers may auto-approve tasks that meet machine-checkable evidence rules; others may require a person to review. The payments interface should support both without coupling payout to one UI workflow.

Spend Governance

Projects can have per-task, daily or monthly limits. High-value tasks can require an approval token or a separate privileged action. These controls are essential if AI agents are allowed to initiate paid work.

Error Model

Model offline exceptions deliberately. The important question is not only whether a request was valid but whether the intended observation or action could occur under real conditions.

Production Readiness

Before production, test duplicate creation, cancellation, a blocked task, incomplete evidence, credential rotation and at least one repeated webhook.

Common Integration Mistake

Payment state should never be inferred from task status; execution and money movement are separate state machines.

Next Step

Implement one payments api flow against the canonical task lifecycle, inspect the real payloads and only then generalize the client for more capabilities or locations.

Implementation Notes for Payments API

Budget object

When implementing budget object for Payments API, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Funding a task

When implementing funding a task for Payments API, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Authorization versus capture

When implementing authorization versus capture for Payments API, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Approval and revision

When implementing approval and revision for Payments API, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Worker payout state

When implementing worker payout state for Payments API, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Refund paths

When implementing refund paths for Payments API, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Spend controls

When implementing spend controls for Payments API, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Test Matrix

A Payments API integration should be tested against more than the happy path. Include a valid request, invalid input, duplicate retry, no matching supply, worker exception, incomplete evidence and cancellation where the interface supports it. The result of each test should be observable in the canonical task object so developers can reconcile UI, API and agent behavior.