Hosted & Direct B2B Payments

Mode 1 · RAZORPAY_CHECKOUT

The source guide describes a hosted payment gateway. Application creation returns tracking_id, payment_mode and a signed checkout_url. The end user completes payment in a Tax Genius-hosted checkout, while the partner reconciles the asynchronous payment state.

• Create a case using an enabled application endpoint.
• Display only the signed checkout_url returned by your server; do not construct a checkout URL manually.
• Process the payment.successful webhook on your backend after HMAC verification.
• Verify current application/payment status server-side before treating the payment as settled.

A payment-success browser message is a UI hint, not proof of settlement. Validate event.origin and request status from your server.

Mode 2 · CUSTOM_DIRECT

Under a negotiated wholesale agreement, the partner collects payment in its own customer-facing experience. The source guide says the application responds with checkout_url: null and is recorded as payment-successful through the customised partner billing process.

• This mode must be enabled on the vendor account during onboarding.
• Do not infer eligibility simply because the application form requests CUSTOM_DIRECT.
• Partner wholesale billing, rate cards and monthly invoicing require a separate contractual agreement.

Checkout verification endpoint

The uploaded guide documents POST /checkout/verify with application_id, razorpay_payment_id, razorpay_order_id and razorpay_signature.

The guide specifies X-API-Key but omits X-API-Secret on checkout verification. This security contract must be reconciled against the production backend before enabling the operation.

Settlement reconciliation checklist

• Store checkout identifiers and tracking_id in the partner backend.
• Verify signed notifications against the original request bytes.
• Handle duplicate and out-of-order notifications idempotently.
• Treat browser closures and timeouts as unknown payment state until verified server-side.