API ReferencePayments

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 of currency (for example 24.99 USD or 2499 JPY), not cents or other minor units. Must be a finite number greater than 0, with no more decimal places than the currency has. Numeric strings are not accepted; the converted minor-unit amount must not exceed 9007199254740991.
  • faurya_visitor_id (string): Visitor ID from the faurya_visitor_id browser 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 the faurya_session_id browser 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 for amount, such as USD, EUR, GBP, INR or JPY. Defaults to USD. Faurya must support the currency's decimal precision and have an exchange rate available; otherwise the payment is refused.
  • status (string): succeeded (default) or failed, 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 example 2026-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 after 2000-01-01T00:00:00Z and no more than five minutes ahead of receipt time (clock-skew allowance). If omitted, null or blank, receipt time is used. An invalid value rejects the request. The key must be exactly occurred_at; occurredAt and occuredat are ignored.
  • metadata (object): Extra attributes stored with the payment, not used as customer identity. May be omitted or null.

Metadata rules

  • metadata must 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_id must be unique for your site. Sending it again returns 400 with "error": "DUPLICATE_TRANSACTION", including while the first request is still being recorded.
  • A deleted transaction cannot be recorded again ("error": "TRANSACTION_DELETED").
  • transaction_id is 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 with TRANSACTION_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 in errors, each with the field, a code and a message. Recording refusals return message and error instead.
  • 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.