POST /sdk/tip — Initiate a Tip from an SDK Session

Use this endpoint after a successful POST /sdk/init call to register a tip intent on behalf of a supporter. The response gives you an intentId you can use to track the transaction, while the actual payment is completed by the supporter inside the embedUrl iframe.

Endpoint

POST https://tipstack.fun/api/sdk/tip

Authentication

Pass the sessionToken returned by /sdk/init as a Bearer token. Session tokens always begin with sdk_sess_.

Authorization: Bearer sdk_sess_<uuid>

Session tokens are scoped to a single creator and origin. Do not share tokens across multiple creator embeds or reuse them after the session expires.

Request Body

string

required

The creator’s UUID as returned in config.creatorId from the /sdk/init response.

number

required

The tip amount in USD. Must be a positive number greater than zero.

string

required

The Solana mint address for the token the supporter is paying with. For SOL use the native mint (So11111111111111111111111111111111111111112); for USDC use EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v.

string

required

The supporter’s Solana wallet address. This address is recorded with the tip event and displayed to the creator.

Response

boolean

true when the tip intent was registered successfully.

string

A unique payment intent ID in the format pi_<hex>. Store this value to reconcile the tip against events returned by GET /sdk/events.

string

Always "requires_action" on success. This means the intent has been created but the supporter must still complete the on-chain transaction inside the checkout iframe.

Completing the Payment

After you receive "status": "requires_action", render the embedUrl from your /sdk/init response inside an <iframe>. The supporter connects their wallet and approves the Solana transaction directly inside the iframe — no further server-side calls are needed to execute the payment.

// After calling /sdk/tip, embed the checkout
const iframe = document.createElement('iframe');
iframe.src = sdkInitResponse.config.embedUrl;
iframe.width = '400';
iframe.height = '600';
document.getElementById('tip-container').appendChild(iframe);

Once the transaction is confirmed on-chain, the tip will appear in GET /sdk/events with type: "tip_completed".

Example

Request

curl -X POST https://tipstack.fun/api/sdk/tip \
  -H "Authorization: Bearer sdk_sess_a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "creatorId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "amount": 5.00,
    "inputTokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "sourceWalletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
  }'

Response

{
  "success": true,
  "intentId": "pi_a1b2c3d4e5f67890abcdef1234567890",
  "status": "requires_action"
}

Error Responses

Status	Error	Cause
`400 Bad Request`	`"amount, inputTokenMint, sourceWalletAddress, and creatorId are required"`	One or more required body fields are missing.
`401 Unauthorized`	`"Missing or invalid SDK session token"`	The `Authorization` header is absent or not a valid `sdk_sess_` token.
`500 Server Error`	`"Failed to initiate tip flow"`	An unexpected server error occurred.

Overview

Payments

Tips

SDK

Payouts

POST /sdk/tip — Initiate a Tip from an SDK Session

Endpoint

Authentication

Request Body

Response

Completing the Payment

Example

Request

Response

Error Responses

​Endpoint

​Authentication

​Request Body

​Response

​Completing the Payment

​Example

​Request

​Response

​Error Responses

Endpoint

Authentication

Request Body

Response

Completing the Payment

Example

Request

Response

Error Responses