Connect / Claim Connect

Claim Connect API

Pull user-consented Expense Card claims out of PayMyQR and into your HR, payroll, or accounting system. One canonical Node schema, three integration modes, and an accounting block that drops straight into double-entry books.

Public Beta. Partner onboarding is invite-based during beta. Every node is released only for an employee who has explicitly consented to share their card with your tenant. PII (bank details, email, phone) is encrypted at rest and exposed only inside a consented claim payload.

1. Integration modes

Mode	Direction	Best for
Pull	You call `GET /v1/connect/nodes`	Modern ERP / HRMS (recommended)
Push	We POST signed webhooks to you	Event-driven ingestion
Drop	Batch XLSX / CSV / Google Sheet export	Legacy or no-API systems

2. Authentication

OAuth 2.0 client_credentials. Exchange your tenant client ID/secret for a short-lived bearer token scoped to connect.

POST /v1/connect/oauth/token
Content-Type: application/json

{ "grant_type": "client_credentials",
  "client_id": "co_live_…",
  "client_secret": "…" }

→ { "access_token": "…", "token_type": "Bearer", "expires_in": 3600, "scope": "connect" }

Send Authorization: Bearer <token> on every request. The token can read only your tenant's consented nodes — never another tenant's, never user-app routes.

3. The Node object

The single contract bound by the PayMyQR app, this API, and your ingest. One node = one claim line item.

{
  "nodeId": "nd_…", "seq": 81423,
  "claimId": "cl_…", "cardId": "ec_…",
  "claimant": { "name": "…", "email": "…", "phone": "…" },
  "employeeRef": "EMP-2231",
  "status": "SUBMITTED | APPROVED | PAID | REJECTED",
  "date": "2026-05-20", "currency": "INR",
  "amount": 1180.00, "homeAmount": 1180.00, "fxRate": 1,
  "category": "TRAVEL.HOTEL", "merchant": "…",
  "origin": "TRACKED | MANUAL",
  "reimbursability": "REIMBURSABLE | REPORT_ONLY | ADVANCE_FUNDED",
  "admissible": true, "exclusionReason": null,
  "tax": { "gstin": "…", "invoiceNo": "…", "hsnSac": "…", "taxAmount": 180, "ratePct": 18 },
  "proof": [{ "kind": "UPI_REF | SMS | RECEIPT_IMG", "value": "…", "url": "<signed, expiring>", "hash": "…" }],
  "accounting": {
    "debitAccount": "Travel Expense",
    "creditAccount": "Employee Payable | Corporate Card Clearing | Advance Account",
    "costCenter": null, "project": null
  },
  "idempotencyKey": "…", "version": 1
}

The claim header (returned by GET /claims/{id}) adds payout (UPI VPA + QR / NEFT bank details), advanceTotal, reimbursableTotal, reportOnlyTotal, and netToReimburse.

Reimbursability → ledger leg

Value	Meaning	Credit account
`REIMBURSABLE`	Employee paid personally	Employee Payable
`REPORT_ONLY`	Corporate card — company already paid	Corporate Card Clearing
`ADVANCE_FUNDED`	Paid from a prior advance / float	Advance Account

4. Endpoints

Method	Path	Purpose
POST	`/v1/connect/oauth/token`	Mint scoped bearer token
GET	`/v1/connect/nodes?since=<seq>&status=APPROVED`	Incremental pull, paginated by `seq`
GET	`/v1/connect/nodes/{id}`	Single node
GET	`/v1/connect/claims/{id}`	Claim header + payout + totals
GET	`/v1/connect/proofs/{id}`	Short-lived signed proof URL
POST	`/v1/connect/employees/link`	Map your `employeeRef` ↔ a consenting PayMyQR user
POST	`/v1/connect/webhooks`	Register a webhook URL + events
POST	`/v1/connect/claims/{id}/ack`	Report back APPROVED / REJECTED / PAID + your remote ref
GET	`/v1/connect/export.csv` · `.json`	Batch drop for legacy systems

5. Webhooks

We POST Node[] on claim.submitted, claim.approved, node.created, and claim.paid. Verify the signature before trusting the body.

X-PMQ-Signature: sha256=<hex hmac of the raw request body, keyed with your webhook secret>

# verify (pseudocode)
expected = hmac_sha256(secret, raw_body)
if not constant_time_equal(expected, header_hex): reject(401)

Retries use exponential backoff; dedupe on idempotencyKey.

6. Mapping into your system

System	Node maps to
Zoho Books / Expense	Expense line / expense report (`is_reimbursable`, GST fields)
QuickBooks Online	Bill / Purchase — Dr expense, Cr Employee Payable
Xero	Expense Claim
Tally Prime	Journal voucher (Dr expense / Cr party) + GST
Concur / NetSuite	Expense report line item
No API (SMB)	Templated XLSX / CSV / Google Sheet, or branded PDF by email

GST fields (gstin, hsnSac, taxAmount) flow straight into Indian books for input-tax-credit.

7. Sandbox

Beta partners get a sandbox tenant pre-seeded with synthetic consenting employees and claims, so you can build and certify your adapter before going live. Request access via support.