v1

Changelog

A dated record of changes to the v1 API and these docs, newest first.

  1. Add Funds embed redesign

    • The hosted Add Funds iframe has a new dark look to match the updated app designs: current wallet balance on the amount screen, radio-style payment method selection with a Continue confirmation, and a live card preview on Add Card that mirrors the detected brand, last four, and expiry as the fan types. Card capture behavior is unchanged — the card number and CVC never leave the tokenization iframes. No integration changes required; the embed URL and parameters are the same. See the Embed tab for the updated preview.
    • Add Card now collects an optional billing ZIP and forwards it to the payment processor for AVS verification.

  2. Simulate card transactions

    • New Simulate tab: drive the card-spend earn flow end to end without a live card or a real Ansa delivery. Pick a cardholder, simulate an authorization at any merchant, then settle it — the synthetic event runs the same handlers a real Ansa webhook would, so you can watch pending points become available, verify sponsor theming and multipliers, and exercise your points.pending receiver. Sandbox only.

  3. List wallet payment methods

    • GET /v1/users/{userId}/wallet/payment-methods returns the display-safe funding sources attached to a wallet — brand, last four, and expiry per card, plus which is preferred. Use it to show saved cards before prompting a load. See Docs → Wallet.

  4. Merchant location on card-spend earns

    • Card-spend point events now include the merchant city and state where the fan spent — populated from the card transaction, absent when the event carries no location. Use it to show or group earns by where the fan spent. See the points event shape under Docs → Points.

  5. Card-spend earning

    • Card-spend point events now include a sponsorId when the merchant matches a sponsor, so you can theme Tokens by where the fan spent. See the points event shape under Docs → Points.
    • Card taps now earn pending points that become available (redeemable) once the charge settles — credited at the amount that actually settled, so a tip or partial capture adjusts the award and a fully reversed charge earns none. The points balance now returns both currentBalance (available) and pendingBalance (estimated from authorization); pending points can't be redeemed. See Docs → Points balance.
    • Uptop now POSTs a points.pending event the moment a fan earns, so your app updates without polling. Setup, payload, signature verification, and a test-fire tool are on the new Webhooks tab.

  6. Free-form reward tags

    • Rewards now carry an optional tags[] array for editorial grouping (e.g. edc-exclusive, summer-drop) beyond the fixed type — surfaced on the v1 reward shape.

  7. Expand reward on auctions

    • GET /v1/auctions?expand=reward inlines the full reward object on each auction row, removing the extra per-item call your storefront used to make.

  8. Phone number on upsert

    • POST /v1/users:upsert accepts phoneNumber (E.164), required for virtual-card issuance.

  9. Wallet API

    • Wallet endpoints: get wallet + live balance, cursor-paginated transactions, attach payment method, add balance, and display-safe virtual-card metadata.

  10. v1 API launch

    • Initial v1 surface: users, sponsors, rewards, auctions, points, and redemptions — all keyed by the Uptop user id returned from users:upsert.