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.

> DataFast can track payments automatically when you [connect a payment provider](/docs/connect-payment-provider) such as Stripe, LemonSqueezy, Polar, Paddle, Shopify, or WooCommerce. Use this API 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"
}
```