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

# 印度支付方式

> 接受来自印度客户的 UPI、印度发行的银行卡和 Apple Pay，并以 INR 结算。了解 RBI 订阅授权、48 小时延迟以及授权限额。

接受来自印度客户的 UPI、印度发行的银行卡（Visa、Mastercard 和 RuPay）以及 Apple Pay。按交易量计算，UPI 占印度数字支付交易的 80% 以上。Dodo Payments 通过符合 RBI 规定的授权，支持使用 UPI 和印度发行的银行卡进行订阅。

## 为什么印度的支付方式很重要

<CardGroup cols={3}>
  <Card title="UPI Dominance" icon="mobile">
    UPI 每月处理超过 200 亿笔交易，而且许多印度客户没有国际银行卡。
  </Card>

  <Card title="Low-Value Payments" icon="indian-rupee-sign">
    UPI 适合高交易量、低金额的交易。
  </Card>

  <Card title="Subscription Support" icon="repeat">
    与大多数替代支付方式不同，UPI 和印度发行的银行卡（包括 Visa、Mastercard 和 RuPay）可通过 RBI 授权指令支持定期付款。
  </Card>
</CardGroup>

## 支持的方式

下表列出了每种方式，以及其是否支持订阅：

| 方式 | 类型 | 订阅 |
| :- | :- | :-: |
| **UPI** | 二维码 | 是\* |
| **RuPay Credit** | 银行卡 | 是\* |
| **RuPay Debit** | 银行卡 | 是\* |
| **Apple Pay** | 数字钱包 | 是\* |

\*订阅需要符合 RBI 规定的授权，并遵循特殊的处理规则。所有印度发行的银行卡、UPI 和 Apple Pay 的定期扣款均适用 48 小时处理延迟。

以 INR 结算的付款金额必须至少为 ₹5.00，并且至少达到 USD 最低金额的等值金额：一次性付款为 \$0.50，订阅为 \$1.00。请参阅[最低金额](/features/adaptive-currency#minimum-amounts)。

## 配置

### API Method Types

在 `allowed_payment_method_types` 中传入以下值：

| 类型 | 描述 |
| :- | :- |
| `upi_intent` | 通过二维码使用 UPI |
| `credit` | 信用卡，包括 RuPay |
| `debit` | 借记卡，包括 RuPay |
| `apple_pay` | 在 Apple 设备上使用 Apple Pay。请参阅[印度的 Apple Pay](/features/payment-methods/digital-wallets#apple-pay-in-india) |

<Warning>
  Checkout 仅将 UPI 作为 `upi_intent` 提供。如果 `allowed_payment_method_types` 列出了 `upi_collect`，但未列出 `upi_intent`，UPI 就不会显示在 Checkout 中。
</Warning>

### 示例：面向印度的 Checkout

此结账会话向一位位于印度、以 INR 结算的客户提供 UPI、银行卡和 Apple Pay：

```javascript theme={null}
// `client` is an initialized DodoPayments client.
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: [
    'upi_intent',
    'credit',
    'debit',
    'apple_pay'
  ],
  billing_currency: 'INR',
  customer: {
    email: 'customer@example.com',
    name: 'Priya Sharma',
    phone_number: '+919876543210'
  },
  billing_address: {
    country: 'IN',
    zipcode: '560001'
  },
  return_url: 'https://example.com/success'
});
```

### UPI 的要求

仅当以下所有条件均满足时，UPI 才会显示在 Checkout 中：

1. **billing country** 为印度（`IN`）。
2. **billing currency** 为 INR。
3. 对于印度境外 merchant 的订阅，已启用 **Adaptive Currency**。如果产品以 INR 定价，一次性 Checkout 不需要启用该功能。

<Warning>
  如果你是印度境外的 merchant 且已禁用 Adaptive Currency，客户将无法使用 UPI 支付订阅。
</Warning>

## 使用 RBI Mandates 的订阅

使用 UPI 或印度发行的银行卡支付的订阅基于 RBI（Reserve Bank of India）mandates，这些 mandates 会增加其他支付方式没有的规则。

### RBI Mandates 的工作方式

客户订阅时会授权一个 mandate。之后，每次续订扣款都会在预扣款通知后等待 48 小时，银行才会扣除资金：

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant Your App
    participant Dodo
    participant Bank
    
    Customer->>Your App: Subscribe
    Your App->>Dodo: Create subscription
    Dodo->>Bank: Create mandate
    Bank->>Customer: Authorize mandate
    Customer->>Bank: Approve (billing amount or mandate floor)
    Bank->>Dodo: Mandate active
    
    Note over Dodo,Bank: On renewal date...
    
    Dodo->>Bank: Initiate charge
    Note over Bank: 48-hour window starts
    Bank->>Customer: Pre-debit notification
    Note over Bank: After 48 hours...
    Bank->>Dodo: Debit completed
    Dodo->>Your App: payment.succeeded webhook
```

### Mandate 类型

Mandate 类型取决于订阅金额与 mandate floor 的比较结果：

| 订阅金额 | Mandate 类型 | 限额 |
| :- | :- | :- |
| **低于 mandate floor** | On-demand mandate | Mandate floor（默认 ₹15,000） |
| **等于或高于 mandate floor** | Fixed-amount mandate | 确切的订阅金额 |

在客户银行登记的金额为 `max(mandate_floor, billing_amount)`。当计费金额低于该 floor 时，floor 就会成为面向客户的 **authorization ceiling**。

\*\*Plan changes：\*\*如果升级产生的扣款超过现有 mandate limit，扣款会失败，客户必须重新授权。

### 可配置的 Mandate Floor

使用 `mandate_min_amount_inr_paise` 字段设置 INR e-mandates 的 mandate floor，单位为 **INR paise**（₹1 = 100 paise）。

<Warning>
  此设置仅影响在 INR 订阅中为印度发行的银行卡（Visa、Mastercard、RuPay）登记的 e-mandates。UPI 订阅遵循自己的 AutoPay flow，不受此设置影响。
</Warning>

你可以在以下三个级别覆盖系统默认值 ₹15,000：

| 级别 | 设置位置 | 范围 |
| - | - | - |
| **Per request** | Checkout session 或 subscription 中的 `mandate_min_amount_inr_paise` | 单笔交易 |
| **Merchant** | Business-level default（如果已配置） | 你的所有 INR 订阅 |
| **System** | — | 默认 ₹15,000 |

Dodo Payments 使用第一个已设置的值：先使用 per-request override，然后是 merchant setting，最后是 system default。

要设置 floor，请在[创建 Checkout session](/api-reference/checkout-sessions/create)时，在 request body 中传入 `mandate_min_amount_inr_paise`。已弃用的 [Create Subscription](/api-reference/subscriptions/post-subscriptions) endpoint 也接受相同字段。

```typescript theme={null}
// `client` is an initialized DodoPayments client.
// Per-checkout override
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_inr_monthly', quantity: 1 }],
  mandate_min_amount_inr_paise: 2_000_000, // ₹20,000 ceiling
  return_url: 'https://yoursite.com/return'
});

