Payout Integration Guide

What Are Payouts and Why They Matter

Payouts enable your application to seamlessly transfer funds to your customers’ bank accounts, using cryptocurrency as the funding source. Whether you’re a developer or a business owner, this guide will help you integrate DollarPe’s Payout system.

Prerequisites:

Ensure you have completed the authentication setup
Configure your webhook endpoint for real-time updates
Review the following guides to ensure compatibility:
- supported geographies
- supported stablecoins and blockchains
- supported fiat methods
- Verify your users have completed KYC and have at least one verified bank account

Warning: Initiate the payout before the quotation expiry time.

Integration at a Glance

The Payout integration flow for centralized exchanges involves the following key steps:

Fetch Configurations - Retrieve the basic configuration to understand supported assets, networks, and limits.
Validate user requirements – Ensure the customer has completed KYC verification and has at least one verified bank account added.
Fetch payout limits – Retrieve payout limits to check daily limits, available limits, and whether Enhanced Due Diligence (EDD) is required.
Fetch exchange rates – Retrieve the latest cryptocurrency exchange rates.
Create a quotation – Generate a quote for the desired payout amount.
Initiate the payout – Start the payout using the exchange order ID.
Link exchange transfer ID – Link the exchange transfer ID with the payout.
Monitor transaction status – Track the progress of the transaction.
Handle completion – Finalize the payout once the transaction is confirmed.

Visual Integration Flow

Process Flow Diagram

Sequence Diagram: Detailed Process Flow

Step-by-Step Integration Guide

Step 1: Fetch Configurations

Before starting the integration, fetch the basic configuration to understand supported assets, networks, and limits:

API Request
Response

GET /payout/configuration

{
"status": true,
"message": "Success",
"data": {
  "inr": {
    "supported_assets": [
      "usdt",
      "usdc"
    ],
    "coin_limits": {
      "usdt": {
        "imps": {
          "min": 28,
          "max": 5563
        },
        "upi": {
          "min": 28,
          "max": 1113
        }
      },
      "usdc": {
        "imps": {
          "min": 28,
          "max": 5563
        },
        "upi": {
          "min": 28,
          "max": 1113
        }
      }
    },
    "required_risk_parameters": [
      "ip_address",
      "device_id",
      "suspicious_activity_report",
      "law_enforcement_agency_report"
    ]
  }
}
}

Key Fields:

supported_fiats: List of supported fiat currencies
supported_assets: List of supported cryptocurrencies
supported_networks: List of supported blockchain networks
coin_limits: Minimum and maximum limits for each supported cryptocurrency

If you are storing these configurations in your application to validate user inputs and display appropriate options, make sure to update this data periodically.

Step 2: Check Customer KYC and Bank Account status

Before initiating any payout, ensure the customer is KYC-verified and has a verified bank account.

Fetch Customer Info
Fetch Bank Account Info

GET /customer/{customer_id}
Response:
{
    "status": true,
    "message": "Success",
    "data": {
        "id": "8da49e5e-33d1-48b2-b107-eb34f851b2fd",
        "client_reference_id": "client_id_1",
        "full_name": "John Doe",
        "email": "john@example.com",
        "phone": "+911234123412",
        "country": "IND",
        "type": "INDIVIDUAL",
        "status": "UNVERIFIED",
        "failure_reason": null
    }
}

GET /bank/list/{customer_id}
{
  "status": true,
  "message": "Success",
  "data": {
    "count": 1,
    "next": null,
    "previous": "<url>",
    "results": [
      {
        "id": "4e6f1b20-a73c-11ec-b909-0242ac120002",
        "customer_id": "550e8400-e29b-41d4-a716-446655440000",
        "account_number": "123456789012",
        "ifsc_code": "ABC123456",
        "vpa": "testing@upi",
        "bank_account_type": "ACCOUNT_DETAILS",
        "bank_account_status": "VERIFIED"
      }
    ]
  }
}

Step 3: Check if EDD is Required

Before proceeding with the payout, check if Enhanced Due Diligence (EDD) is required for the customer. This step also returns current daily/available payout limits.

API Request
Response

GET /edd/fetch?customer_id=520e8400-e29b-41d4-a716-446655440000

{
  "status": true,
  "message": "Success",
  "data": {
    "daily_limit": 500000,
    "available_limit": 100000,
    "payment_method_limits": {
        "per_transaction_limit": {
            "UPI": 100000,
            "IMPS": 100000
        },
        "total_available_limit": {
            "UPI": 100000,
            "IMPS": 100000
        }
    },
    "full_limit_reset_timestamp": "2024-03-13T10:00:00Z",
    "is_edd_required": false,
    "is_limit_increase_available": true
  }
}

Key Fields:

daily_limit: Maximum daily payout limit for the asset
available_limit: Remaining available payout limit for the current day
limit_reset_timestamp: Unix timestamp when the daily limit will reset
is_edd_required: Whether Enhanced Due Diligence (EDD) is required (true or false)
is_limit_increase_available: Whether the customer can apply for a higher daily limit

If is_edd_required is true, you must complete the EDD process for this customer before proceeding with the payout.

