Quickstart

1. Set up your account

Create an app

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

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.

Link the wallet to your app

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

Generate a secret key

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

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.

2. Create a payment

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:

{
  "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 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. Saving the URL returns a signing secret, whsec_..., shown once. Pay another payment and the event arrives:

{
  "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 has the details and the verification code.

Next steps

Hosted checkout

What your customer sees, return URLs and expiry.

Webhooks

Verify signatures and handle retries.

Payment statuses

What each status means and what to do.

Getting started

Guides

API reference

SDKs

1. Set up your account

2. Create a payment

3. Pay it

4. Receive the webhook

Next steps

Hosted checkout

Webhooks

Payment statuses

​1. Set up your account

​2. Create a payment

​3. Pay it

​4. Receive the webhook

​Next steps

Hosted checkout

Webhooks

Payment statuses

1. Set up your account

2. Create a payment

3. Pay it

4. Receive the webhook

Next steps