Skip to main content

Overview

Payment links in Flexprice provide a secure, hosted checkout experience powered by Razorpay. Customers click a payment URL and are redirected to Razorpay’s secure checkout page to complete their payment.

Key Features

  • Secure Checkout: Hosted by Razorpay with PCI compliance
  • Multiple Payment Methods: Cards, UPI, netbanking, wallets, and more
  • Real-time Updates: Webhook-driven status updates
  • Invoice Integration: Automatic invoice reconciliation
  • Auto-generated Links: Razorpay automatically generates payment link URLs

Payment Status Flow

Status Transitions

Status Definitions

When an Invoice Is Voided

When you void an invoice, Flexprice attempts to close its pending Razorpay payment links. For a Razorpay payment-link handle (plink_), it cancels the payment link. For a Razorpay invoice handle (inv_), it cancels the invoice. When cancellation succeeds, or a follow-up status check confirms that the link is already cancelled or expired, Flexprice changes the payment from PENDING to VOIDED. Payment links owned by a checkout session are skipped by this invoice-void step and left to the session. If Razorpay cancellation fails and a status check cannot confirm that the link is cancelled or expired, the payment remains PENDING and Flexprice logs the failure. If the status check finds the link is already paid, Flexprice leaves the payment for the Razorpay webhook instead of marking it VOIDED. Invoice voiding therefore does not guarantee that every Razorpay payment link is closed.

Prerequisites

  1. Razorpay Connection: Active Razorpay connection configured
  2. Customer Sync: Customer must have Razorpay customer ID
  3. Invoice Status: Invoice must be finalized and unpaid
  4. Valid Amount: Payment amount must match invoice outstanding
  5. Currency Minimums: Ensure amounts meet Razorpay minimums

Currency Minimum Amounts

Razorpay requires minimum amounts in the smallest currency subunit: Important: Amounts are automatically converted to smallest currency units (paise for INR, cents for USD) when creating payment links.

API Request

Endpoint: POST /api/v1/payments Headers:
Request Body:

Response

Note: The payment_url is automatically generated by Razorpay and returned as a short URL (e.g., https://rzp.io/i/abc123).
  1. Open an invoice with a balance due and select Record payment from the ⋯ menu.
  2. Choose Payment link under Method and select Razorpay as the Provider.
  3. Check the amount and click Create payment.
  4. Copy the URL from Payment link ready and send it to the customer.
The invoice menu’s Copy hosted invoice link action copies the Flexprice-hosted invoice page. To debit a saved method from the dashboard, see Recording a payment.

Required Fields

When creating payment links, Flexprice automatically configures Razorpay with:
  • Payment Methods: Cards, UPI, netbanking, wallets, and more
  • Currency: Matches the payment currency
  • Amount: Exact payment amount (converted to smallest unit)
  • Customer: Pre-filled with customer data
  • Description: Invoice details and line items
  • Notifications and reminders: Email, SMS, and payment reminders are off by default. Set gateway_options.razorpay.notify_customer to true on the payment request to enable all three.

Callback URL

Razorpay uses a single callback_url for both successful and cancelled payments:
  • Success: Customer is redirected to callback_url with payment details
  • Cancel: Customer is redirected to callback_url with cancellation status
  • Method: Only GET method is supported for payment links

Webhook Processing

Payment Completion Webhook

When a payment is completed, Razorpay sends a payment.captured webhook:

Webhook Processing Flow

  1. Receive Webhook: Flexprice receives the webhook from Razorpay
  2. Verify Signature: Validate webhook signature for security
  3. Find Payment: Locate payment record using payment ID from notes
  4. Update Status: Change payment status to SUCCEEDED
  5. Reconcile Invoice: Update invoice payment status and amounts
  6. Trigger Events: Send payment completion events

Error Handling

Common Payment Errors

When link creation fails during checkout, the session stores the rejection reason in failure_reason. This differs from a declined payment on an existing link, which remains available for retry.

Payment Failure Handling

When a customer’s payment on a payment link is declined:
  1. Webhook Received: Razorpay sends payment.failed webhook
  2. Attempt Recorded: Flexprice records the failed attempt with the decline reason and sends payment.attempt.failed
  3. Payment Stays Open: The payment is not marked FAILED, and the link stays live
  4. Retry Available: The customer retries on the same link
Without a checkout session, a decline also leaves the payment open; for a session-backed link, checkout cleanup archives the payment, and a decline received after the session is no longer pending marks the payment FAILED.

Test Environment Setup

  1. Use Test Keys: Configure Razorpay test mode
  2. Test Cards: Use Razorpay’s test card numbers
  3. Test Webhooks: Use ngrok for local webhook testing

Test Card Numbers

Test Cards for Indian Payments

Test Cards for International Payments

Test UPI IDs

To use the test UPI ID details:

  1. At the Checkout, select UPI as the payment method
  2. Enter the UPI ID
  3. Test payment success flow using success@razorpay
  4. Test payment failure flow using failure@razorpay
Watch Out!In test mode, payment cancellation will result in a successful payment. Use the live mode to test payment cancellation on UPI.

Testing Flow

  1. Create Test Payment: Use test invoice and customer
  2. Generate Payment Link: Create payment with test data
  3. Complete Payment:
    • Use test card numbers listed above in Razorpay checkout
    • Or use test UPI ID success@razorpay for UPI payments
  4. Verify Webhook: Check webhook processing
  5. Confirm Status: Verify payment and invoice updates

Invoice Integration

When an invoice is synced to Razorpay:
  1. Invoice Sync: Invoice is created in Razorpay with payment URL
  2. Payment Link Reuse: If payment link is requested for synced invoice, the existing Razorpay invoice payment URL is returned
  3. Automatic Association: Payments made through the URL are automatically associated with the invoice

Invoice Sync Timing

Invoices are automatically synced to Razorpay when:
  • Invoice is finalized (status changes from DRAFT to FINALIZED)
  • Invoice outbound sync is enabled in the Razorpay connection
  • Customer is successfully synced to Razorpay

Security Considerations

  • HTTPS Required: All payment links use HTTPS
  • Link Expiry: Links expire based on Razorpay settings
  • One-time Use: Each link can only be used once
  • Signature Verification: All webhooks verified

Data Protection

  • PCI Compliance: Razorpay handles sensitive payment data
  • No Card Storage: Card details never stored in Flexprice
  • Encrypted Storage: All payment data encrypted at rest
  • Access Controls: Role-based access to payment data

Webhook Endpoints

  • POST /api/v1/webhooks/razorpay/{tenant_id}/{environment_id} - Razorpay webhook handler
For complete API documentation, see the API Reference.