Step 4: Fetch Exchange Rate

Get the real-time exchange rate for a given crypto asset.

API Request
Response

GET /payout/fetch-rate
{
  "asset": "usdt",
  "fiat": "inr",
}

{
  "status": true,
  "message": "Success",
  "data": {
    "asset": "USDT",
    "fiat": "INR",
    "rate": 87.2
  }
}

Key Fields:

asset: Cryptocurrency to be used (e.g., “USDT”, “USDC”)
amount: Amount in cryptocurrency
rate: Current exchange rate (amount of fiat per 1 unit of crypto)

Rates fluctuate constantly based on market conditions. We recommend fetching a new rate before each transaction to ensure accuracy.

Step 5: Create a Quotation

After getting the current rate, create a quotation to lock in the rate.

API Request
Response

POST /payout/quotation
{
  "asset": "usdt",
  "fiat": "inr",
  "sending_amount": "51",
  "customer_id": "def8b740-99f9-4cba-bc9e-99de57e927b4",
  "bank_id": "4e6f1b20-a73c-11ec-b909-0242ac120002",
  "risk_parameters": {
    "ip_address": "127.0.0.1",
    "device_id": "<string>",
    "suspicious_activity_report": false,
    "law_enforcement_agency_report": false
  }
}

{
    "status": true,
    "message": "Success",
    "data": {
        "id": "c9f343b5-ff56-4d52-93af-0962f75242b7",
        "customer_id": "8da49e5e-33d1-48b2-b107-eb34f851b2fd",
        "bank_id": "c863b696-7fbd-4b16-b3a7-134aefffb2fe",
        "asset": "USDT",
        "fiat": "INR",
        "sending_amount": 10,
        "rate": 87.2,
        "receiving_amount": 858.96,
        "fees": {
            "client_fee_fiat": "",
            "client_fee_crypto": "",
            "dollarpe_fee": "",
            "pg_fee": "",
            "client_gst_fiat": "",
            "client_gst_crypto": "",
            "dollarpe_gst": "",
            "pg_gst": "",
            "tds": "",
            "gross_exchange_rate": ""
        },
        "created_at": "2025-03-21T13:29:07.828029Z",
        "expiry_time": "2025-03-21T13:39:07.828029Z"
    }
}

Key Fields:

asset: Cryptocurrency to be used
fiat: Fiat currency to receive (e.g., “INR” for Indian Rupee)
sending_amount: Amount in cryptocurrency
customer_id: ID of the KYC-verified customer
expiry_time: Time until the quotation expires

You must complete your transaction before this time expires.

Step 6: Initiate the Payout

Create a payout request with the exchange order ID:

API Request
Response

POST /payout/initiate
{
  "quotation_id": "2e104290-07c8-49f1-a5ca-0d27f0078f8a",
  "customer_id": "def8b740-99f9-4cba-bc9e-99de57e927b4",
  "client_reference_id": "testUser123",
  "exchange_order_id": "898990982672892"
}

{
  "status": true,
  "message": "Success",
  "data": {
      "id": "ac7c5360-0b57-4fb7-88f2-df1c371930ee",
      "quotation_id": "c9f343b5-ff56-4d52-93af-0962f75242b7",
      "customer_id": "8da49e5e-33d1-48b2-b107-eb34f851b2fd",
      "client_reference_id": "payout_first_test",
      "bank_id": "c863b696-7fbd-4b16-b3a7-134aefffb2fe",
      "asset": "USDT",
      "fiat": "INR",
      "rate": 87.2,
      "sending_amount": 10,
      "receiving_amount": 858.96,
      "fees": {
          "client_fee_fiat": "",
          "client_fee_crypto": "",
          "dollarpe_fee": "",
          "pg_fee": "",
          "client_gst_fiat": "",
          "client_gst_crypto": "",
          "dollarpe_gst": "",
          "pg_gst": "",
          "tds": "",
          "gross_exchange_rate": ""
      },
      "exchange_order_id": "898990982672892",
      "created_at": "2025-03-21T13:37:53.208137Z",
      "status": "PROCESSING"
  }
}

Key Fields:

quotation_id: ID received from Step 3
customer_id: ID of the KYC-verified customer
client_reference_id: Your internal reference ID for tracking (optional)
bank_id: ID of the verified bank account
exchange_order_id: ID of the order placed at the centralized exchange
status: Current status of the payout

Most payouts are processed within 30-60 minutes, but can take up to 24 hours during high volume periods or in case of bank processing delays.

Step 7: Monitor Transaction Status

After linking the exchange transfer ID, you need to track the payout status. There are two ways to monitor this status:

Option A: Webhook Integration (Recommended)

Webhooks provide real-time updates about payout status changes. Configure your webhook endpoint to receive these notifications:

// Sample webhook payload for payout status updates
{
  "type": "PAYOUT",
  "id": "ac7c5360-0b57-4fb7-88f2-df1c371930ee",
  "event": "COMPLETED", // or "FAILED", "PROCESSING"
  "failure_reason": null, // Contains failure reason if status is "FAILED"
  "timestamp": "2025-03-21T13:37:53.208137Z",
  "data": {
    "utr": "123456789012", // Bank reference number (only for COMPLETED status)
    "fiat": "INR",
    "exchange_order_id": "order_123456789"
  }
}

