Transfer Money

You can create payouts to transfer funds using one of the following methods:

• Pre-created beneficiary
• Inline beneficiary details
• Batch upload
• Batch API

Select the method based on payout frequency, operational workflow, and automation requirements.

Payout methods

Pre-created beneficiary

Create a beneficiary once and reuse it across multiple payouts. We recommend pre-creating a beneficiary when you need to create recurring payouts.

This reduces payload size, avoids repeated validation, and improves operational consistency.

Step 1: Create a beneficiary

Use the Create Beneficiary request.

This returns a beneficiaryHashId that uniquely identifies the beneficiary.

Store the beneficiaryHashId for future use.

Step 2: Create a payout referencing the beneficiary

Use the Create Payout (Remittance) request.

Include the stored beneficiaryHashId in the request body:

{
  "beneficiary": {
    "id": "6081219f04fa070017d12e68"
  },
  "payout": {
    "destinationAmount": 10
  },
  "purposeCode": "IR005"
}

Use this method for payroll, vendor payments, marketplace disbursements, and other recurring payouts.

Inline beneficiary

Include beneficiary details directly in the payout request without pre-creating a beneficiary. We recommend creating beneficiaries inline when you need to create one-time payouts.

No beneficiary record is stored.

Use the Create Payout (Remittance) request and include all beneficiary details inline:

{
  "beneficiary": {
    "beneficiary": {
      "name": "John Doe",
      "accountType": "CORPORATE"
    },
    "paymentAccount": {
      "accountNumber": "1234567",
      "payoutMethod": "LOCAL",
      "payoutCurrency": "INR",
      "routingCode": [
        {
          "type": "IFSC CODE",
          "value": "ICIC0001451"
        }
      ]
    }
  },
  "payout": {
    "destinationAmount": 10
  },
  "purposeCode": "IR005"
}

Use this method for ad-hoc or infrequent transfers when you do not need to reuse a beneficiary.

Batch upload

Submit multiple payouts using a CSV file through Nium Portal.

This method is suitable for finance-led workflows and spreadsheet-based processes.

• Upload a CSV file in Nium Portal
• Validate file rows
• Execute the payout batch

For more information, see Batch Payout.

Batch payout API

Submit up to 1,000 payouts in a single API request. We recommend using the Batch Payout request when you need to automate a high volume of payouts.

This method is designed for automated platforms, marketplaces, and large-scale payout orchestration.

Use the Create Batch Payout request.

Features of the Batch endpoint include:

• Per-item status tracking
• Bulk-level lifecycle tracking
• Webhook notifications
• Scheduled execution (executeAt)
• Idempotency support

Each batch can:

• Reference a pre-created beneficiary, or
• Include inline beneficiary details

Use this method when building automated disbursement systems.

Create quote

If currency conversion is required prior to payout, use the Create Quote request.

Use the returned quote details when creating the payout.

Upload documents

If compliance requires additional documentation, use the Upload Payout Document request.

Documentation requirements vary by corridor and payout type.

Payout comparison

Requirement	Recommended Method
One-time payout	Inline beneficiary
Recurring payout	Pre-created beneficiary
Manual spreadsheet workflow	Batch upload
High-volume automated payouts	Batch endpoint

Validation errors

If a payout request contains missing or invalid fields, a structured validation error response is returned.

This response helps you identify which field caused the error and how to resolve it.

Error response

Validation errors follow the a unified schema:

{
  "code": "field_missing",
  "description": "Field is missing",
  "field": "beneficiary.address",
  "action": "Input the beneficiary address",
  "regexp": "^.[A-Za-z0-9 -.]{1,255}$"
}

Response body

Field	Description
code	Machine-readable error identifier describing the validation failure.
description	Human-readable explanation of the error.
field	The request field that caused the error.
action	Recommended action to resolve the issue.
regexp	Validation pattern required for the field, when applicable.

Example response

If a payout request is submitted without a beneficiary address, the response can return:

{
  "code": "field_missing",
  "description": "Field is missing",
  "field": "beneficiary.address",
  "action": "Input the beneficiary address",
  "regexp": "^.[A-Za-z0-9 -.]{1,255}$"
}

This response indicates that the beneficiary.address field was not provided and must be included in the request.

Legacy schema

Newly onboarded customers receive validation errors using the error schema shown above.

Some existing integrations may continue to receive validation errors in a previous response format. This does not affect existing integrations.

Legacy integrations can adopt the new error schema to use the standardized error structure shown in this section.

Handling validation errors

When building payout integrations, we recommend:

• Logging the returned error response
• Mapping code values to retry or correction logic
• Displaying the description or action message in internal dashboards or operational tools
• Validating required fields before submitting payout requests when possible

Handling validation errors correctly helps reduce failed payout attempts and improves operational reliability.

Lifecycle and status tracking

After creating a payout:

• Retrieve status using the Get Transaction endpoint
• Subscribe to webhook events for real-time updates
• Handle returned or rejected transactions if applicable
• Upload additional documentation if requested

See our Payout Webhooks documentation for event schemas and status transitions.

See Track Payouts for details on how to track payouts.