POST Payment
Record revenue from any payment provider and attribute it to a customer and visitor.
If you have connected your payment provider, you don't need this endpoint: Faurya already records those payments. Sending the same payment here as well would count it twice.
This endpoint records one payment. If you need subscriptions, invoices with line items, refunds and chargebacks, MRR or churn, use the billing API instead — it takes your whole billing model rather than a single revenue event.
POST Payment
POST https://api.faurya.com/api/v1/payments
Record a payment and attribute it to the customer and visitor who made it. The payment appears in your revenue reports and dashboards alongside payments from connected providers. Requires Bearer Token authentication.
Example request
const response = await fetch("https://api.faurya.com/api/v1/payments", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.FAURYA_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
transaction_id: "payment_456",
amount: 2499,
currency: "INR",
status: "succeeded",
occurred_at: "2026-11-09T10:30:00Z",
email: user.email,
name: user.name,
faurya_visitor_id: req.cookies.faurya_visitor_id,
faurya_session_id: req.cookies.faurya_session_id,
metadata: {
customer_id: user.id,
plan: "starter",
provider: "custom_checkout",
},
}),
});
const result = await response.json();Success response
{
"message": "Payment recorded",
"status": "recorded",
"transaction_id": "payment_456",
"amount_usd": 29.99,
"currency": "USD"
}A 200 means the payment has been recorded and committed before the response is sent; it is not queued for later recording. amount_usd is the amount valued using the request's receipt date for the exchange rate, even when you supply a past occurred_at. The value above is illustrative. Faurya stores the payment in the currency you sent and converts it for each report.
Here's an example of how to add payment data and attribute revenue using this API endpoint.
Request body
Send a JSON object with the following fields. Unknown top-level fields are ignored, not stored. Field names must match exactly.
Required fields
transaction_id(string): Unique ID of the payment in your system. At most 255 characters.amount(number): Payment amount in major units ofcurrency(for example24.99USD or2499JPY), not cents or other minor units. Must be a finite number greater than0, with no more decimal places than the currency has. Numeric strings are not accepted; the converted minor-unit amount must not exceed9007199254740991.faurya_visitor_id(string): Visitor ID from thefaurya_visitor_idbrowser cookie. Required for every payment; at most 128 characters. Identifies the paying customer and links the payment to the visitor's traffic source, pages and journey.
Optional customer details
faurya_session_id(string): Session ID from thefaurya_session_idbrowser cookie, when available. At most 128 characters.email(string): The customer's valid email address. At most 320 characters.name(string): The customer's name. At most 255 characters.
Identifiers and names are trimmed and must not contain control characters. Required strings cannot be blank. Optional strings can be omitted, null or blank; omitted customer details do not erase existing values.
A top-level customer_id is ignored and cannot replace faurya_visitor_id.
Store your own user ID in metadata.customer_id if needed. Metadata does not
determine customer identity or merge visitors across devices. email and
name are stored for display, never used to match customers.
Minimum request body
{
"transaction_id": "payment_456",
"amount": 24.99,
"faurya_visitor_id": "your-faurya-visitor-id"
}This records a successful USD payment using the time Faurya receives the request.
Payment details
All fields in this section are optional.
currency(string): Supported three-letter ISO 4217 code foramount, such asUSD,EUR,GBP,INRorJPY. Defaults toUSD. Faurya must support the currency's decimal precision and have an exchange rate available; otherwise the payment is refused.status(string):succeeded(default) orfailed, case-insensitive. Failed payments appear in failed-transaction reports and never count as revenue.occurred_at(string): When the payment happened, as an ISO 8601 date-time, for example2026-11-09T10:30:00Z. A valid supplied value is used as the payment timestamp instead of the request's receipt time. It must be on or after2000-01-01T00:00:00Zand no more than five minutes ahead of receipt time (clock-skew allowance). If omitted,nullor blank, receipt time is used. An invalid value rejects the request. The key must be exactlyoccurred_at;occurredAtandoccuredatare ignored.metadata(object): Extra attributes stored with the payment, not used as customer identity. May be omitted ornull.
Metadata rules
metadatamust be a JSON object with at most 10 entries.- Keys are 1-64 characters, cannot be blank or whitespace-only, and must not contain control characters.
- Values must be a string (at most 500 characters), finite number, boolean or
null. Objects and arrays are refused.
Rules
transaction_idmust be unique for your site. Sending it again returns400with"error": "DUPLICATE_TRANSACTION", including while the first request is still being recorded.- A deleted transaction cannot be recorded again (
"error": "TRANSACTION_DELETED"). transaction_idis shared with the billing API: one id belongs to one door. An id already recorded there is refused here as a duplicate, and an id recorded here is refused there withTRANSACTION_EXISTS_IN_PAYMENTS_API.- The visitor does not need to exist yet. A payment made moments after the visitor's first page view is recorded immediately, and linked to the visitor as soon as the visit is processed.
- Payments do not count toward your account's event limit.
Response
200 OK: Payment recorded and committed, with"status": "recorded".400 Bad Request: The request is invalid, the currency is unsupported, or the transaction already exists or was deleted. Invalid requests list problems inerrors, each with thefield, acodeand amessage. Recording refusals returnmessageanderrorinstead.401 Unauthorized: Missing or invalid API key.503 Service Unavailable: Recording capacity is temporarily exhausted ("error": "CAPACITY_EXCEEDED"). Nothing was written; retry the same request later.
{
"message": "Invalid payment request",
"errors": [
{
"field": "amount",
"code": "TOO_MANY_DECIMALS",
"message": "USD amounts have at most 2 decimal places"
}
]
}When you need more than a payment
The payments API records revenue and attributes it to a visitor. It does not model what the revenue was for, so it cannot produce MRR, subscriber counts, churn, plan changes or refunds.
The billing API does. It takes customers, plans, invoices with line items, transactions (payments, refunds, chargebacks and their reversals) and subscription lifecycle events, and derives subscriptions and MRR from them. It also has a bulk import for moving an existing history in.
Both APIs share one customer space on your site, and payments recorded through either are joined to the same visitor. Record any given payment through one of them, never both.