If using webhooks, ensure your server acknowledges receipt with a 200 OK response to prevent duplicate notifications.

Option B: Status Polling

If webhooks aren’t feasible, you can periodically check the status using the payout endpoint:

API Request
Response

GET /payout/{payout_id}

  {
  "status": true,
  "message": "Success",
  "data": {
    "id": "ac7c5360-0b57-4fb7-88f2-df1c371930ee",
    "quotation_id": "c9f343b5-ff56-4d52-93af-0962f75242b7",
    "customer_id": "8da49e5e-33d1-48b2-b107-eb34f851b2fd",
    "client_reference_id": "payout_first_test",
    "bank_id": "c863b696-7fbd-4b16-b3a7-134aefffb2fe",
    "asset": "USDT",
    "fiat": "INR",
    "sending_amount": "10.00000000",
    "rate": "87.20000000",
    "receiving_amount": "858.96000000",
    "fees": {
      "client_fee": "",
      "dollarpe_fee": "",
      "pg_fee": "",
      "client_gst": "",
      "dollarpe_gst": "",
      "pg_gst": "",
      "tds": "",
      "gross_exchange_rate": ""
    },
    "exchange_order_id": "",
    "exchange_transfer_id": "",
    "status": "PROCESSING",
    "utr": null,
    "failure_reason": "",
    "created_at": "2025-03-21T13:37:53.208137Z",
    "updated_at": "2025-03-21T13:37:53.208142Z"
  }
}

If using the polling approach, we recommend checking no more frequently than once every 60 seconds to avoid API rate limits.

Possible Status Values:

PROCESSING: Initial state, waiting for crypto confirmation
SUCCESS: Payout has been successfully completed and UTR is generated
FAILED: Payout has failed and failure_reason is updated

Step 8: Handle Transaction Completion

Successful Transactions

When a payout is completed successfully:

Update your internal records with the transaction details
Notify your user that the funds have been sent to their bank account
Provide the bank reference number for their records (if available)
Store the transaction details for future reference and customer support

If your transaction fails due to sending funds to the wrong address or network, recovery may not be possible. Always double-check these details before sending.

Step 9: Link Exchange Order ID with Exchange Transfer ID

After the payout is successful, you must link the exchange transfer ID related to the crypto sent with the exchange order ID:

API Request
Response

PATCH /payout/update-transfer-id
{
  "exchange_order_id": "92823910232129090",
  "exchange_transfer_id": "9282391023212"
}

{
  "status": true,
  "message": "Success",
  "data": {
    "exchange_order_id": "92823910232129090",
    "exchange_transfer_id": "9282391023212"
  }
}

Key Fields:

exchange_order_id: The order ID from your centralized exchange
exchange_transfer_id: The transfer ID associated with the crypto transaction

Testing Your Integration

Sandbox Environment

Before going live, test your integration thoroughly in our sandbox environment:

Use the base URL: https://sandbox-api.dollarpe.xyz
Follow the same steps as production
Test both successful and failed transaction scenarios

In the sandbox environment, you can simulate different failure scenarios by using specific test values. Refer to our Sandbox Testing Guide for details.

Getting Help

If you encounter any issues with your payout integration:

Check our API documentation for detailed endpoint information
Visit the Troubleshooting Guide for common solutions
Contact our support team with your customer_id and transaction logs

Our support team is available 24/7 to help with integration issues. For urgent matters, use the in-app chat or call our technical support hotline.

Documentation Index

​What Are Payouts and Why They Matter

​Integration at a Glance

​Visual Integration Flow

​Process Flow Diagram

​Sequence Diagram: Detailed Process Flow

​Step-by-Step Integration Guide

​Step 1: Fetch Configurations

​Step 2: Check Customer KYC and Bank Account status

​Step 3: Check if EDD is Required

​Step 4: Fetch Exchange Rate

​Step 5: Create a Quotation

​Step 6: Initiate the Payout

​Step 7: Monitor Transaction Status

​Option A: Webhook Integration (Recommended)

​Option B: Status Polling

​Step 8: Handle Transaction Completion

​Successful Transactions

​Step 9: Link Exchange Order ID with Exchange Transfer ID

​Testing Your Integration

​Sandbox Environment

​Getting Help

What Are Payouts and Why They Matter

Integration at a Glance

Visual Integration Flow

Process Flow Diagram

Sequence Diagram: Detailed Process Flow

Step-by-Step Integration Guide

Step 1: Fetch Configurations

Step 2: Check Customer KYC and Bank Account status

Step 3: Check if EDD is Required

Step 4: Fetch Exchange Rate

Step 5: Create a Quotation

Step 6: Initiate the Payout

Step 7: Monitor Transaction Status

Option A: Webhook Integration (Recommended)

Option B: Status Polling

Step 8: Handle Transaction Completion

Successful Transactions

Step 9: Link Exchange Order ID with Exchange Transfer ID

Testing Your Integration

Sandbox Environment

Getting Help