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

# Remittance Payout Integration Guide

<Highlight># Remittance Payout Integration Guide</Highlight>

## What Is a Remittance Payout

A remittance payout is a crypto-to-fiat payout made on behalf of a remittance user: someone sending money to a beneficiary in India, rather than a customer cashing out their own funds. The flow reuses the standard [Payout](/api-reference-exchange/integration-guides/payout-integration-guide) building blocks (customer, bank account, quotation, status tracking) and adds two things: a PAN-only KYC for the beneficiary, and a remitter record that identifies the sending party.

<Note>
  The beneficiary of a remittance payout is a DollarPe Customer, but they skip the full document KYC flow. Instead, submit the customer's tax number (PAN) once via [Remittance Beneficiary KYC](/api-reference-exchange/endpoint/kyc/remittance-beneficiary-kyc) after creating the customer.
</Note>

## Integration at a Glance

1. **Create the beneficiary customer.** Register the receiving party via `/customer/create` with `alpha_3_country_code: "IND"`.
2. **Complete beneficiary KYC.** Submit the customer's PAN via `/kyc/remittance-beneficiary-kyc`.
3. **Add the bank account.** Add the beneficiary's bank account via `/bank/create`.
4. **Create the remitter.** Register the sending party via `/kyc/remitter/create`.
5. **Create a quotation.** Generate a quote via `/remittance-payout/quotation`, keyed off the amount the beneficiary should receive.
6. **Fund the payout.** On the prefunding flow, check that your prefunded balance covers the quotation's `sending_amount` via `/payout/balance`. On the non-prefunding flow, send the `sending_amount` in crypto to the wallet address from the quotation response and save the transaction hash.
7. **Initiate the remittance payout.** Create the order via `/remittance-payout/initiate`, linking the quotation and remitter. Pass the `transaction_hash` only on the non-prefunding flow.
8. **Monitor transaction status.** Track progress via webhooks or polling.

## Funding Models

How you fund payouts changes what you do before and during initiation.

On the prefunding flow (recommended), you top up a DollarPe wallet address with USDT or USDC in advance, and every payout debits that balance. You don't transfer crypto per payout, and you don't pass any funding reference when initiating. Before each payout, check the balance via `/payout/balance`.

On the non-prefunding flow, you fund each payout individually: send the quotation's `sending_amount` to the wallet address returned in the quotation response, then pass that transfer's on-chain `transaction_hash` when initiating.

<Tip>
  Prefunding removes the per-payout deposit step entirely: top up the balance once,
  then fire payouts against it. Contact your DollarPe account manager to set up a
  prefunding wallet address.
</Tip>

## Visual Integration Flow

