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

# Record payments

> Send every charge to Tolt so the partner behind the customer earns a commission.

Pick one source of payments. Either your billing integration sends them, or your backend does.

## A. Billing integration

> **[Stripe](/integrations/stripe)**

> **[Paddle](/integrations/paddle)**

> **[Chargebee](/integrations/chargebee)**

> [!WARNING]
>
> With a billing integration connected, don't also call `POST /v2/transactions`. Each charge would be counted twice and pay two commissions.

## B. Record a charge with the API

Call this wherever you confirm a successful charge. `amount` is an integer in the smallest currency unit (`4900` = \$49.00). `customer_id` is Tolt's `cus_...` id, not yours.

Your billingchargeYour serverbackendTolt/v2 API*1*ch\_3Qf8… succeeded*2*POST /v2/transactions*3*201 txn\_Hc5d…*4*flows → comm\_2nV8…

```ts TypeScript theme={"system"}
import { ToltApiClient } from "@tolt/api";

const tolt = new ToltApiClient({ token: process.env.TOLT_API_KEY! });

const { data: transaction } = await tolt.transactions.create({
  customer_id: "cus_Q7wRt2YxLm9KfZ3nPb8HcV4d",
  amount: 4900,
  charge_id: "ch_3Qf8x2aBcD",
  billing_type: "subscription",
  interval: "month",
  source: "api",
});
```

```python Python theme={"system"}
import os
from tolt import ToltApi

client = ToltApi(token=os.environ["TOLT_API_KEY"])

res = client.transactions.create(
    customer_id="cus_Q7wRt2YxLm9KfZ3nPb8HcV4d",
    amount=4900,
    charge_id="ch_3Qf8x2aBcD",
    billing_type="subscription",
    interval="month",
    source="api",
)
```

```bash cURL theme={"system"}
curl -X POST https://platform.tolt.com/v2/transactions \
  -H "Authorization: Bearer $TOLT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_Q7wRt2YxLm9KfZ3nPb8HcV4d",
    "amount": 4900,
    "charge_id": "ch_3Qf8x2aBcD",
    "billing_type": "subscription",
    "interval": "month",
    "source": "api"
  }'
```

Tolt credits the customer's partner and marks the customer `active`. Your commission flows run in the background, so the commission can appear a moment after the response; recording a payment doesn't pay anyone by itself:

Jane's payment txn\_Hc5d…Transaction\$49.00 API12:15Customerjane\@example.com Active12:15Commission\$14.70 Pending12:15Approvedcomm\_2nV8… Approved+30dPaid\$14.70 Paid+45d

Immediate approval skips pending. See [commission lifecycle](/concepts/commission-lifecycle) for rejections and refunds.

> [!WARNING]
>
> Send a `charge_id` with every payment. A customer can have only one transaction per `charge_id`, so a retried webhook that posts the same charge again gets a `409 already_exists` instead of a second transaction; treat that 409 as already handled. That also makes SDK retries safe, so the samples above keep them on. Without a `charge_id` (or with an empty one) nothing is deduplicated. Give each renewal its own id, such as the invoice or charge id, not the subscription id.

## Find the customer id

Best: store the `cus_...` id when you [track the signup](/tracking/signups). Otherwise, look it up:

```ts TypeScript theme={"system"}
// Created with POST /v2/customers and your own customer_id
const { data } = await tolt.customers.list({ customer_id: "user_1042" });

// Created by tolt.signup(): search by the email you
// passed, then match exactly
const { data: matches } = await tolt.customers.list({
  search: "jane@example.com",
});
const customer = matches.find((c) => c.email === "jane@example.com");
```

```bash cURL theme={"system"}
curl -G https://platform.tolt.com/v2/customers \
  -d customer_id=user_1042 \
  -H "Authorization: Bearer $TOLT_API_KEY"

curl -G https://platform.tolt.com/v2/customers \
  -d search=jane@example.com \
  -H "Authorization: Bearer $TOLT_API_KEY"
```

No match means the customer wasn't referred. Skip the transaction.

## Refunds

Refund the transaction by its `txn_...` id. Unpaid commissions become `refunded`. Already paid ones get a negative commission that nets against the next payout.

```ts TypeScript theme={"system"}
await tolt.transactions.refund({ id: "txn_Hc5dPj8fKq2LmZx7RtYw3nVb" });
```

```python Python theme={"system"}
client.transactions.refund(id="txn_Hc5dPj8fKq2LmZx7RtYw3nVb")
```

```bash cURL theme={"system"}
ID=txn_Hc5dPj8fKq2LmZx7RtYw3nVb
curl -X POST \
  "https://platform.tolt.com/v2/transactions/$ID/refund" \
  -H "Authorization: Bearer $TOLT_API_KEY"
```


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