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.

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. Must be greater than 0.

Optional fields

• faurya_session_id (string): Session ID from the browser cookie when available.
• currency (string): Accepted by the request body, but the current endpoint records the numeric amount only.
• metadata (object): Extra primitive values to attach to the payment event.

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.
• 400 Bad Request: Missing required fields, invalid amount, 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.

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: 29.99,
    metadata: {
      plan: "starter",
      provider: "custom_checkout",
    },
  }),
});

const result = await response.json();

Success response

{
  "message": "Payment recorded successfully",
  "transaction_id": "payment_456"
}