Quickstart

This guide takes you from nothing to a simulated user with a completed deposit. Everything here runs against the sandbox: no real money moves and no real identity check happens.

Install the SDK#

The TypeScript SDK is distributed through Tilt Pay's private registry (GitHub Packages) to customers under contract. The read access token is provided by Tilt Pay when your contract starts; never commit it.

Add a .npmrc file at the root of your project, with the token read from an environment variable:

@tilt-pay:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${TILT_PAY_NPM_TOKEN}

Then install the package:

export TILT_PAY_NPM_TOKEN="<token provided by Tilt Pay>"
npm install @tilt-pay/sdk

The SDK is optional: every example below also works with plain HTTP calls.

1. Create a sandbox API key#

1. Sign in to the Hub and open Developers.
2. Make sure the environment switch in the top bar says Sandbox, then click Create sandbox key.
3. Copy the key now. The secret is shown once: afterwards the Hub only shows its prefix and last four characters.

A sandbox key looks like tp_test_ followed by 32 characters. Keep it on your server and expose it to your code through an environment variable:

export TILT_PAY_API_KEY="tp_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. Make your first call#

Introspect the API key to check that your key works. The response tells you the project, the environment and your rate limit.

curl "https://sdk.tilt-pay.com/v1/me" \
  -H "Authorization: Bearer $TILT_PAY_API_KEY"

You should see "environment": "sandbox" and "livemode": false. If you get a 401, see Authentication.

3. Create a user#

Create a user with a phone number in E.164 format. Send an Idempotency-Key so that a network retry can never create the user twice (see Idempotency).

curl -X POST "https://sdk.tilt-pay.com/v1/users" \
  -H "Authorization: Bearer $TILT_PAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7b1c0d36-5f0e-4d2a-9a43-0b8c6e2f1a90" \
  -d '{"phone": "+33612345678", "external_id": "cust_8f2a"}'

The response is a user object with an id. In the sandbox the phone number is considered verified straight away and a simulated wallet is created. Calling the endpoint again with the same phone number returns 409 user_already_exists.

You can also store profile fields (email, names, country…) at creation: see User profiles and erasure. To rehearse the phone verification your users will go through, use the verification routes: in the sandbox the code is always 123456.

4. Simulate a user journey#

The sandbox simulator plays realistic scenarios for a user and emits the matching events. Use Simulate a scenario with the user id from the previous step (we use 4821 below).

# 1. Approve the user's identity verification
curl -X POST "https://sdk.tilt-pay.com/v1/sandbox/users/4821/simulate" \
  -H "Authorization: Bearer $TILT_PAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scenario": "kyc_approved"}'

# 2. Credit the wallet with 100 USDC
curl -X POST "https://sdk.tilt-pay.com/v1/sandbox/users/4821/simulate" \
  -H "Authorization: Bearer $TILT_PAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scenario": "deposit", "amount": 100}'

If a precondition is not met you get 409 invalid_state, 409 kyc_required or 409 insufficient_funds: simulate the earlier steps first.

5. Read the results#

• List the transactions of a user to see the deposit.
• List the wallets of a user to see the simulated balance.
• Create a KYC session to rehearse the identity verification (see KYC sessions).
• List events to see everything that was emitted. Each event has the same evt_… identifier as its webhook delivery.

Where to go next#

• Receive these events in your backend with webhooks, which you can also register with the API.
• Understand errors, pagination and rate limits.
• When you are ready, follow the go-live checklist.