Payments

Overview

MechZie supports two payment methods: Online (Razorpay) and Cash / COD. Every monetary operation is backed by an immutable double-entry ledger — the payments table records Razorpay state, while ledger_entries is the financial source of truth.

Online — customer pays via Razorpay checkout (UPI, card, etc.). Platform collects the full amount and credits the mechanic’s wallet.
Cash / COD — customer pays the mechanic in cash on-site. The mechanic confirms receipt, and the platform fee is deducted from their future earnings.

All amounts are in paisa (₹1 = 100 paisa).

Architecture

Payment Method Selection

When creating a job, the customer chooses a payment method:

curl -X POST https://api.mechzie.in/api/v1/jobs \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_category_id": "uuid",
    "pickup_address": "123 Main St",
    "pickup_lat": 12.97,
    "pickup_lng": 77.59,
    "payment_method": "cod"
  }'

Value	Default	Description
`online`	✅	Pay via Razorpay checkout (UPI, card, net banking)
`cod`		Pay cash to the mechanic on-site

If omitted, defaults to online.

Online Payment Flow

Two paths confirm a payment — the optimistic verify (fast UI) and the webhook (canonical truth). Both are idempotent; if they race, the first one wins.

Step-by-Step (Online)

Create a Razorpay Order

After the mechanic marks a job as completed, the customer creates a payment order:

curl -X POST https://api.mechzie.in/api/v1/payments/create-order \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "job_id": "uuid-of-completed-job" }'

Response (200):

{
  "orderId": "order_PqR1s2T3u4V5",
  "amount": 45000,
  "currency": "INR"
}

Amount is in paisa. Display as ₹${(amount / 100).toStringAsFixed(0)}.

Open Razorpay Checkout

Use the Razorpay Flutter SDK:

final razorpay = Razorpay();

razorpay.on(Razorpay.EVENT_PAYMENT_SUCCESS, (PaymentSuccessResponse response) {
  verifyPayment(response.orderId!, response.paymentId!, response.signature!);
});
razorpay.on(Razorpay.EVENT_PAYMENT_ERROR, (PaymentFailureResponse response) {
  showPaymentError(response.message);
});

razorpay.open({
  'key': 'rzp_live_YOUR_KEY_ID',
  'amount': 45000,
  'currency': 'INR',
  'order_id': 'order_PqR1s2T3u4V5',
  'name': 'MechZie',
  'description': 'Service Payment',
  'prefill': { 'contact': '+919876543210' },
});

Use the Razorpay Key ID (starts with rzp_), not the Key Secret. The Key Secret is server-side only.

Verify Payment (Optimistic)

After Razorpay returns success, verify the signature:

curl -X POST https://api.mechzie.in/api/v1/payments/verify \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "razorpay_order_id": "order_PqR1s2T3u4V5",
    "razorpay_payment_id": "pay_AbC1d2E3f4G5",
    "razorpay_signature": "hmac-sha256-signature-string"
  }'

On success, this also triggers the platform fee split into the ledger (mechanic payable 90% + platform fee 10%). The webhook is the canonical fallback if this path fails.

If verify and webhook disagree, webhook always wins. The ledger uses idempotency keys to prevent double-processing.

Cash / COD Payment Flow

For COD jobs, there’s no Razorpay involvement. The mechanic collects cash directly from the customer and confirms receipt via the API.

Step-by-Step (Cash / COD)

Customer creates COD job

The customer selects “Pay by Cash” when creating a job:

curl -X POST https://api.mechzie.in/api/v1/jobs \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_category_id": "uuid",
    "pickup_address": "123 Main St",
    "pickup_lat": 12.97,
    "pickup_lng": 77.59,
    "payment_method": "cod"
  }'

The job proceeds through the normal lifecycle (dispatching → accepted → en_route → arrived → in_progress → completed).

Customer pays cash to mechanic

After the mechanic marks the job as completed, the customer’s app shows the amount to pay in cash. This is a UI-only step — no API call needed from the customer.

Mechanic confirms cash received