// Per-subscription override
// Note: POST /subscriptions is deprecated — prefer checkout sessions for new integrations
const subscription = await client.subscriptions.create({
  product_id: 'pdt_inr_monthly',
  quantity: 1,
  customer: { email: 'customer@example.com' },
  billing: { country: 'IN', zipcode: '560001' },
  mandate_min_amount_inr_paise: 2_000_000
});
```

该字段接受以下值：

| 字段 | 类型 | 验证 | 适用范围 |
| - | - | - | - |
| `mandate_min_amount_inr_paise` | `integer`（INR paise） | `>= 1` | 非 Airwallex connectors 上的印度银行卡 INR 订阅 |

<Info>
  更高的 floor 允许你之后进行更大金额的一次性扣款，例如计划升级或基于用量的超额扣款，而无需客户重新授权。较低的 floor 会使客户的授权金额更接近实际计费金额，但也会减少未来可变扣款的空间。
</Info>

### 48 小时处理延迟

印度银行卡或 UPI 的续订扣款会在续订日期约 48 小时后完成。这是它与国际银行卡付款最重要的区别：

<Steps>
  <Step title="Charge Initiated (Day 0)">
    在预定的续订日期，Dodo Payments 会向银行发起扣款。
  </Step>

  <Step title="Pre-Debit Notification">
    客户的银行会通知客户即将发生扣款。
  </Step>

  <Step title="48-Hour Window">
    在此期间，客户可以在银行 app 中取消 mandate。
  </Step>

  <Step title="Debit Completed (~48-51 Hours)">
    48 小时后，银行还可能需要最多 3 小时进行处理，之后才会扣除资金。
  </Step>

  <Step title="Webhook Sent">
    Dodo Payments 会在实际扣款后，而不是在发起扣款时，发送 `payment.succeeded` webhook。
  </Step>
</Steps>

<Warning>
  \*\*不要在发起扣款时授予权益。\*\*请等待 `payment.succeeded` webhook，该 webhook 会在预定扣款日期后的约 48–51 小时到达。
</Warning>

### 处理 48 小时窗口

根据 payment webhook（而不是续订日期）授予访问权限：

```javascript theme={null}
// grantPremiumAccess and revokePremiumAccess are your own access-control functions.

// DON'T do this:
async function handleSubscriptionRenewal(subscription) {
  // Bad: Granting access immediately when charge is initiated
  grantPremiumAccess(subscription.customer.customer_id);
}