```mermaid theme={null}
%%{init: {'themeVariables': { 'fontSize': '18px', 'nodeWidth': '300', 'nodeHeight': '60' }}}%%
flowchart TD
    Start([Start Process]) --> CreateCustomer["Create Beneficiary Customer\n/customer/create (IND)"]
    CreateCustomer --> BeneficiaryKYC["Remittance Beneficiary KYC\n/kyc/remittance-beneficiary-kyc"]
    BeneficiaryKYC --> AddBank["Add Bank Account\n/bank/create"]
    AddBank --> CreateRemitter["Create Remitter\n/kyc/remitter/create"]

    CreateRemitter --> FetchRate["Fetch Exchange Rate (optional)"]
    FetchRate -->|API Call| RateAPI[/"API: /payout/fetch-rate"/]
    RateAPI --> CreateQuote["Remittance Quotation (receiving_amount)"]

    CreateQuote -->|API Call| QuoteAPI[/"API: /remittance-payout/quotation"/]
    QuoteAPI --> FundingModel{"Funding model?"}

    FundingModel -->|Prefunding| CheckBalance["Check Prefunded Balance"]
    CheckBalance -->|API Call| BalanceAPI[/"API: /payout/balance"/]
    BalanceAPI --> InitiateRemit["Create Remittance Payout\n(no transaction_hash)"]

    FundingModel -->|Non-prefunding| SendCrypto["Send sending_amount to the wallet\naddress from the quotation response"]
    SendCrypto --> InitiateRemitHash["Create Remittance Payout\n(with transaction_hash)"]

    InitiateRemit -->|API Call| RemitAPI[/"API: /remittance-payout/initiate"/]
    InitiateRemitHash -->|API Call| RemitAPI
    RemitAPI --> WebhookNotification["Webhook Notification"]
    RemitAPI --> PollStatus["Order Polling\n/payout/{payout_id} or /payout/history"]

    WebhookNotification --> PayoutStatus{"Check Payout Status"}
    PollStatus --> PayoutStatus

    PayoutStatus -->|SUCCESS| PayoutDone["Payout Done"]
    PayoutStatus -->|FAILED| HandleFail["Handle Failure"]
    PayoutStatus -->|PROCESSING| WaitRetry["Recheck Later"]

    HandleFail --> ContactSupport[Contact Support]
    PayoutDone --> End([End Process])

    classDef startEndNode fill:#dcedc8,stroke:#558b2f,stroke-width:2px,color:#000
    classDef mainNode fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000
    classDef apiNode fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px,color:#000
    classDef stateNode fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#000
    classDef failureNode fill:#ffebee,stroke:#c62828,stroke-width:2px,color:#000
    classDef waitNode fill:#fff8e1,stroke:#ff8f00,stroke-width:2px,color:#000

    class Start,End startEndNode
    class CreateCustomer,BeneficiaryKYC,AddBank,CreateRemitter,FetchRate,CreateQuote,CheckBalance,SendCrypto,InitiateRemit,InitiateRemitHash,HandleFail,ContactSupport,WaitRetry mainNode
    class RateAPI,QuoteAPI,BalanceAPI,RemitAPI apiNode
    class WebhookNotification,PollStatus waitNode
    class PayoutDone stateNode
    class PayoutStatus,FundingModel decision
```

## Step-by-Step Integration Guide

### Step 1: Create the Beneficiary Customer

Register the receiving party as a DollarPe Customer. For remittance payouts to India, `alpha_3_country_code` must be `IND`.

<Tabs>
  <Tab title="API Request">
    ```javascript theme={null}
    POST /customer/create
    {
      "full_name": "John Doe",
      "email": "john@example.com",
      "phone": "9911002211",
      "alpha_3_country_code": "IND",
      "client_reference_id": "test123"
    }
    ```
  </Tab>

  <Tab title="Fetch Later">
    ```javascript theme={null}
    // Retrieve the created customer at any time:
    GET /customer/{customer_id}      // single customer
    GET /customer/list               // all customers
    ```
  </Tab>
</Tabs>

Save the returned `customer_id`; every later step references it. You can retrieve the customer again via [Fetch Customer](/api-reference-exchange/endpoint/customer/\{customer_id}) or [List Customers](/api-reference-exchange/endpoint/customer/list).

### Step 2: Complete Remittance Beneficiary KYC

Submit the beneficiary's tax number (PAN) once, after creating the customer. This PAN-only KYC replaces the full document KYC flow for remittance beneficiaries.

<Tabs>
  <Tab title="API Request">
    ```javascript theme={null}
    POST /kyc/remittance-beneficiary-kyc
    {
      "customer_id": "638d9a52-9427-460e-99ba-948d46ce349c",
      "tax_number": "HCDPS3890E"
    }
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "status": true,
      "message": "Success",
      "data": {
        "id": "ea6899a3-abb9-4418-8878-e23f5021e38f",
        "customer_id": "638d9a52-9427-460e-99ba-948d46ce349c"
      }
    }
    ```
  </Tab>
</Tabs>

See the [Remittance Beneficiary KYC reference](/api-reference-exchange/endpoint/kyc/remittance-beneficiary-kyc) for full field and error details.

