# GOAT Network Gift Cards

> Choose an exact source offer, review its native face value and USD price, create a Flow payment instruction and track private delivery.

This release exposes 14 local gift-card actions and has no coupon purchase or
management capability. Use current API schemas, never remembered supplier prices.
Catalog presence, successful quote and checkout eligibility are distinct states.
Region purchasable is deprecated discovery metadata, not a blanket purchase gate.

## Contracts

- [Purchase guide](/gift-cards.md): source identity, authentication, quote, confirmation, payment and delivery.
- [Manifest](https://giftcard-api.goat.network/api/v1/manifest): runtime identity and namespace.
- [Actions](https://giftcard-api.goat.network/api/v1/actions): action input/output schemas.
- [OpenAPI](https://giftcard-api.goat.network/api/v1/openapi.json): HTTP and wallet authentication.
- [Canonical regions](https://giftcard-api.goat.network/api/v1/catalog/regions): reviewed redemption destinations.
- [Payment tokens](https://giftcard-api.goat.network/api/v1/supported-tokens): exact live enabled tuples.

Ask explicitly where to redeem; WW/GLC labels do not prove worldwide coverage.
Keep source product, source country, currency and amount unchanged. Honor amount
checking states and retry timing. A temporary failure is not proof of sold-out stock.

Authenticate the intended wallet, call orders.quote for a positive native amount,
and confirm country, face value and exact pay_amount_usd. Both suppliers use this
path. Pass the reviewed USD total as expected_pay_amount_usd to orders.create.
QUOTE_CHANGED requires a new review. Never relabel a native amount as USD/USDT.

Persist one idempotency key (1–128 characters) before creation and reuse it during
recovery. CREATED cannot be paid. GET /supported-tokens selects the payment mode:
an absent checkout_mode means inpage; checkout_mode="hosted" means a person must
open the returned checkout_url. For inpage, validate the entire returned instruction
and at least 30 seconds remaining before separately approving the wallet transfer.
For hosted, validate checkout_url against the configured GOAT Flow origin, require
its cs query to equal checkout_id, present it as human_action_required, and poll the
same order. Chain and token are chosen by the person on GOAT Flow; never log or
replace the bearer checkout handle, and never create a second session to resume.
Hosted requires PAYMENT_PENDING, at least 30 seconds before order/session expiry,
and the approved pay_amount_usd (rounded upward to cents). The local plugin
2.0.0-rc.2 uses checkoutOrigin; CLI uses --checkout-origin or
GIFT_CLI_CHECKOUT_ORIGIN, default https://flow-quickpay.goat.network. Valid payable
results add next_action="open checkout_url, then poll orders.get"; terminal or
capability-free reads never prompt payment. CLI --checkout-mode auto|inpage
(default auto) follows server mode unless explicitly requesting inpage. Send
checkout_mode="inpage" on both quote and create only when the server allows it
(flow.allow_inpage_requests); rejection must stop, never silently switch modes.
Hosted payer may differ from owner: card access remains owner-only, refunds go
to the recorded payer. Hosted CLI table output polls every five seconds by
default; --wait=false opts out, JSON stays one-shot, and inpage needs --wait.
No CLI/plugin path broadcasts funds.
The local plugin does not transfer funds. The official AgentKit wallet integration
requires separate acceptance, including persistent cross-process payment exclusion.
Never automatically repeat an uncertain broadcast. Hosted callback success is only
a navigation signal, not proof of payment. EXPIRED orders can recover a late payment
for five minutes; do not create replacements during reconciliation.

Poll delivery/refund states with bounds. A transaction hash is not fulfillment or
refund confirmation. Card secrets are private to the authenticated owner; never
log them or retain them across wallet/session changes.

Legacy coupons/capabilities always returns enabled=false. Authenticated coupon
quotes and any explicit coupon_code in new orders are rejected with COUPONS_DISABLED.
Do not remove a code and retry at full price. Historical discounted orders remain
readable; their fields do not imply that new coupon purchases are supported.

## Batched discovery and English search

Use catalog.availability with face_values (array in Actions, comma-separated in
HTTP): up to 20 fixed or 5 variable values, with optional face_value priority from
that batch. Consume per-source states and display expiry; ready/check_required
means a browsing price exists but checkout needs a fresh orders.quote.
Respect retry_after_seconds, observe the initial batch for at most 120 seconds,
then stop; do not periodically refresh browsing prices.

Catalog search supports names, product titles, reviewed English aliases and
bounded typo matches. Inspect search_match and selection_required. Ask the buyer
to resolve approximate/ambiguous results; do not purchase the first fuzzy match
or merge redemption rights. Preserve the selected source, country, currency and
amount through quote, confirmation and idempotent order creation.

Agent availability inputs use distinct amounts: fixed arrays have at most 20 entries, variable arrays at most five. Deduplicate before calling; direct and schema-aware hosts reject duplicates, nonpositive/nonfinite amounts, values above 10,000,000, and more than two decimal places before transport. The legacy HTTP query still deduplicates repeated amounts for compatibility. Per-result availability rows expose singular `face_value`, not an array.