Skip to main content
Initiate a fiat payment session that allows supporters to tip a creator using NGN credit card or bank transfer. The endpoint resolves the creator, deducts the platform fee, calculates the NGN checkout amount, and returns payment instructions for the supporter to complete. Once payment is confirmed, the tip is credited to the creator’s fiat wallet and recorded in Tip Stack.

​
Request

POST https://tipstack.fun/api/payments/fiat/intent
​
creatorId
string
required
The creator to tip. Accepts a Tip Stack user ID, Solana wallet address, or .sol domain.
​
amount
number
required
The tip amount in USD. A 5% platform fee is deducted from this value before calculating the creator’s payout and the NGN checkout total.
​
amountNgn
number
Explicit NGN amount to charge the supporter. When provided, this overrides the automatic USD-to-NGN conversion. Useful when you have pre-fetched an exchange rate quote and want to lock in that amount for the supporter.
​
senderName
string
Display name of the supporter. Defaults to "Anonymous". Ignored when isAnonymous is true.
​
payerEmail
string
Email address of the supporter. Used for receipt delivery and guest account creation. When omitted or when isAnonymous is true, a one-time guest email is generated automatically.
​
memo
string
An optional message from the supporter to the creator. Stored on the tip record and surfaced in the creator’s dashboard.
​
isAnonymous
boolean
When true, the supporter’s name and email are withheld from the creator. The senderName is overridden to "Anonymous" and a generated email is used regardless of the value provided in payerEmail.

​
Platform fee

Tip Stack deducts a 5% platform fee from the amount you supply before calculating the creator payout and the NGN checkout total. For example, a 10tipresultsina10 tip results in a 9.50 payout to the creator. The fee is visible in the metadata of the intent record.

​
Response

​
success
boolean
true when the checkout session was created successfully.
​
intentId
string
Unique intent identifier prefixed with fossa_. Use this with GET /payments/fiat/status to poll payment completion.
​
status
string
Always requires_action immediately after creation. The supporter must complete payment through the provided instructions.
​
checkoutUrl
string | null
A hosted checkout URL to redirect the supporter to for credit card or bank transfer payment. May be null when the creator’s account uses static bank transfer instructions, in which case use paymentInstructions.
​
paymentInstructions
object
Bank or wallet transfer instructions for the supporter when checkoutUrl is null. Typically includes account number, bank name, and amount in NGN.

​
Example request

JSON
{
  "creatorId": "monalisa.sol",
  "amount": 10,
  "senderName": "John Doe",
  "payerEmail": "john@example.com",
  "memo": "Great stream today!",
  "isAnonymous": false
}

​
Example response

JSON
{
  "success": true,
  "intentId": "fossa_7c3e9a1b2f4d8e0a6c5b",
  "status": "requires_action",
  "checkoutUrl": null,
  "paymentInstructions": {
    "bankName": "Guaranty Trust Bank",
    "accountNumber": "0123456789",
    "accountName": "Tip Stack / Monalisa",
    "amount": 14250,
    "currency": "NGN",
    "reference": "fossa_7c3e9a1b2f4d8e0a6c5b"
  }
}
After the supporter completes payment, poll GET /payments/fiat/status?intentId=fossa_xxx to check for confirmation. A completed status means the tip has been credited to the creator’s fiat wallet.
Fetch the current USD → NGN exchange rate via GET /payments/fiat/rate before creating the intent to display an accurate NGN preview to the supporter. Pass the returned amountNgn directly as the amountNgn parameter to lock in that rate.