Once the mechanic has collected cash, they confirm via the API:

curl -X POST https://api.mechzie.in/api/v1/payments/confirm-cash \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "job_id": "uuid-of-completed-job" }'

Response (200):

{
  "data": {
    "job_id": "uuid",
    "amount": 45000,
    "platform_fee": 4500,
    "mechanic_payable": 40500,
    "status": "paid"
  }
}

This endpoint:

Transitions the job to paid
Records the COD collection in the ledger
Deducts the platform fee from the mechanic’s wallet balance

COD Ledger Entries

When a mechanic confirms a COD payment, CommissionService.processCodCommission() creates these ledger entries:

Entry	Debit	Credit	Amount
COD collected	Mechanic Account	`PLATFORM_COD_RECEIVABLE`	Gross (₹450)
Platform fee	Mechanic Account	`PLATFORM_FEE_REVENUE`	Platform fee (₹45)

The platform fee is deducted from the mechanic’s future earnings (wallet balance goes negative by the fee amount).

COD is not available for cancellation fees. Cancellation fees must always be paid online via Razorpay to prevent customers from avoiding payment.

Platform Fee Split

When a payment is captured (online) or confirmed (COD), CommissionService splits the gross amount. The mechanic always receives 90%. For online payments, the gateway processing fee (PG fee) is a platform expense — it never reduces the mechanic’s payout.

Component	Formula	Example (₹1,000 job)
Gross	Customer-paid amount	₹1,000 (100000 paisa)
Platform fee (10%)	`gross × platform_fee_bps / 10000`	₹100 (10000 paisa)
Mechanic payable	`gross − platform_fee`	₹900 (90000 paisa)
PG fee (actual)	Reported by gateway after settlement (online only)	~₹20 (varies)
Platform net revenue	`platform_fee − pg_fee − gateway_tax`	~₹80

The platform fee rate is dynamic — stored in platform_config as platform_fee_bps (default: 1000 = 10%) and changeable without redeployment.

Online vs COD Fee Handling

Aspect	Online	COD
Who collects money	Razorpay	Mechanic (cash)
Mechanic wallet effect	+90% to pending balance	−10% platform fee from balance
PG fee	Platform expense (actual, from gateway)	None
Ledger accounts	`PLATFORM_COLLECTIONS`	`PLATFORM_COD_RECEIVABLE`

PG Fee Tracking

The payment-gateway processing cost is recorded separately as a platform expense — not deducted from the mechanic:

On payment.captured webhook — if Razorpay reports fee and tax fields, PgFeeService.recordActualPgFee() posts a pg_fee_actual ledger entry: DR PLATFORM_FEE_REVENUE → CR PLATFORM_PG_EXPENSE
From settlement reports — if the webhook fee was 0, a corrected entry can be posted with source: 'settlement_report' (distinct idempotency key).
pg_fee_bps_estimate (default: 200 = 2%) is available for margin estimation only — never used in actual ledger calculations.

Webhook Processing

The webhook pipeline guarantees exactly-once processing via payment_events.razorpay_event_id: Handled events:

Razorpay Event	Action
`payment.captured`	Payment → captured, job → paid, platform fee ledger entries, PG fee recorded (if reported)
`payment.failed`	Payment → failed
`refund.processed`	Refund row → processed, payment → refunded
`payout.processed`	Payout → processed, settlement → completed
`payout.failed`	Payout → failed, settlement → failed
`payout.reversed`	Payout → reversed

Endpoint: POST /api/v1/payments/webhook

No authentication (Razorpay sends directly)
Verified via HMAC-SHA256 in X-Razorpay-Signature header
Always returns 200 to prevent Razorpay retries

Frontend devs don’t need to implement webhook handling — it’s server-side only. But you should handle the case where verify succeeds but the UI should wait for the job status to update to paid.

Checking Payment Status

GET /api/v1/payments/{jobId}
Authorization: Bearer ACCESS_TOKEN

Response:

{
  "id": "uuid",
  "job_id": "uuid",
  "type": "service",
  "razorpay_order_id": "order_PqR1s2T3u4V5",
  "razorpay_payment_id": "pay_AbC1d2E3f4G5",
  "amount": 45000,
  "status": "captured",
  "method": "upi",
  "created_at": "2026-05-21T10:30:00.000Z"
}

For COD jobs, there is no payments table record — the job transitions directly from completed to paid when the mechanic confirms cash. Check the job’s status field instead.

Payment Statuses

Status	Meaning	UI Action
`created`	Order created, waiting for payment	Show checkout button
`authorized`	Payment authorized (rare intermediate)	Show “Processing…”
`captured`	Payment successful	Show receipt ✅
`failed`	Payment failed	Show retry option
`refunded`	Refund processed	Show refund confirmation

Cancellation Fees

Late cancellations incur fees. The fee amount is configurable in platform_config.

Customer cancellation

Cancelling from en_route, arrived, or in_progress → flat ₹50 fee (default). The customer cannot create new jobs until the fee is paid (402 PAYMENT_REQUIRED).

Mechanic cancellation

Consecutive cancellations above a threshold (default: 3 in 30 days) → ₹100 penalty deducted from their wallet automatically.

Check for Unpaid Fees

GET /api/v1/payments/unpaid-fees
Authorization: Bearer ACCESS_TOKEN

{ "hasFees": true, "amount": 5000 }

Use the same create-order → Razorpay checkout → verify flow with type: "cancellation_fee".

Customers with unpaid fees cannot create new jobs (402 PAYMENT_REQUIRED). Always check on app launch and prompt payment if needed. Cancellation fees cannot be paid via COD — online payment is required.

Pricing Model

Component	Description	Example
`base_price`	Set per service category (in paisa)	35000 (₹350)
Line items	Parts + labor added by mechanic	10000 (₹100)
`final_price`	`base_price + SUM(line items)`	45000 (₹450)
Platform fee	10% of `final_price` (configurable BPS)	4500 (₹45)
Mechanic payable	`final_price − platform_fee` (always 90%)	40500 (₹405)
PG fee	Actual gateway cost (online only, platform expense)	~₹9 (varies)

All amounts in the API are in paisa. Always divide by 100 for display: ₹${(amount / 100).toFixed(0)}.

Client SDKs Required

SDK	Package	Purpose
Razorpay Flutter	`razorpay_flutter`	Payment checkout UI (online payments only)

The Razorpay Key ID will be provided via your app’s environment configuration. Do not hardcode it. COD payments require no additional SDKs.

Getting Started

Guides

Development

Overview

Architecture

Payment Method Selection

Online Payment Flow

Step-by-Step (Online)

Cash / COD Payment Flow

Step-by-Step (Cash / COD)

COD Ledger Entries

Platform Fee Split

Online vs COD Fee Handling

PG Fee Tracking

Webhook Processing

Checking Payment Status

Payment Statuses

Cancellation Fees

Customer cancellation

Mechanic cancellation

Check for Unpaid Fees

Pricing Model

Client SDKs Required

​Overview

​Architecture

​Payment Method Selection

​Online Payment Flow

​Step-by-Step (Online)

​Cash / COD Payment Flow

​Step-by-Step (Cash / COD)

​COD Ledger Entries

​Platform Fee Split

​Online vs COD Fee Handling

​PG Fee Tracking

​Webhook Processing

​Checking Payment Status

​Payment Statuses

​Cancellation Fees

​Customer cancellation

​Mechanic cancellation

​Check for Unpaid Fees

​Pricing Model

​Client SDKs Required

Overview

Architecture

Payment Method Selection

Online Payment Flow

Step-by-Step (Online)

Cash / COD Payment Flow

Step-by-Step (Cash / COD)

COD Ledger Entries

Platform Fee Split

Online vs COD Fee Handling

PG Fee Tracking

Webhook Processing

Checking Payment Status

Payment Statuses

Cancellation Fees

Customer cancellation

Mechanic cancellation

Check for Unpaid Fees

Pricing Model

Client SDKs Required