> ## Documentation Index
> Fetch the complete documentation index at: https://public-openfx.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# INR payout integration guide

> Pay an Indian bank account in INR: set up the sender and receiver, register the bank account, and pay regular or NRE accounts.

Pay a receiver's Indian bank account in INR.

This guide covers only what's specific to India. For the general flow, see [Payouts](/v3/payouts). INR payouts differ in four ways:

* Every INR payout names a sender.
* The sender, the receiver, and the bank account must all be set up for the same kind of Indian account: regular or NRE.
* The bank account is identified by IFSC and account number.
* The name check runs once, when you register the bank account, and every later payout reuses it.

## Set up the accounts and payout address

You do this once per receiver. All three must be <span class="ofx-enum">ACTIVE</span> before you can pay. [Account model](/v3/account-model#the-shared-state-machine) explains each status.

| Resource | Needs |
| - | - |
| Sender `Account` | An <span class="ofx-enum">ACTIVE</span> INR-sending capability |
| Receiving account | An <span class="ofx-enum">ACTIVE</span> INR-receiving capability |
| `PayoutAddress` | The receiver's Indian bank account |

Both accounts must be individuals. INR doesn't support organizations as sender or receiver.

### How repatriability pairs

An Indian bank account is either NRE (funded from abroad and freely repatriable) or regular (NRO and ordinary resident accounts). The bank account says which with `isNre`, and each capability covers one kind, shown by `repatriability` in its `details`.

**All three must match**: the sender's capability, the receiver's capability, and the bank account's `isNre`. This guide pays a regular account (`isNre: false`), so it uses the non-repatriable capabilities throughout. [NRE accounts](#nre-accounts) covers what changes for NRE.

* The **receiver** owns the bank account and needs a non-repatriable INR-receiving capability.
* The **sender** is the person the money comes from. They need a non-repatriable INR-sending capability, and every INR payout names them in `sender`.

<Steps>
  <Step title="Create the sender account">
    Create the sender first, since its capability must be <span class="ofx-enum">ACTIVE</span> before a payout can name it. The sender needs a legal name, a phone number, and either a PAN or an identity document, wherever they live. [Capabilities](/v3/capabilities#be-named-as-the-sender-to-a-regular-indian-account) has the full list. This sender lives in India, so the example uses their Aadhaar, sent as a <span class="ofx-enum">NATIONAL\_ID</span> in `documents[]`.

    ```bash cURL theme={"theme":{"light":"poimandres","dark":"poimandres"}}
    curl -X POST https://api.openfx.com/v3/common/accounts \
      -H "Authorization: Bearer $OPENFX_JWT" \
      -H "X-Request-Signature: $OPENFX_SIGNATURE" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{
        "capabilities": ["cap_R2EcnNENdJX6suu2SWM2fs"],
        "identity": {
          "identityType": "INDIVIDUAL",
          "individual": {
            "firstName": "Arjun",
            "lastName": "Rao",
            "phoneNumber": "+919876543210",
            "documents": [{ "type": "NATIONAL_ID", "number": "365412782093", "issuingCountry": "IN" }]
          }
        },
        "label": "Arjun Rao"
      }'
    ```

    Wait until the sender's capability is <span class="ofx-enum">ACTIVE</span> before naming them on a quote. The payout checks the capability and its repatriability again.
  </Step>

  <Step title="Create the receiver account">
    Create the account you're paying, with a non-repatriable INR-receiving capability. The receiver needs only a name and a phone number, with no identity document.

    ```bash cURL theme={"theme":{"light":"poimandres","dark":"poimandres"}}
    curl -X POST https://api.openfx.com/v3/common/accounts \
      -H "Authorization: Bearer $OPENFX_JWT" \
      -H "X-Request-Signature: $OPENFX_SIGNATURE" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{
        "capabilities": ["cap_R8mRkY9V6dXFFpFrff3mDw"],
        "identity": {
          "identityType": "INDIVIDUAL",
          "individual": { "firstName": "Nadia", "lastName": "Mehta", "phoneNumber": "+919812345678" }
        },
        "label": "Nadia Mehta"
      }'
    ```

    Wait for [`common.account.capability_activated`](/v3/webhooks/payments/accounts-webhooks/account-capability-activated) before you pay this account. You don't need to wait to register the bank account, so do both at the same time.
  </Step>

  <Step title="Create the Indian bank account payout address">
    Use `routingFamily: "IN_LOCAL"` with an `ifsc` and an `accountNumber`. Always set `isNre`: it says which kind of account this is, and the receiver's capability must match it.

    ```bash cURL theme={"theme":{"light":"poimandres","dark":"poimandres"}}
    curl -X POST https://api.openfx.com/v3/payments/payout-addresses \
      -H "Authorization: Bearer $OPENFX_JWT" \
      -H "X-Request-Signature: $OPENFX_SIGNATURE" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{
        "payoutAddressType": "BANK_ACCOUNT",
        "accountId": "acc_BMY3UenpGBn8ZQ8hio4BgE",
        "bankAccount": {
          "routingFamily": "IN_LOCAL",
          "accountHolderName": "Nadia Mehta",
          "ifsc": "HDFC0001234",
          "accountNumber": "50100234567890",
          "isNre": false,
          "bankAccountType": "SAVINGS"
        }
      }'
    ```

    A penny drop (<span class="ofx-enum">IMPS\_PENNY\_DROP</span>) runs during the call. It compares `accountHolderName` with the name the bank returns, and checks `isNre` against the bank's records. Both finish before the response, so its `status` already shows the result. The address comes back <span class="ofx-enum">REJECTED</span> if the result is <span class="ofx-enum">NO\_MATCH</span> (the bank has a different holder) or <span class="ofx-enum">ACCOUNT\_TYPE\_MISMATCH</span> (the name matches but `isNre` doesn't). Later payouts reuse this check instead of running a new one.
  </Step>
</Steps>

## Price and create the payout

<Steps>
  <Step title="(Optional) List the financial accounts that can fund an INR payout">
    An INR payout is funded from a balance in another currency and converted.

    ```bash cURL theme={"theme":{"light":"poimandres","dark":"poimandres"}}
    curl "https://api.openfx.com/v3/common/financial-accounts?receiveCurrency=INR" \
      -H "Authorization: Bearer $OPENFX_JWT" \
      -H "X-Request-Signature: $OPENFX_SIGNATURE"
    ```
  </Step>

  <Step title="Quote the payout">
    Get a price before you create the payout, naming the sender in `sender`. OpenFX picks the Indian payment rail for you, and the quote shows it in `rail`.

    ```bash cURL theme={"theme":{"light":"poimandres","dark":"poimandres"}}
    curl -X POST https://api.openfx.com/v3/payments/payout-quotes \
      -H "Authorization: Bearer $OPENFX_JWT" \
      -H "X-Request-Signature: $OPENFX_SIGNATURE" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{
        "financialAccountId": "finacc_AmKC5dMVXUbiAW8VzKBfqz",
        "receiver": { "payoutAddressId": "pytadd_PbDQ126YUAbkNrNX6XbGL" },
        "sendAmount": "1000.00",
        "receiveCurrency": "INR",
        "quoteForSeconds": 60,
        "sender": { "accountId": "acc_2BkQn4xCSUk8aUDc9oktTw" }
      }'
    ```

    `fees` includes the <span class="ofx-enum">NETWORK\_FEE</span> every INR payout pays. A payout to a regular account (`isNre: false`) can also include a <span class="ofx-enum">RESIDENT\_DISCOUNT</span>, a negative amount. The conversion cost isn't listed separately: it's already in `fxRates.client`.
  </Step>

  <Step title="Create the payout from the quote">
    The payout takes the sender from the quote, so don't name it again. There's no new name check: the payout reuses the one from address setup, so the `AccountHolderNameConfirmation` in `confirmations[]` has timestamps from before the payout.

    ```bash cURL theme={"theme":{"light":"poimandres","dark":"poimandres"}}
    curl -X POST https://api.openfx.com/v3/payments/payouts \
      -H "Authorization: Bearer $OPENFX_JWT" \
      -H "X-Request-Signature: $OPENFX_SIGNATURE" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "FROM_QUOTE",
        "quoteId": "pytqte_5PKPvtstSbXf9BurnLJfLA",
        "receiverMemo": "Support June 2026"
      }'
    ```

    The reused result isn't always <span class="ofx-enum">MATCH</span>. A failing result would already have rejected the address, and paying a rejected address fails with `409` <span class="ofx-enum">PAYOUT\_ADDRESS\_REJECTED</span>.
  </Step>

  <Step title="Confirm the payout">
    [Confirm the payout](/v3/api-reference/payments/payouts/confirm-payout) to accept everything in `confirmations[]` and move it to <span class="ofx-enum">ACCEPTED</span>.

    ```bash cURL theme={"theme":{"light":"poimandres","dark":"poimandres"}}
    curl -X POST https://api.openfx.com/v3/payments/payouts/pyt_9P3Gs3GSn4hMdHQ22Evi5f/confirm \
      -H "Authorization: Bearer $OPENFX_JWT" \
      -H "X-Request-Signature: $OPENFX_SIGNATURE" \
      -H "Idempotency-Key: $(uuidgen)"
    ```
  </Step>
</Steps>

## Track settlement and the trace reference

After <span class="ofx-enum">ACCEPTED</span>, the payout settles in the background. See [Payouts](/v3/payouts#send-the-payout) for each status and webhook. Once the payment is sent, `settlementTraceId` carries the bank's reference: an RRN on <span class="ofx-enum">IMPS</span>, or a UTR on <span class="ofx-enum">NEFT</span> and <span class="ofx-enum">RTGS</span>. `key` names the type and `value` holds the reference.

## NRE accounts

Paying an NRE account needs its own setup at both ends. Only three things change:

* The bank account sets `isNre: true`, and the receiver needs the repatriable INR-receiving capability.
* The sender needs the repatriable INR-sending capability, <span class="ofx-enum">ACTIVE</span> before the quote.
* Both ends need more identity details. [Capabilities](/v3/capabilities#identity-requirements) lists them.

```bash cURL theme={"theme":{"light":"poimandres","dark":"poimandres"}}
curl -X POST https://api.openfx.com/v3/common/accounts \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": ["cap_BTfPKkGd8ttTQjf3bxA22g"],
    "identity": {
      "identityType": "INDIVIDUAL",
      "individual": {
        "firstName": "Priya",
        "lastName": "Mehta",
        "nationality": "IN",
        "dateOfBirth": "1988-11-02",
        "phoneNumber": "+493012345678",
        "residentialAddress": { "line1": "Kastanienallee 12", "city": "Berlin", "country": "DE" },
        "documents": [{ "type": "PASSPORT", "number": "Z1234567", "issuingCountry": "IN" }]
      }
    },
    "label": "Priya Mehta"
  }'
```

Set up the receiver the same way, with the repatriable INR-receiving capability and a `nationality` and phone number. An account that uses both kinds requests both capabilities when you create it, and each has its own status. NRE payouts don't get the <span class="ofx-enum">RESIDENT\_DISCOUNT</span>.

## Common mistakes

* **Mixing regular and NRE.** The sender's capability, the receiver's capability, and the bank account's `isNre` must all match. A mismatch fails with `409` <span class="ofx-enum">CAPABILITY\_NOT\_ACTIVE</span>.
* **Leaving out `sender`.** Every INR payout needs one, and a sender whose capability isn't <span class="ofx-enum">ACTIVE</span> fails the same way a receiver would.
* **Expecting a name check on every payout.** It runs once, when you register the bank account. A rejected address can't be fixed, only replaced.
* **Leaving out the phone number.** Every INR capability needs `identity.individual.phoneNumber`, unless OpenFX has waived it for your organization.
* **Registering an NRE sender who lives in India.** An NRE sender's `residentialAddress.country` can't be `IN` or a sanctioned country.

## What's next

<CardGroup cols={2}>
  <Card title="Payouts" icon="https://public-assets.openfx.com/docs/icons/withdrawals.svg" href="/v3/payouts">
    The general payout flow.
  </Card>

  <Card title="EUR payout integration guide" icon="https://public-assets.openfx.com/currencies/EUR.svg" href="/v3/eur-payout-integration">
    Paying euro accounts over SEPA or SWIFT.
  </Card>

  <Card title="Capabilities" icon="https://public-assets.openfx.com/docs/icons/capabilities.svg" href="/v3/capabilities#identity-requirements">
    Every INR capability's id and identity requirements.
  </Card>

  <Card title="Payment Webhooks" icon="https://public-assets.openfx.com/docs/icons/webhooks-setup.svg" href="/v3/webhooks/payments/payouts-webhooks/payout-created">
    Every payout, account, and address event.
  </Card>
</CardGroup>