// DO this:
async function handlePaymentWebhook(event) {
  if (event.type === 'payment.succeeded') {
    // Good: Only grant access after payment is confirmed
    grantPremiumAccess(event.data.customer.customer_id);
  }
  
  if (event.type === 'payment.failed') {
    // Handle failed payment (mandate cancelled, insufficient funds)
    revokePremiumAccess(event.data.customer.customer_id);
  }
}
```

### 印度订阅的 Webhook 事件

为使用 UPI 或印度发行的银行卡支付的订阅处理以下事件：

| 事件 | 时间 | 操作 |
| :- | :- | :- |
| `subscription.active` | Mandate 已授权 | 记录订阅开始 |
| `payment.succeeded` | 扣款日期后约 48 小时 | 授予/继续访问权限 |
| `payment.failed` | 扣款失败 | 通知客户，暂停访问权限 |
| `subscription.on_hold` | 付款失败 | 提示更新 payment method |
| `subscription.active` | 付款后重新激活 | 恢复访问权限 |

## 测试

### UPI 测试 ID

在 test mode 中输入以下 UPI ID，以模拟各类结果：

| 状态 | UPI ID |
| :- | :- |
| 成功 | `success@upi` |
| 失败 | `failure@upi` |

### 印度银行卡测试号码

使用以下印度发行的测试银行卡：

| Brand | 场景 | Card Number | Expiry | CVV |
| :- | :- | :- | :- | :- |
| Visa | 成功 | `4576238912771450` | 06/32 | 123 |
| Visa | 被拒绝 | `4706131211212123` | 06/32 | 123 |
| Mastercard | 成功 | `5409162669381034` | 06/32 | 123 |
| Mastercard | 被拒绝 | `5105105105105100` | 06/32 | 123 |

## 最佳实践

<AccordionGroup>
  <Accordion title="Plan for the 48-hour delay">
    构建应用时，应处理扣款发起与实际付款之间的时间差。请考虑：

    * 订阅访问权限的宽限期
    * 清晰地向客户说明处理时间
    * 由 webhook 驱动的履约，而不是由日期驱动的履约
  </Accordion>

  <Accordion title="Handle mandate cancellations">
    客户可以随时在银行 app 中取消 mandates。监控 `subscription.on_hold` webhooks，并提示客户重新订阅或更新 payment method。
  </Accordion>

  <Accordion title="Set appropriate mandate amounts">
    对于基于用量计费等可变定价，请检查 mandate floor 上的 on-demand mandate（默认为 ₹15,000）是否足以覆盖最大扣款。如果扣款金额可能超过该值，请通过 [`mandate_min_amount_inr_paise`](#configurable-mandate-floor) 提高 floor。否则，客户必须授权新的 mandate。
  </Accordion>

  <Accordion title="Offer UPI prominently">
    对于印度客户，请将 UPI 设为主要支付选项。许多客户更偏好 UPI 而不是银行卡，因为他们更熟悉这种方式，操作阻力也更小。
  </Accordion>
</AccordionGroup>

## 故障排查

<AccordionGroup>
  <Accordion title="UPI not appearing at checkout">
    **检查：**

    1. billing country 是否设置为 `IN`？
    2. billing currency 是否设置为 `INR`？
    3. 如果你是印度境外的 merchant，是否已启用 Adaptive Currency？
    4. `upi_intent` 是否包含在 `allowed_payment_method_types` 中？

    \*\*解决方案：\*\*在 billing address 中设置 `country: "IN"`，并设置 `billing_currency: "INR"`。如果已禁用 Adaptive Currency，API 会忽略 `billing_currency`，因此请改为使用 INR 为产品定价。
  </Accordion>

  <Accordion title="Subscription charge failed after upgrade">
    \*\*原因：\*\*新的扣款金额超过了现有 mandate limit：即 mandate floor（默认为 ₹15,000），或订阅金额（如果订阅金额更高）。

    \*\*解决方案：\*\*客户必须更新 payment method，以使用正确的限额设置新的 mandate。
  </Accordion>

  <Accordion title="Subscription on hold but customer claims they didn't cancel">
    \*\*原因：\*\*客户可能在 48 小时窗口内取消了 mandate，或者其银行拒绝了扣款。

    \*\*解决方案：\*\*客户需要再次授权 mandate，或更新 payment method。
  </Accordion>

  <Accordion title="Payment deduction delayed beyond 48 hours">
    \*\*原因：\*\*银行 API 延迟可能使处理时间延长 2–3 小时。

    \*\*解决方案：\*\*这是预期行为。请构建系统以处理总计约 51 小时的延迟。
  </Accordion>

  <Accordion title="Mandate cancelled but subscription still active">
    \*\*原因：\*\*RBI regulations 中存在一种边界情况：在处理窗口内取消 mandate 不会立即取消订阅。

    \*\*解决方案：\*\*下一次扣款会失败，订阅会变为 `on_hold`。监控 `payment.failed` webhooks。
  </Accordion>
</AccordionGroup>

## 相关页面

<CardGroup cols={2}>
  <Card title="Payment Methods Overview" icon="credit-card" href="/features/payment-methods">
    查看所有支持的支付方式。
  </Card>

  <Card title="Subscriptions" icon="repeat" href="/features/subscription">
    完整的订阅文档，包括 RBI mandates。
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    支付事件的 webhook 处理。
  </Card>

  <Card title="Testing Process" icon="flask" href="/miscellaneous/testing-process">
    所有测试数据，包括 UPI ID 和印度银行卡。
  </Card>
</CardGroup>


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