Internal reference — not the public API

This documents NearSync's internal action-dispatch surface, used by the apps themselves and by tenant automations. It is not the public API and carries no stability guarantee — actions may change or be removed without notice. For the supported, versioned public API see API Reference.

Finance Endpoints

Endpoints for payment processing, invoice management, document signing, and contract generation. NearSync supports both Stripe (non-INR currencies) and Razorpay (INR) as payment providers, with automatic routing based on currency.

All endpoints use POST to the hyper-worker base URL with the type field specifying the action.

POST https://<project>.supabase.co/functions/v1/hyper-worker

---

Payments

create-payment

Authenticated - Requires JWT.

Create a payment checkout session for an invoice. Automatically routes to Stripe or Razorpay based on the target currency.

Rate limit: 10 requests per 60 seconds

Request

{
  "type": "create-payment",
  "invoiceId": "<uuid>",
  "clientEmail": "client@example.com",
  "successUrl": "https://portal.example.com/payment-success",
  "cancelUrl": "https://portal.example.com/invoices",
  "targetCurrency": "USD"
}

Field	Type	Required	Description
invoiceId	string	Yes	Invoice ID to create payment for
clientEmail	string	Yes	Client's email (pre-filled in checkout)
successUrl	string	Yes	Redirect URL after successful payment
cancelUrl	string	Yes	Redirect URL if payment is cancelled
targetCurrency	string	Yes	Payment currency (ISO 4217). INR routes to Razorpay, all others to Stripe

Process

1. Fetches the invoice with line items
2. If currency is INR: creates a Razorpay order
3. For all other currencies: creates a Stripe checkout session
4. Returns the checkout URL (Stripe) or order details (Razorpay) for client-side completion

Response (Stripe)

{
  "provider": "stripe",
  "amount": 10000,
  "currency": "USD",
  "url": "https://checkout.stripe.com/pay/..."
}

For Stripe, redirect the user to the url to complete payment.

Response (Razorpay)

{
  "provider": "razorpay",
  "keyId": "<razorpay-key-id>",
  "orderId": "<order-id>",
  "amount": 500000,
  "currency": "INR"
}

For Razorpay, use the keyId and orderId to initialize the Razorpay checkout widget on the client side.

Amount format

Stripe amounts are in the smallest currency unit (cents for USD, pence for GBP). Razorpay amounts are in paise (1/100 of INR). For example, $100.00 USD = 10000, and 5,000.00 INR = 500000.

---

verify-payment

Public - No authentication required.

Verify a completed payment and update the invoice status to paid. This endpoint is called after the user completes checkout and is redirected back to your application.

Rate limit: 10 requests per 60 seconds

Request

{
  "type": "verify-payment",
  "invoiceId": "<uuid>",
  "session_id": "<stripe-session-id>",
  "razorpay_payment_id": "<razorpay-payment-id>"
}

Field	Type	Required	Description
invoiceId	string	Yes	Invoice ID being paid
session_id	string	Conditional	Stripe checkout session ID. Required for Stripe payments
razorpay_payment_id	string	Conditional	Razorpay payment ID. Required for Razorpay payments

Provide either session_id (Stripe) or razorpay_payment_id (Razorpay), depending on which provider processed the payment.

Process

1. Verifies the payment with the provider's API
2. Updates the invoice status to paid
3. Creates an interaction record (type: payment_received)
4. Sends a receipt email to the client

Response

{
  "success": true
}

---

Documents & Contracts

verify-document

Public - No authentication required.

Verify the authenticity of a signed document. Used for third-party verification of contracts and agreements.

Request

{
  "type": "verify-document",
  "docId": "<uuid>"
}

Response (Valid)

{
  "valid": true,
  "doc": {
    "id": "<uuid>",
    "title": "Service Agreement",
    "status": "signed",
    "signers": [
      {
        "name": "Jane Doe",
        "role": "client",
        "signedAt": "2026-03-21T10:00:00Z"
      }
    ]
  }
}

Response (Invalid)

{
  "valid": false
}

---

sign-document

Authenticated - Requires JWT.

Sign a document with a full audit trail. When both required parties (admin and client) have signed, the document status transitions to signed and a certificate PDF is generated.

Request

{
  "type": "sign-document",
  "documentId": "<uuid>",
  "data": {
    "signerName": "Jane Doe",
    "signerEmail": "jane@example.com",
    "signerRole": "client",
    "timestamp": "2026-03-21T10:00:00Z"
  },
  "url": "https://storage.example.com/signed.pdf"
}

Field	Type	Required	Description
documentId	string	Yes	Document ID to sign
data.signerName	string	Yes	Full name of the signer
data.signerEmail	string	Yes	Email of the signer
data.signerRole	string	Yes	Role: admin or client
data.timestamp	string	Yes	ISO 8601 timestamp of signature
url	string	Yes	URL of the signed PDF

Process

1. Fetches the document record
2. Merges the new signature into the existing signatures array
3. If both admin and client signatures are present, sets status to signed
4. Generates a certificate PDF with all signatures
5. Uploads to storage and sends the signed document via email

Response

{
  "success": true,
  "status": "signed"
}

The status field reflects the document's new state: pending_signature if more signatures are needed, or signed if all parties have signed.

---

generate-contract

Authenticated - Requires JWT.

Generate a contract or invoice PDF from a Google Docs template. Template variables are replaced with provided values, and the result is exported as a PDF.

Request

{
  "type": "generate-contract",
  "projectId": "<uuid>",
  "replacements": {
    "{{CLIENT_NAME}}": "Acme Corp",
    "{{DATE}}": "March 21, 2026"
  },
  "title": "Service Agreement - Acme Corp",
  "docType": "contract",
  "templateId": "<google-doc-template-id>",
  "userId": "<uploader-uuid>"
}

Field	Type	Required	Description
projectId	string	Yes	Associated deal/project ID
replacements	object	Yes	Key-value pairs where keys are template placeholders (e.g., {{CLIENT_NAME}}) and values are the replacement text
title	string	Yes	Document title
docType	string	Yes	Document type: contract or invoice
templateId	string	Yes	Google Docs template ID
userId	string	Yes	User creating the document

Process

1. Clones the Google Docs template
2. Replaces all placeholder variables using batch update
3. Exports the document to PDF
4. Uploads the PDF to storage
5. Creates a document record with status pending_signature
6. Sends the document to the client via email

Response

{
  "success": true,
  "document": {
    "id": "<uuid>",
    "title": "Service Agreement - Acme Corp",
    "status": "pending_signature",
    "url": "https://storage.example.com/..."
  }
}

---

Related

• Booking Endpoints - Bookings can trigger invoice creation
• Webhooks - Email tracking pixel for monitoring document delivery