### Step 3: Add the Beneficiary's Bank Account

Add the bank account the payout will land in. Save the returned `bank_id` for the quotation.

```javascript theme={null}
POST /bank/create
{
  "customer_id": "638d9a52-9427-460e-99ba-948d46ce349c",
  "account_number": "7627389201",
  "ifsc": "SBI0001829IU",
  "account_name": "John Doe"
}
```

See the [Add Bank Account reference](/api-reference-exchange/endpoint/bank/create) for full field and error details.

### Step 4: Create the Remitter

Register the sending party once, before requesting a remittance quotation. This call is idempotent: resubmitting the same `id_type` + `id_number` for your organization returns the existing remitter instead of creating a duplicate.

<Tabs>
  <Tab title="API Request">
    ```javascript theme={null}
    POST /kyc/remitter/create
    {
      "first_name": "Siva",
      "last_name": "Raj",
      "nationality": "IND",
      "city": "Sydney",
      "source_of_funds": "gifts",
      "id_type": "PAN_CARD",
      "id_number": "AZL4546"
    }
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "status": true,
      "message": "Remitter created",
      "data": {
        "id": "e14fa86f-2a5e-437a-a031-949c68ade933",
        "type": "PERSONAL",
        "status": "ACTIVE",
        "client_reference_id": "remitter-ref-001",
        "details": {}
      }
    }
    ```
  </Tab>
</Tabs>

**Key Fields:**

* `id_type`: one of `PASSPORT`, `DRIVING_LICENCE`, `BENEFICIARY_ID`, `PAN_CARD`, `AADHAAR_CARD`, `AIRLINE_STAFF_CARD`, `BUSINESS_REGISTRATION_NO_BR`, `CENTRAL_BANK_LICENCE`, `ACRA`
* `source_of_funds`: fixed enum (`salary`, `savings`, `gifts`, `business_income`, and others)
* `id`: pass this value as `remitter_id` in the quotation (Step 5) and payout (Step 7)

See the [Create Remitter reference](/api-reference-exchange/endpoint/kyc/remitter/create) for full field and error details.

### Step 5: Create a Remittance Quotation

You can check the live rate first via [`GET /payout/fetch-rate`](/api-reference-exchange/endpoint/payout/config/fetch-rate), though this is optional.

A standard payout quotation is keyed on `sending_amount`, the crypto amount the customer sends. A remittance quotation is keyed on `receiving_amount` instead: the fiat amount the beneficiary should receive. It links the `customer_id` (Step 1), `bank_id` (Step 3), and `remitter_id` (Step 4):

<Tabs>
  <Tab title="API Request">
    ```javascript theme={null}
    POST /remittance-payout/quotation
    {
      "asset": "USDT",
      "fiat": "INR",
      "receiving_amount": "5100",
      "bank_id": "cab47575-bbcb-4294-81a3-30774104f3b6",
      "customer_id": "84737c7d-7b62-4204-80d6-80f6ecb3ceb4",
      "remitter_id": "e14fa86f-2a5e-437a-a031-949c68ade933",
      "risk_parameters": {}
    }
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "status": true,
      "message": "Success",
      "data": {
        "id": "59bf60c3-e9af-40a7-9d5c-2a1aa191e769",
        "customer_id": "84737c7d-7b62-4204-80d6-80f6ecb3ceb4",
        "bank_id": "cab47575-bbcb-4294-81a3-30774104f3b6",
        "remitter_id": "e14fa86f-2a5e-437a-a031-949c68ade933",
        "asset": "USDT",
        "fiat": "INR",
        "sending_amount": 55.89,
        "rate": 92.34,
        "receiving_amount": 5100.0,
        "fees": {
          "client_fee_fiat": 25.8,
          "client_fee_crypto": 0.27,
          "client_gst_fiat": 4.64,
          "client_gst_crypto": 0.05,
          "dollarpe_fee": 25.8,
          "dollarpe_gst": 4.64,
          "pg_fee": 0.0,
          "pg_gst": 0.0,
          "gross_effective_exchange_rate": 91.25,
          "tds": 0.0
        },
        "created_at": "2026-07-02T11:41:26.836955Z",
        "expiry_time": "2026-07-02T12:11:26.000Z"
      }
    }
    ```
  </Tab>
