POST Payment

POST https://api.faurya.com/api/v1/payments

Record a payment event and attribute revenue to a known visitor. 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({
    faurya_visitor_id: req.cookies.faurya_visitor_id,
    faurya_session_id: req.cookies.faurya_session_id,
    transaction_id: "payment_456",
    amount: 2499,
    currency: "INR",
    metadata: {
      plan: "starter",
      provider: "custom_checkout",
    },
  }),
});

const result = await response.json();

Success response

{
  "message": "Payment recorded successfully",
  "transaction_id": "payment_456",
  "amount_usd": 29.99,
  "currency": "USD"
}

Request body

Send a JSON object with the following fields:

Required fields

• faurya_visitor_id (string): Visitor ID from the Faurya browser cookie.
• transaction_id (string): Unique transaction ID from your payment provider.
• amount (number): Payment amount in the currency you send. Must be greater than 0.

Optional fields

• faurya_session_id (string): Session ID from the browser cookie when available.
• currency (string): Three-letter currency code for amount. Defaults to USD when omitted. If you send it, it must be one of the allowed currencies below. Faurya converts this amount to USD before storing revenue.
• metadata (object): Extra primitive values to attach to the payment event.

Allowed currencies

Only send currency values from this list:

Metadata rules

• metadata must be a JSON object.
• Maximum 10 metadata attributes are allowed.
• Values must be primitive values: string, number, boolean, null, or undefined.
• Objects and arrays are rejected.

The visitor must already exist for the authenticated site. transaction_id must be unique.

Response

• 200 OK: Payment recorded. The payment amount was saved internally in USD.
• 400 Bad Request: Missing required fields, invalid amount, unsupported currency, invalid metadata, or duplicate transaction.
• 401 Unauthorized: Missing or invalid API key.
• 404 Not Found: Visitor or site not found.
• 429 Too Many Requests: Account event limit reached.
• 503 Service Unavailable: Currency conversion failed. Retry the request later.