Create a payment

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

Record a payment, refund, renewal, or free trial from a custom payment flow — for providers without a native DataFast integration or for payment links. Always include datafast_visitor_id when possible so revenue is attributed to marketing channels.

Successful responses use a plain JSON body (no status wrapper). Duplicate transaction_id values are handled idempotently.

Related: Revenue attribution · Custom payment API

Try on Playground

Request

Query parameters

websiteId

string

Required with a dft_ account token on Website API routes. Omit with a df_ website key. Example: ?websiteId=665f0b3c4d2e1a0012345678.

Body parameters

amount

number

required

Amount in major currency units. Example: 29.99. Use 0 for free trials (or set is_free_trial: true).

currency

string

required

ISO currency code matching your charge. Example: "USD".

transaction_id

string

required

Unique ID from your billing system — used for idempotency. Example: "txn_abc123". Re-posting the same ID returns a duplicate message, not a second payment.

datafast_visitor_id

string

Visitor UUID from the datafast_visitor_id cookie or tracking script. Example: "a3ab2331-989f-4cfa-91c6-2461c9e3c6bd". Alias: visitorId on some endpoints. Strongly recommended for revenue attribution.

email / customer_email

string

Customer email. Helps match free trials to later payments. Accepts email or customer_email.

name / customer_name

string

Human-readable name for the resource or event. The exact meaning depends on the endpoint.

customer_id

string

Stable customer ID from your billing system. Example: "cus_abc123".

renewal

boolean

Whether the payment is a recurring renewal. This affects lifecycle and renewal revenue reporting.

refunded

boolean

Whether this payload represents a refund instead of a payment.

is_free_trial

boolean

Whether this payload represents a free trial. Also inferred when amount is 0. true for free trials. Also inferred when amount is 0.

timestamp

string

ISO 8601 event time. Defaults to request time. Example: "2026-05-21T12:00:00Z".

Example request body

{
  "amount": 29.99,
  "currency": "USD",
  "transaction_id": "txn_abc123",
  "datafast_visitor_id": "a3ab2331-989f-4cfa-91c6-2461c9e3c6bd",
  "email": "customer@example.com"
}

Always include datafast_visitor_id when possible so revenue is attributed to traffic sources.

Response

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

Response fields

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.

Authentication

df_ website API key: The website is inferred from the key. You do not need a websiteId query parameter.
dft_ account token: Requires payments:write permission and ?websiteId= on every request. The token must be allowed to access that website.

Read authentication and scopes for token creation, permission lists, and scoped tokens.

Errors

400 — Missing amount, currency, or transaction_id, invalid amount, or invalid field combination.

404 — Website not found.

See API errors for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

✍️ Something missing? Suggest features.

🤖 AI agent or LLM? Read this page as markdown