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.

Try on Playground

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.

✍️ Something missing? Suggest features.

🤖 AI agent or LLM? Read this page as markdown

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"}'