> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywit.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create a payment, pay it from a test wallet, and receive the webhook.

## 1. Set up your account

Sign in to the [sandbox dashboard](https://dashboard.sandbox.paywit.xyz) with your email. You get a one-time code, there is no password.

**1. Create an app**

Under **Apps**, create one for your product. Keys and webhooks belong to an app.

**2. Add and verify a settlement wallet**

Under **Wallets**, add the Stellar public key (`G...`) that should receive USDC. The account must be funded and hold a trustline to testnet USDC. Click **Validate** and pay the small verification amount from that wallet to prove you own it.

**3. Link the wallet to your app**

On the app page, set the settlement wallet. Payments on this app now settle there.

**4. Generate a secret key**

On the app page, under **Secret keys**, generate one. It is shown once. On sandbox it starts with `sk_test_`.

> [!WARNING]
>
> The secret key is for your server only. Never put it in a web page or mobile app. If you need to create payments from the browser, use the publishable key with the [JavaScript SDK](https://docs.paywit.xyz/sdks/javascript.md).

## 2. Create a payment

```bash theme={null}
curl https://api.sandbox.paywit.xyz/v1/payments \
  -H "X-Paywit-Secret-Key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1,
    "description": "Test order",
    "clientReferenceId": "order_1"
  }'
```

The response is the payment and the checkout URL:

```json theme={null}
{
  "paymentCheckoutUrl": "https://checkout.sandbox.paywit.xyz/checkout/0f4c1e2a-...",
  "payment": {
    "id": "0f4c1e2a-7b3d-4e5f-9a6b-1c2d3e4f5a6b",
    "amount": 1,
    "status": "Created",
    "expiresAt": "2026-10-14T10:29:07+00:00",
    "description": "Test order",
    "returnUrl": null,
    "createdAt": "2026-10-14T09:29:07+00:00",
    "bridgeStatus": null
  }
}
```

Store `payment.id` against your order. `clientReferenceId` is your own id and comes back in the webhook.

## 3. Pay it

Open `paymentCheckoutUrl` in a browser. Pick a wallet, approve the payment, and watch the page flip to **Paid**.

You need a wallet with testnet USDC for this. The [testing guide](https://docs.paywit.xyz/guides/test-on-sandbox.md) shows how to get one in a few minutes.

## 4. Receive the webhook

On the app page, under **Webhook**, set the URL Paywit should call. For a first look, use a request catcher such as [webhook.site](https://webhook.site). Saving the URL returns a signing secret, `whsec_...`, shown once.

Pay another payment and the event arrives:

```json theme={null}
{
  "id": "8e2d6a1f-...",
  "type": "payment.paid",
  "createdAt": "2026-10-14T09:31:40+00:00",
  "data": {
    "paymentId": "0f4c1e2a-...",
    "appId": "...",
    "amount": 1,
    "assetIdentifier": "USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
    "status": "Paid",
    "transactionHash": "<64-char hex transaction hash>",
    "clientReferenceId": "order_1"
  }
}
```

In production your endpoint verifies the `Paywit-Signature` header, deduplicates on `id`, and fulfils the order on `payment.paid`. The [webhooks guide](https://docs.paywit.xyz/guides/webhooks.md) has the details and the verification code.

## Next steps

> **[Hosted checkout](https://docs.paywit.xyz/guides/hosted-checkout.md)**
>
> What your customer sees, return URLs and expiry.

> **[Webhooks](https://docs.paywit.xyz/guides/webhooks.md)**
>
> Verify signatures and handle retries.

> **[Payment statuses](https://docs.paywit.xyz/guides/payment-statuses.md)**
>
> What each status means and what to do.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.