> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tirdad.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Autopay & Mandates

> Collect a recurring payment mandate once at checkout, then let future invoices charge automatically

A mandate is a one-time authorization from your customer that lets Tirdad charge their future invoices without asking them to pay each time. The lifecycle has three phases: the customer **registers** the mandate once at checkout, the **first charge** runs, and every invoice after that **auto-debits** in the background.

Razorpay Checkout supports three collection methods:

| Method | What the customer does | Future invoices |
| - | - | - |
| Payment link (default) | Pays a one-time hosted link | Each one needs a new link |
| UPI Autopay mandate | Authorizes a recurring UPI mandate once | Auto-charged, no customer action |
| Card mandate | Saves a card and authorizes recurring charges once | Auto-charged, no customer action |

Use a mandate when the customer will be billed repeatedly — a subscription, metered usage, or wallet top-ups. Use the [one-time payment link](https://docs.tirdad.ai/docs/checkout/checkout-sessions.md) when there is a single payment and nothing recurring.

## Prerequisites

* **Razorpay connection** with invoice sync enabled. Set `sync_config.invoice.outbound: true` when you [connect Razorpay](https://docs.tirdad.ai/integrations/razorpay/connection-setup.md) so future invoices sync automatically.
* **Customer `contact` (phone number).** A mandate registration is rejected without it (`"The contact field is required"`). The requirement comes from Razorpay's authorization step, so set `contact` when you create the customer if you plan to use autopay.
* **A plan and price** in the currency you will charge. The examples below use `INR`.

> [!WARNING]
>
> Set `contact` at customer-creation time. Adding it later does not
> retroactively fix a mandate registration that already failed — you will need
> to start a new checkout.

## Register a mandate at checkout

Create a checkout session and include `payment_provider_config`. This is what switches the session from a one-time payment link to a mandate registration.

```bash theme={null}
curl -X POST https://api.tirdad.ai/v1/checkout/sessions \
  -H "x-api-key: <API_KEY>" \
  -H "X-Environment-ID: <ENVIRONMENT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_external_id": "cust_abc123",
    "action": "create_subscription",
    "payment_provider": "razorpay",
    "configuration": {
      "create_subscription_params": {
        "plan_id": "plan_xyz",
        "currency": "INR",
        "billing_period": "monthly"
      }
    },
    "payment_provider_config": {
      "collection_method": "charge_automatically",
      "payment_method": "UPI",
      "max_mandate_limit": "5000"
    },
    "success_url": "https://app.example.com/checkout/success",
    "cancel_url": "https://app.example.com/checkout/cancel"
  }'
```

The response is the same shape as any checkout session — a `payment_action.url`, this time a Razorpay UPI Autopay authorization link:

```json theme={null}
{
  "id": "chk_01HXXX",
  "checkout_status": "pending",
  "payment_action": {
    "type": "payment_link",
    "url": "https://rzp.io/l/XXXXXXX"
  }
}
```

Redirect the customer to `payment_action.url`. They authorize the mandate once in their UPI app.

### payment\_provider\_config fields

| Field | Required | Description |
| - | - | - |
| `collection_method` | Yes | Set to `charge_automatically` to register a mandate. Omit `payment_provider_config` entirely for the default one-time payment link. |
| `payment_method` | Yes | `UPI` for UPI Autopay, `CARD` for a card mandate. |
| `max_mandate_limit` | Yes | Ceiling, in the major currency unit (e.g. rupees), for any single future auto-charge. Invoices above this are not auto-charged. |

### Card mandate

A card mandate uses the same request. Change `payment_method` to `CARD`:

```json theme={null}
"payment_provider_config": {
  "collection_method": "charge_automatically",
  "payment_method": "CARD",
  "max_mandate_limit": "5000"
}
```

The response is the same — a Razorpay-hosted link where the customer enters card details and authorizes recurring charges. Everything after authorization works identically to UPI.

## What happens after authorization

Once the customer authorizes, Razorpay confirms the mandate (`token.confirmed`) and captures the first payment (`payment.captured`). Tirdad marks the checkout session `completed`, activates the subscription, and finalizes the invoice — the same completion path as a one-time payment link.

From then on, every new invoice for that customer is checked for a usable saved token and charged automatically, with no further customer action. This applies to subscription renewals, and also to one-off invoices and wallet top-up invoices.

An invoice falls back to a normal Razorpay payment link when there is no usable saved token, or when the invoice amount exceeds `max_mandate_limit`. The fallback is automatic and safe to rely on — the customer receives a link to pay that invoice manually.

> [!NOTE]
>
> `max_mandate_limit` is a hard ceiling, not a soft warning. An invoice above it
> never auto-charges; it always falls back to a payment link. Set the limit high
> enough to cover your largest expected invoice.

## Gotchas

* **`contact` is mandatory** to register a mandate. Collect it at customer creation — see [Prerequisites](#prerequisites).
* **`max_mandate_limit` is a hard ceiling.** Invoices above it fall back to a payment link rather than auto-charging. This is an intentional safety cap.
* **Currency casing.** Send `currency` in any casing — Tirdad normalizes it to uppercase before calling Razorpay.

> [card] [Razorpay Setup](https://docs.tirdad.ai/docs/checkout/razorpay-checkout.md)
>
> Enable the webhook events, including the mandate events autopay needs.

> [card] [Checkout Sessions API](https://docs.tirdad.ai/docs/checkout/checkout-sessions.md)
>
> Full field reference for the create session call.

> [card] [Implementation Guide](https://docs.tirdad.ai/docs/checkout/implementation-guide.md)
>
> End-to-end integration with webhook handling.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.