</Tabs>

The response's `sending_amount` is the crypto amount needed to fund the payout; the next step depends on it. See the [Remittance Quotation reference](/api-reference-exchange/endpoint/remittance-payout/quotation) for full field and error details.

### Step 6: Fund the Payout

What you do here depends on your [funding model](#funding-models).

**Prefunding flow.** Check that the prefunded wallet covers the quotation's `sending_amount` before you initiate. The balance is returned per asset and cached briefly, so a top-up you just made can take a short while to show up.

<Tabs>
  <Tab title="API Request">
    ```javascript theme={null}
    GET /payout/balance
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "status": true,
      "message": "Success",
      "data": {
        "available_balance": {
          "USDT": "15000.5"
        }
      }
    }
    ```
  </Tab>
</Tabs>

If the available balance for the quotation's asset is lower than `sending_amount`, top up the wallet before initiating; otherwise the payout will fail. See the [Fetch Balance reference](/api-reference-exchange/endpoint/remittance-payout/balance) for full details. You don't send any crypto per payout and won't need a transaction hash in the next step.

**Non-prefunding flow.** Send the quotation's `sending_amount` in crypto to the wallet address returned in the quotation response. Save the on-chain `transaction_hash` of that transfer; you pass it when initiating the payout in the next step.

### Step 7: Initiate the Remittance Payout

<Tabs>
  <Tab title="Prefunding Flow">
    ```javascript theme={null}
    POST /remittance-payout/initiate
    {
      "quotation_id": "59bf60c3-e9af-40a7-9d5c-2a1aa191e769",
      "customer_id": "84737c7d-7b62-4204-80d6-80f6ecb3ceb4",
      "remitter_id": "e14fa86f-2a5e-437a-a031-949c68ade933",
      "client_reference_id": "testUser123"
    }
    ```
  </Tab>

  <Tab title="Non-Prefunding Flow">
    ```javascript theme={null}
    POST /remittance-payout/initiate
    {
      "quotation_id": "59bf60c3-e9af-40a7-9d5c-2a1aa191e769",
      "customer_id": "84737c7d-7b62-4204-80d6-80f6ecb3ceb4",
      "remitter_id": "e14fa86f-2a5e-437a-a031-949c68ade933",
      "client_reference_id": "testUser123",
      "transaction_hash": "0x9b7bb827c2e5e3c1a0f2d3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4"
    }
    ```
  </Tab>
</Tabs>

<Note>
  Include `transaction_hash` only on the non-prefunding flow: it is the hash of the crypto transfer you made in Step 6. On the prefunding flow, send no funding reference; the payout debits your prefunded USDT/USDC balance. `client_reference_id` is optional in both cases.
</Note>

See the [Create Remittance Payout reference](/api-reference-exchange/endpoint/remittance-payout/initiate) for the full response shape and error codes.

### Step 8: Monitor Transaction Status

Track the payout by polling [`GET /payout/{payout_id}`](/api-reference-exchange/endpoint/payout/order/\{payout_id}) (single order) or [`GET /payout/history`](/api-reference-exchange/endpoint/payout/order/history) (all orders), or subscribe to [webhooks](/api-reference-exchange/endpoint/organizations/api-webhooks) for status change notifications.

## Getting Help

If you have questions about the remittance payout flow:

* Check our [API documentation](/api-reference-exchange/overview/introduction) for detailed endpoint information
* Contact our [support team](mailto:support@dollarpe.xyz)