fulfillments

Create Fulfillment

Creates a payment intent — a "send" (sender defaults to the caller) or, when sender_user_id or sender_wallet names someone else, a "request" the caller becomes the receiver of. deadline is required RFC3339. memo is the join key to on-chain settlement: 409 memo_taken if it's already held by a live (pending/claimed/submitted) fulfillment in the tenant — omit it and the server mints one. 422 amount_over_limit if a DIRECT-tagged payment exceeds the per-payment cap (max_uoa/max_cents echoed in the error body).

idempotency_key (optional, 8..255 chars) — pass one if your client can retry. A second create with the same key in the same tenant returns the ORIGINAL fulfillment, same id, instead of minting a second payment. The key is durable for the row's whole life, so a retry that arrives after the original settled still resolves to it — that is the "response was lost, client retried" case. Without a key, behaviour is unchanged: every call creates a new payment intent. Note the counterparty notification fires only on the real create, never on a replay.

post/fulfillments

Request

  • Base URL: https://api.instruxi.dev/api/v1/enforcer
  • URL: https://api.instruxi.dev/api/v1/enforcer/fulfillments
  • Auth: API key in header Authorization

Request body

chain_idinteger
deadlinestring

RFC3339

expected_payer_walletstring

ExpectedPayerWallet restricts funding to ONE wallet: a settlement from any other payer will not confirm this fulfillment. Optional; omitted means anyone may pay it, which is the normal case. Use it when the payer is the point rather than a detail — a refund that must leave the merchant's settlement wallet.

expected_plan_hashstring
idempotency_keystring

IdempotencyKey de-duplicates this create. Optional, but strongly advised for any client that can retry: pass the same key and a second call returns the ORIGINAL fulfillment (200-shaped, same id) instead of minting a second payment. Unique per tenant, 8..255 chars, and durable for the row's whole life — a retry after the original settled still resolves to it.

max_fee_bpsinteger
memostring
notional_uoastring
receiver_user_idstring
receiver_walletstring
referencestring
refund_walletstring

RefundWallet is NOT settable here: a refund destination is chosen only by a trusted service at POST /service/fulfillments. Sending it on this route is refused (403 refund_wallet_service_only) rather than silently dropped.

request_tokenstring
sender_user_idstring

SenderUserID addresses the payer by account id — used by the "request" flow when the contact has no on-chain wallet on file. Optional: when unset, the sender defaults to the caller (the "send" flow). Mutually optional with sender_wallet.

sender_walletstring

Response

Created

successboolean

Example response

{
  "success": true
}

Changes

No recorded changes to this operation across all 1 revision of this API.