Guides

Going live

A checklist to move your integration from the sandbox to production.

Going live means swapping a tp_test_ key for a tp_live_ key. The routes, the request format and the error format are the same. What changes is that the data is real, so check the following first.

Checklist#

Business verification (KYB). Your organization must be approved before live access is enabled. Until then, live keys cannot be used and calls answer 403 live_not_enabled. Introspect the API key shows organization.live_enabled.
Create a live key in the Hub: switch the environment to Live in the top bar, then create the key in Developers. Store it in your secrets manager, never in the app or in source control.
Create live webhook endpoints. Sandbox endpoints do not receive live events. Register your production URL (in the Hub or with a live key through the API), save its signing secret and verify signatures.
Handle duplicates and retries. Deduplicate webhook events by id, and send an Idempotency-Key on every creating POST. See Idempotency.
Handle errors by code. Retry 429 after Retry-After and 5xx with backoff; never retry other 4xx unchanged. See Errors.
Check your quota. Your live rate limit depends on your plan: see Rate limits.
Review fees and policies. Confirm your markup in Fees (effective fees) and your Automation Policies.
Review your team. Give members the least role they need: admins manage keys, webhooks and settings; support is read-only; read-only members can only view.
Test failure paths in the sandbox: a rejected KYC, a withdrawal below the minimum, an insufficient balance, a suspended user. The simulator plays them all.

What is different in live#

Several live features sit behind flags that Tilt Pay switches on for the platform. They are off by default, so ask your Tilt Pay contact which ones are active before you rely on them, and test each in live with a single real user first. The API answers explicitly when one is off.

Feature	When it is off
Wallet creation	`POST /v1/users` creates the user without a wallet (`wallet_status: "none"`).
Wallet balance	`balance_usdc` and `balance_as_of` are `null`. The call still succeeds.
Phone verification	`403 live_feature_unavailable`.
KYC sessions	`409 feature_unavailable`.
`transaction.` and `withdrawal.` events	Not emitted. Poll the transactions of a user if you need them.
`kyc.approved` and `kyc.rejected` events	Not emitted. Read the KYC status of the user instead.

What always holds in live:

Phone numbers are not verified (verified: false) until you run the phone verification.
KYC statuses reflect real identity verification. You cannot change them through the API.
Transactions are the user's real movements. Nothing in this API moves money.
The user.* events are always emitted by the API.
A wallet can be pending for a short while, or failed if its creation was abandoned (contact support): never assume a wallet exists right after creating a user, and read wallet_status.

After launch#

Watch your usage and invoices on the Hub's Billing page. If something looks wrong, give support the request_id of the failing response.