Source: https://datafa.st/docs/api/website/payments/create
Markdown source: https://datafa.st/docs/api/website/payments/create.md
Description: Record a payment, refund, renewal, or free trial from a custom payment flow.

# Create a payment

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

Record a payment, refund, renewal, or free trial from a custom payment flow.

## Request

### Authentication

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


### Body parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | number | Yes | Payment amount sent by your payment system. DataFast converts it for reporting when needed. |
| `currency` | string | Yes | Currency code for money values, such as `USD` or `EUR`. |
| `transaction_id` | string | Yes | Unique transaction ID from your payment provider. Used for idempotency and deletion. |
| `datafast_visitor_id` | string | No | DataFast visitor UUID from the browser cookie or client SDK. Used to attach server-side events to a visitor journey. Visitor UUID. Strongly recommended for attribution. |
| `email / customer_email` | string | No | Customer email. |
| `name / customer_name` | string | No | Human-readable name for the resource or event. The exact meaning depends on the endpoint. |
| `customer_id` | string | No | Stable customer ID from your payment system. Helps connect payments and free trials to the same customer. |
| `renewal` | boolean | No | Whether the payment is a recurring renewal. This affects lifecycle and renewal revenue reporting. |
| `refunded` | boolean | No | Whether this payload represents a refund instead of a payment. |
| `is_free_trial` | boolean | No | Whether this payload represents a free trial. Also inferred when `amount` is `0`. |
| `timestamp` | string | No | Event timestamp. Use it when recording historical events; defaults to the request time. |

## Response

Returns a plain JSON object. This endpoint intentionally does not wrap successful create responses in `status: "success"`.

### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `message` | string | Human-readable confirmation or status message for the operation. Result message. This endpoint does not wrap create responses in `status`. |
| `transaction_id` | string | Unique transaction ID from your payment provider. Used for idempotency and deletion. Transaction ID that was recorded, skipped, refunded, or attributed. |

### Errors

Common errors include `400` for invalid input, `401` for missing or invalid tokens, `403` for missing permission or suspended tracking, `404` for missing resources, and `500` for server errors.

## Code examples

### Example request

```bash
curl -X POST "https://datafa.st/api/v1/payments" \
  -H "Authorization: Bearer df_xxx" \
  -H "Content-Type: application/json" \
  -d '{"amount":29.99,"currency":"USD","transaction_id":"payment_456","datafast_visitor_id":"visitor-id-from-cookie"}'
```

### Success response

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