Source: https://datafa.st/docs/api/website/payments
Markdown source: https://datafa.st/docs/api/website/payments.md
Description: Track and delete payment events for revenue attribution.

# Payments API

Use the Payments API to send revenue events from any payment provider and attribute them to visitors.

If you use Stripe, LemonSqueezy, Polar, Paddle, Shopify, or WooCommerce through DataFast integrations, payments can be tracked automatically. Use this endpoint for custom payment flows or providers that DataFast does not integrate with yet.

| Endpoint | Method | Path | Purpose |
|---|---|---|---|
| [Create payment](/docs/api/website/payments/create) | POST | `/api/v1/payments` | Record a payment or revenue event |
| [Delete payments](/docs/api/website/payments/delete) | DELETE | `/api/v1/payments` | Delete payment events by transaction, visitor, or date range |

## Create a payment

`POST https://datafa.st/api/v1/payments`

### Authentication

- `df_` website API key for one website. No `websiteId` query parameter required.
- `dft_` account token with `payments:write`. Pass `websiteId` as a query parameter.

### Body parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `amount` | number | Yes | Payment amount. Must be zero or greater. Use `refunded: true` for refunds |
| `currency` | string | Yes | Payment currency code, for example `USD` |
| `transaction_id` | string | Yes | Unique transaction ID from your payment provider |
| `datafast_visitor_id` | string | No | Strongly recommended for revenue attribution |
| `email` / `customer_email` | string | No | Customer email |
| `name` / `customer_name` | string | No | Customer name |
| `customer_id` | string | No | Stable customer ID from your payment system |
| `renewal` | boolean | No | Set true for recurring renewal payments |
| `refunded` | boolean | No | Set true to record a refund |
| `is_free_trial` | boolean | No | Also inferred when `amount` is `0` |
| `timestamp` | string | No | ISO 8601 timestamp. Defaults to now |

```json
{
  "amount": 29.99,
  "currency": "USD",
  "transaction_id": "payment_456",
  "datafast_visitor_id": "visitor-id-from-cookie"
}
```

## Delete payments

`DELETE https://datafa.st/api/v1/payments`

Delete by `transaction_id`, `datafast_visitor_id`, `startAt`, and `endAt`.

```http
DELETE /api/v1/payments?transaction_id=payment_456
DELETE /api/v1/payments?datafast_visitor_id=visitor-id-from-cookie&startAt=2026-05-01T00:00:00Z&endAt=2026-05-19T23:59:59Z
```

> Be careful: without a date range, matching records across all time can be deleted.

## Response

### Response fields

| Field | Type | Description |
|---|---|---|
| `message` | string | Result message. This endpoint does not wrap successful create responses in `status: "success"` |
| `transaction_id` | string | Transaction ID that was recorded, attributed, skipped as duplicate, or refunded |

## Code examples

### Example request (Node.js/Express)

```javascript
// Send payment data to DataFast's API
const handler = async (req, res) => {
  const datafast_visitor_id = req.cookies.datafast_visitor_id;

  try {
    const response = await fetch("https://datafa.st/api/v1/payments", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${DATAFAST_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        amount: 29.99,
        currency: "USD",
        transaction_id: "payment_456",
        datafast_visitor_id: datafast_visitor_id,
      }),
    });

    res.status(200).send("Payment tracked");
  } catch (error) {
    console.error("Error tracking payment:", error);
    res.status(500).send("Failed to track payment");
  }
};
```

### Success responses (200 OK)

```json
{
  "message": "Payment recorded and attributed successfully",
  "transaction_id": "payment_456"
}
```