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

# Fiat Payment Intent — POST /payments/fiat/intent

> Initiate a fiat checkout session for NGN card or bank transfer tips. Returns payment instructions and an intent ID to track confirmation status.

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`**

<ParamField body="creatorId" type="string" required>
  The creator to tip. Accepts a Tip Stack user ID, Solana wallet address, or `.sol` domain.
</ParamField>

<ParamField body="amount" type="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.
</ParamField>

<ParamField body="amountNgn" type="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.
</ParamField>

<ParamField body="senderName" type="string">
  Display name of the supporter. Defaults to `"Anonymous"`. Ignored when `isAnonymous` is `true`.
</ParamField>

<ParamField body="payerEmail" type="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.
</ParamField>

<ParamField body="memo" type="string">
  An optional message from the supporter to the creator. Stored on the tip record and surfaced in the creator's dashboard.
</ParamField>

<ParamField body="isAnonymous" type="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`.
</ParamField>

## 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 $10 tip results in a $9.50 payout to the creator. The fee is visible in the `metadata` of the intent record.

## Response

<ResponseField name="success" type="boolean">
  `true` when the checkout session was created successfully.
</ResponseField>

<ResponseField name="intentId" type="string">
  Unique intent identifier prefixed with `fossa_`. Use this with [`GET /payments/fiat/status`](/api/payments/fiat-status) to poll payment completion.
</ResponseField>

<ResponseField name="status" type="string">
  Always `requires_action` immediately after creation. The supporter must complete payment through the provided instructions.
</ResponseField>

<ResponseField name="checkoutUrl" type="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`.
</ResponseField>

<ResponseField name="paymentInstructions" type="object">
  Bank or wallet transfer instructions for the supporter when `checkoutUrl` is `null`. Typically includes account number, bank name, and amount in NGN.
</ResponseField>

## Example request

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

## Example response

```json JSON theme={null}
{
  "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"
  }
}
```

<Note>
  After the supporter completes payment, poll [`GET /payments/fiat/status?intentId=fossa_xxx`](/api/payments/fiat-status) to check for confirmation. A `completed` status means the tip has been credited to the creator's fiat wallet.
</Note>

<Tip>
  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.
</Tip>