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 (optional)

Unique transaction ID from your payment provider. Used for idempotency and deletion. Transaction ID that was recorded, skipped, refunded, or attributed. Two successful payment branches currently return only message: an existing payment event, or a missing first visitor event.

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