jobs

Create or top-up a buyer-funded envelope (canonical of /envelopes alias)

This is the canonical envelope-creation endpoint. The /envelopes path (documented above) is a Next.js rewrite alias to this URL; both serve the same handler. New external integrators may use either path.

See /envelopes for the full request body + response schema

  • idempotency + top-up semantics. The two entries exist so the spec-coverage drift-immunity test (PR 65) can verify both URLs resolve to the same route file.
post/escrow/envelopes

Request

  • Base URL: https://pact0.com/api/v1
  • URL: https://pact0.com/api/v1/escrow/envelopes
  • Auth: API key in cookie authjs.session-token

Request body

amount_minorinteger required

Money in micro-units. 1 USD = 1,000,000 micro.

WARNING — do not confuse with cents. Every *_minor field in this spec uses this convention, NOT the Stripe-style minor-currency-unit (cents) convention. Misreading the suffix as cents and multiplying by 100 yields a 10,000× misposting.

Conversion examples:

  • $0.05 (the test-pool fixture price) is 5_000_000 ÷ 100 = 50_000
  • $1.00 (the minimum buyer envelope) is 1_000_000
  • $5.00 (the dispute stake floor) is 5_000_000
  • $50.00 (the dispute stake ceiling) is 50_000_000
  • $5,000.00 (the maximum buyer envelope) is 5_000_000_000

Conversion to Stripe's cents (÷10,000, round down) happens only at the API boundary in the platform's wallet-backend implementations. Clients never invert this.

The _usd twin. On job, claim and balance responses every <base>_minor / <base>_micro field has a <base>_usd sibling: the same amount in US dollars, as a number (amount_minor: 50000 → amount_usd: 0.05). Read the twin; do arithmetic on the integer.

Trio v8 §4.2 (2026-05-26): added because a REST-only buyer reading bare { type: integer, format: int64 } schemas could plausibly assume cents. The bounds on POST /escrow/envelopes (minimum: 1000000, maximum: 5000000000) cap the worst-case misposting but do not close the confusion vector; surfacing the convention at every field site does.

currency'USD'
noncestring required
expires_in_daysinteger
topup_envelope_idstring

Response

OK — see /envelopes

successtrue

Changes

No recorded changes to this operation across all 2 revisions of this API.