Skip to main content

Test before launch

Run through checkout, box openings, your vault and shipping before inviting customers. Include a refresh or interrupted payment so you know recovery works too.

1. Check the connection​

In the starter, run:

npm run doctor

This checks your key, app configuration, payment methods and local login settings using GET requests only. It doesn't make a purchase or test a customer's login.

A 403 means you should check that the key is enabled, unexpired, a Commerce key and owned by an active DYLI Pro developer.

2. Know which mode you're using​

  • Demo: NEXT_PUBLIC_DEMO_MODE=true lets you try the interface with live catalog data and simulated purchases. No money moves.
  • Live: NEXT_PUBLIC_DEMO_MODE=false connects to production by default, even on localhost. Browsing is free; purchases and wallet transfers are real.
  • Separate test environment: if DYLI has supplied a lab URL and key, use those together. A lab is not automatically created when you register an app or clone the repo. Ask DYLI support about availability.

Do not send Stripe test cards, invented transaction hashes or simulated payment evidence to production.

3. Test the customer experience​

Commerce v1 is boxes-only, including vaulting, sell-backs and redemptions. Check:

  • Sign-in: the customer sees their own wallet and holdings, never someone else's.
  • Checkout: card and balance both work, including with a new wallet that has no gas funds.
  • Other crypto, if you add it: test conversion success, failure and interruption. Confirm the exact Abstract USDC settlement and payer authorization; a successful swap alone shouldn't create an order or trigger another charge.
  • Box openings: test 1 and 10 of the same box, with one charge per batch.
  • Vault and sell-back: keep all items, sell all eligible items, then try a mix. Check the actual holdings and USDC balance.
  • Recovery: refresh, interrupt a request and submit it again. Resume the purchase without charging twice.
  • Shipping: redeem one item and multiple items. Check address corrections, delivery rates, payment, shipment records and status.
  • Desktop and mobile: check the full flow and checkout's return to your registered domain.

Start with an isolated lab if one is available. Otherwise arrange an explicitly approved, low-value production test with DYLI; it uses real funds. Deployed storefronts use their registered HTTPS return origin. Local development can return to exact localhost, 127.0.0.1 or IPv6 loopback URLs; that changes navigation, not payment mode.

Secondary marketplace, P2P trading and eBay integration are coming soon, not part of these v1 checks.

Integration checks and separate test environments

Credentials​

If DYLI provisions an isolated lab for you, use its assigned URL and matching key:

DYLI_COMMERCE_BASE_URL=https://commerce-lab.example/api/commerce/v1
DYLI_API_KEY=YOUR_ASSIGNED_LAB_KEY

Keep the API key on your server. The lab uses the same /api/commerce/v1 route shapes, authentication headers, idempotency rules, order states, and webhook format as production. Lab customers, payments, orders, inventory claims, and fulfillment remain isolated from production.

Do not send made-up transaction hashes or test card payments to the production base URL. If you have not received lab credentials, contact DYLI support.

Check available features​

Confirm the key, automatically resolved application, and currently available payment methods:

curl "$DYLI_COMMERCE_BASE_URL" \
  -H "x-api-key: $DYLI_API_KEY"

Require all of the following before showing a checkout button:

  • capabilities.writes.enabled is true
  • capabilities.purchasing_ready is true
  • The chosen method appears in capabilities.payments

Your build can also validate requests and responses against the OpenAPI 3.1 document.

API checklist​

Use unique external IDs and idempotency keys for every test case:

  1. Read GET /catalog/boxes and select a box with purchase.supported: true.
  2. Synchronize a test customer and Abstract delivery wallet.
  3. Create a quote from the row's unchanged purchase.quote_item.
  4. Complete card checkout and balance payment as separate purchases. The starter uses embedded Stripe Checkout for cards.
  5. Complete the box's buy/results/decision/finalize flow from the customer's Abstract wallet. Then poll the order until fulfillment_status is completed.
  6. Repeat the same request with the same idempotency key and confirm that the original result is returned.
  7. Reuse the idempotency key with a changed body and confirm that the API returns 409 idempotency_conflict.
  8. Add signed partner webhooks, deliver the same event twice, and confirm that your system applies it once.
  9. If you will use a treasury wallet, test one USDC transfer and signature per quote, including transaction-reuse rejection.
  10. Redeem eligible items from the customer's vault. Confirm the shipping payment and resulting shipment records.

For card checkout, the lab returns a Stripe test Checkout page. DYLI receives and verifies Stripe's webhook; your integration only follows the returned checkout state and DYLI order state.

For simulated USDC, use the test-payment instructions supplied with the lab. Production never accepts the lab test flag or simulated transaction evidence.

Opening and recovery checks​

Require capabilities.box_play.ready: true and a customer wallet on the returned chain_id. An isolated lab uses Abstract testnet and its own contracts, inventory and sponsorship. Don't use a production contract with a simulated or Stripe-test payment.

  • Open batches of 1, 2 and 10; reject 0, 11, fractional quantities, and multiple Box products in one quote.
  • Verify the total includes the Box subtotal once and any partner fee once. Test fee_rules.enabled:false and an explicit fixed fee of 0.
  • Exercise all-vault, all-sell, and mixed decisions. Verify holdings and USDC payouts on the selected network, not just the reveal animation.
  • Repeat create/results/decision/finalize requests. An order must create one batch and one set of canonical DYLI orders.
  • Close/reload after each broadcast. Recover the existing transaction hashes; never repay or redraw a settled batch.
  • Expire the target-block window. Restart using the same paid order and a changed opening_reference, clearing old hashes and choices.
  • Make concurrent calls and verify 409 box_play_busy is retryable. Try a different partner/customer/wallet and confirm it cannot access or mutate the play.
  • Verify card buyback withdrawal holds survive settlement. Test payout-liquidity delays and receipt/indexing delays without losing rewards.
  • A cancelled/failed/expired payment must not authorize an opening. Uncertain payments are reconciliation cases, not permission to send a second transfer.

What to persist​

Store these values in your own application:

  • Your external customer and order IDs
  • The DYLI quote, payment-session, and order IDs
  • Each idempotency key together with the exact request body
  • The last observed order and fulfillment status
  • Processed x-dyli-event-id values if you use webhooks

You do not copy DYLI inventory tables or payment recipient addresses into your database. Read catalog state from the API and use the recipient and token addresses returned with each quote.

Before going live​

Use your production Commerce key, registered HTTPS domain and production login settings. Check the returned network and gas sponsorship, then run the connection check again. Arrange a small production purchase with DYLI to verify the deployed flow. Keep checkout unavailable if box openings or the selected payment method aren't ready.