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

# Create a Payout to a Mobile Number Using Composite API

> Create a Payout to Mobile Number using the Composite API.

Available in
🇮🇳 India
🇲🇾 Malaysia
🇺🇸 United States

Use this endpoint to create a payout to a mobile number using Composite Payout API.

> [!WARNING]
>
> **Watch Out!**
>
> * Ensure you allowlist IPs and pass the idempotency key to make a successful payout.
> * You can send payouts to VPA (UPI) linked mobile numbers only.

\
&#x20;Consider the points given below before firing this API:

* Contact
  * A new contact is created if any combination of the following details is unique:
    * `fund_account.contact.name`
    * `fund_account.contact.email`
    * `fund_account.contact.contact`
    * `fund_account.contact.type`
    * `fund_account.contact.reference_id`
  * If **all** the above details match the details of an existing contact, the API returns details of the existing contact.
  * Use the [Update Contact API](https://razorpay.com/docs/my/api/x/contacts/update.md) if you want to make changes to an existing contact.
* Fund Account
  * A new fund account is created if any combination of the following details is unique:
    * `fund_account.card.name`
    * `fund_account.card.number`
    * `fund_account.contact.name`
    * `fund_account.contact.email`
    * `fund_account.contact.contact`
    * `fund_account.contact.type`
    * `fund_account.contact.reference_id`
  * If **all** the above details match the details of an existing fund account, the API returns details of the existing fund account.
  * You cannot edit the details of a fund account.

To understand the status of the payouts, refer to Payout Status Details.

```bash Curl theme={null}
curl -u <YOUR_KEY>:<YOUR_SECRET> 
-X POST https://api.razorpay.com/v1/payouts 
-H "Content-Type: application/json" 
-H "X-Payout-Idempotency: 53cda91c-8f81-4e77-bbb9-7388f4ac6bf4" 
-d '{
  "account_number": "7878780080316316",
  "amount": 1000,
  "currency": "INR",
  "mode": "UPI",
  "purpose": "cashback",
  "fund_account": {
    "account_type": "mobile",
    "mobile": {
      "number": "9876543210",
      "account_holder_name": "Gaurav Kumar"
    },
    "contact": {
      "name": "Gaurav Kumar",
      "email": "gaurav.kumar@example.com",
      "contact": "9000090000",
      "type": "self",
      "reference_id": "Acme Contact ID 12345",
      "notes": {
        "notes_key_1": "Tea, Earl Grey, Hot",
        "notes_key_2": "Tea, Earl Grey… decaf."
      }
    }
  },
  "queue_if_low_balance": true,
  "reference_id": "Acme Transaction ID 12345",
  "narration": "Acme Corp Fund Transfer",
  "notes": {
    "notes_key_1": "Beam me up Scotty",
    "notes_key_2": "Engage"
  }
}'
```

```json Success theme={null}
  {
  "id": "pout_F681qslJ3ba70q",
  "entity": "payout",
  "fund_account_id": "fa_F681qr6Bqy1Je7",
  "fund_account": {
    "id": "fa_F681qr6Bqy1Je7",
    "entity": "fund_account",
    "contact_id": "cont_F681qmU11CfPDl",
    "contact": {
      "id": "cont_F681qmU11CfPDl",
      "entity": "contact",
      "name": "Gaurav Kumar",
      "contact": "9000090000",
      "email": "gaurav.kumar@example.com",
      "type": "employee",
      "reference_id": "Acme Contact ID 12345",
      "batch_id": null,
      "active": true,
      "notes": {
        "notes_key_1": "Tea, Earl Grey, Hot",
        "notes_key_2": "Tea, Earl Grey… decaf."
      },
      "created_at": 1592929016
    },
    "account_type": "mobile", 
    "mobile": {
      "number": "9876543210",
      "account_holder_name": "Gaurav Kumar"
    },
    "vpa": {
      "username": null,
      "handle": "exampleupi",
      "address": null,
    },
    "batch_id": null,
    "active": true,
    "created_at": 1592929016
  },
  "amount": 1000,
  "currency": "INR",
  "notes": {
    "notes_key_1": "Beam me up Scotty",
    "notes_key_2": "Engage",
    "VPA_HANDLE": "okhdfcbank"
  },
  "fees": 59,
  "tax": 9,
  "status": "processed",
  "purpose": "refund",
  "utr": "UPI2928292020",
  "mode": "UPI",
  "reference_id": "Acme Transaction ID 12345",
  "narration": "Acme Corp Fund Transfer",
  "batch_id": null,
  "failure_reason": null,
  "created_at": 1592929017,
  "fee_type": null,
  "status_details": {
        "reason": "pending_approval",
        "description": "Workflow for the payout is pending approval from the approver(s)",
        "source": "business"
    },
  "merchant_id": "Pup4LDLiA1DssX",
  "status_details_id": "R7aA38hQzg5TDj",
  "error": {
    "description": null,
    "source": null,
    "reason": null,
    "code": "NA",
    "step": "NA",
    "metadata": {}
  }
}
```

```json Failure theme={null}
{
  "error": {
    "code": "BAD_REQUEST_ERROR",
    "description": "No linked account details found",
    "source": "customer",
    "step": "fetch_account_details",
    "reason": "no_linked_account_found",
    "metadata": {},
    "field": "number"
  }
}
```

## Request Parameters

**account\_number** `string` *required*

The account from which you want to make the payout.\
Account details can be found on the RazorpayX Dashboard. For example, `7878780080316316`.

* Pass your customer identifier if you want money to be deducted from RazorpayX Lite.
* Pass your Current Account number if you want money to be deducted from your Current Account.

> [!WARNING]
>
> **Watch Out!**
>
> * This is **not** your contact's bank account number. Log in to your **RazorpayX Dashboard** and go to **My Account & Settings → Banking → Customer Identifier.**
> * This value is different for Test Mode and Live Mode.
> * RazorpayX Lite is currently not available for new merchants. To set up a new RazorpayX account, refer to Current Account.

**amount** `integer` *required*

The payout amount, in paise. For example, pass `1000000` to transfer an amount of ₹10,000. Minimum value is `100`. \
&#x20;The value passed here does not include fees and tax. Fees and tax, if any, are deducted from your account balance.

**currency** `string` *required*

The payout currency. Here, it is `INR`.

**mode** `string` *required*

The mode to be used to create the payout. Here, it is `UPI`.\\

The payout modes are case-sensitive. When creating payouts using APIs, ensure payout modes are entered in upper case. \\

**purpose** `string` *required*

The purpose of the payout. Classifications available in the system by default:

* `refund`
* `cashback`
* `payout`
* `salary`
* `utility bill`
* `vendor bill` \\

Additional purposes for payouts can be created via the Dashboard and then used in the API. However, it is not possible to create a new purpose for the payout via the API.

**fund\_account** `object` *required*

Details of the contact and fund account to which the payout should be made.

**account\_type** `string` *required*

The type of account linked to the contact ID. Here, the value has to be `mobile`.

**mobile** `object` *required*

Object for capturing phone number and the name linked to it (optional).

**number** `string` *required*

The contact's 10-digit mobile number (without country code) to which you wish to send the payout. This has to be linked to a VPA (UPI). For example, `9876543210`.

**account\_holder\_name** `string`

The name linked to the mobile number. This, if provided, will be validated against the linked UPI/bank account name.  This will not be validated if not entered. For example, `Gaurav Kumar`.

**contact** `object` *required*

Details of the contact to whom the payout should be made.

**name** `string` *required*

Contact's name. Minimum 3 characters. Maximum 50 characters. This field is case-sensitive. Supported characters: `a-z`, `A-Z`, `0-9`, `space`, `’` , `-` , `_` , `/` , `(` , `)` and , `.`. For example, `Gaurav Kumar`.

**email** `string`

The contact's email address. For example, `gaurav.kumar@example.com`.

**contact** `string`

The contact's phone number. For example, `9000090000`. This can be same or different from the number passed to the `mobile` object for payout.

**type** `string`

Classification for the contact. For example, `employee`. Classifications are available by default:

* `vendor`
* `customer`
* `employee`
* `self` \\

Additional classifications can be created via the Dashboard and then used in APIs. It is not possible to create new classifications via the API.

**reference\_id** `string`

Maximum length is 40 characters. A reference you enter for the contact. For example, `Acme Contact ID 12345`.

**notes** `object`

Notes you can enter for the contact for future reference. This is a key-value pair. For example, `"note_key": "Beam me up Scotty"`.

**queue\_if\_low\_balance** `boolean`

Possible values:

* `true`: The payout is queued when your business account does not have sufficient balance to process the payout.
* `false` (default): The payout is never queued. The payout fails if your business account does not have sufficient balance to process the payout.

**reference\_id** `string`

Maximum length is 40 characters. A reference you enter for the payout. For example, `Acme Transaction ID 12345`. You can use this field to store your own transaction ID, if any.

**narration** `string`

Maximum length 30 characters. Allowed characters: `a-z`, `A-Z`, `0-9` and `space`. This is a custom note that also appears on the bank statement. If no value is passed for this parameter, it defaults to the Merchant Billing Label. \
&#x20;Enter the important text in the first 9 characters as banks truncate the rest as per their standards.

**notes** `array`

Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, `"note_key": "Beam me up Scotty”`.

## Response Parameters

**id** `string`

The unique identifier linked to the payout. For example, `pout_00000000000001`.

**entity** `string`

The entity being created. Here, it will be `payout`.

**fund\_account\_id** `string`

The unique identifier linked to the fund account. For example, `fa_00000000000001`.

**fund\_account** `string`

Contact and fund account details to which the payout was made.

**id** `string`

The unique identifier linked to the fund account. For example, `fa_00000000000001`.

**entity** `string`

Here it will be `fund_account`.

**contact\_id** `string`

The unique identifier linked to the contact. For example, `cont_00000000000001`.

**contact** `string`

Details of the contact to whom the payout is being made.

**id** `string`

The unique identifier linked to the contact. For example, `cont_00000000000001`.

**entity** `string`

The entity being created. Here, it will be `contact`.

**name** `string`

The contact's name. For example, `Gaurav Kumar`.

**contact** `string`

The contact's phone number. For example, `9000090000`.

**email** `string`

The contact's email address. For example, `gaurav.kumar@example.com`.

**type** `string`

Classification for the contact being created. For example, `employee`. Classifications are available by default:

* `vendor`
* `customer`
* `employee`
* `self`

Additional Classifications can be created via the Dashboard and then used in APIs. It is not possible to create new Classifications via API.

**reference\_id** `string`

A reference you entered for the contact. For example, `Acme Contact ID 12345`.

**batch\_id** `string`

This parameter is populated if the contact was created as part of a bulk upload. For example, `batch_00000000000001`.

**active** `boolean`

Possible values:

* `true`: active
* `false`: inactive

**notes** `object`

User-entered notes for internal reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example, `"note_key": "Beam me up Scotty”`.

**created\_at** `integer`

Timestamp, in Unix, when the contact was created. For example, `1545320320`.

**account\_type** `string`

The type of fund account being created. Here, it will be `mobile`.

**mobile** `object`

The contact's mobile number to which you wish to make a payout.

**number** `string` *required*

Account holder's mobile number containing 10 digits.

**account\_holder\_name** `string`

The name linked to the mobile number.

**vpa** `string`

The contact's VPA (UPI) details.

**username** `string`

The user name from the VPA (UPI). For example, `gauravkumar`.

**handle** `string`

The handle from the VPA (UPI) address. For example, `exampleupi`.

**address** `string`

The VPA (UPI) address. For example, `gauravkumar@exampleupi`.

**batch\_id** `string`

This parameter is populated if the contact was created as part of a bulk upload. For example, `batch_00000000000001`.

**active** `boolean`

Possible values:

* `true`: active
* `false`: inactive

**created\_at** `integer`

Timestamp, in Unix, when the contact was created. For example, `1545320320`.

**amount** `integer`

The payout amount, in paise. For example, if the amount transferred is ₹100, it will display  10000.  \
This value  does not include fees and tax. Fees and tax, if any, are deducted from your account balance.

**currency** `string`

The payout currency. Here, it is `INR`.

**notes** `object`

Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, `"note_key": "Beam me up Scotty”`.

**fees** `integer`

The fees for the payout. This field is populated only when the payout moves to the `processing` state. For example, `59`

**tax** `integer`

The tax that is applicable for the fee being charged. This field is populated only when the payout moves to the `processing` state. For example, `9`

**status** `string`

The payout status. Possible payout states:

* `queued`
* `pending` (if you have Approval Workflow enabled)
* `rejected` (if you have Approval Workflow enabled)
* `processing`
* `processed`
* `cancelled`
* `reversed`

**purpose** `string`

The purpose of the payout. Classifications available by default:

* `refund`
* `cashback`
* `payout`
* `salary`
* `utility bill`
* `vendor bill`

**utr** `string`

The unique transaction number linked to a payout. For example, `UPI2928292020`.

**mode** `string`

Here, it is `UPI`.

**reference\_id** `string`

A user-generated reference given to the payout. For example, `Acme Transaction ID 12345`. You can use this field to store your own transaction ID, if any.

**narration** `string`

This is a custom note that also appears on the bank statement.\
\
If no value is passed for this parameter, it defaults to the Merchant Billing Label.

**batch\_id** `string`

This parameter is populated if the contact was created as part of a bulk upload. For example, `batch_00000000000001`

**failure\_reason** `string`

The reason why the payout has failed (only in case of a failure, else it will return a null value).

**merchant\_id** `string`

This parameter returns the merchant id. For example, `Pup4LDLiA1DssX`

**status\_details\_id** `string`

This parameter returns the status id of the payout. For example, `R7aA38hQzg5TDj`

**status\_details** `object`

This parameter returns the current status of the payout. For example, `IMPS is not enabled on beneficiary account, Retry with different mode.`

**description** `string`

A description for the error. For example, `IMPS is not enabled on beneficiary account, please retry with different mode`.

**source** `string`

Possible values:

* `gateway`: Technical error at Razorpay Curlec Partner bank.
* `beneficiary_bank`: Technical error at beneficiary bank.
* `business`: Merchant action required.
* `internal`: Technical error at Razorpay Curlec's server.

**reason** `string`

Reason for the current status. For example, `imps_not_allowed`. Payout Status Details and Next Steps.

**created\_at** `integer`

Timestamp, in Unix, when the payout was created. For example, `1545320320`.

**fee\_type** `string`

Indicates the fee type charged for the payout. Possible values is `free_payout`.

## Errors

> [accordion] No linked account details found
>
> **Code:** `400`
>
> No linked VPA (UPI) found for the entered mobile number.
>
> **Solution:** Enter a mobile number which is linked to a VPA.

> [accordion] Account holder name not matching with bank provided name
>
> **Code:** `400`
>
> Account holder name is not matching with the name fetched from the bank.
>
> **Solution:** `account_holder_name` is optional. Enter this only if you are sure of the name linked to the phone number, as per bank records. System will validate the name only if entered.

> [accordion] Mobile number should be 10-digit long
>
> **Code:** `400`
>
> Entered mobile number is not 10-digit long.
>
> **Solution:** Enter the correct 10-digit mobile number, without country code.

> [accordion] We are facing trouble fetching account details. Please try again shortly
>
> **Code:** `500`
>
> Server error. Unable to fetch account details from the server.
>
> **Solution:** This is due to the NPCI mapper API being unresponsive. Retry the request after sometime.
