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

# Initiate a Payout 

> Send funds from a virtual account to a verified beneficiary via IMPS, NEFT, RTGS, or UPI. Provide contact_id, va_id, amount, and payment_mode.

Use this endpoint to send funds from a virtual account to a verified beneficiary contact. You can route payments over IMPS, NEFT, RTGS, or UPI by specifying the `payment_mode` in your request body.

> [!WARNING]
>
> Only **VERIFIED** contacts can receive payouts. Call the Get Contact Status API before initiating if you are unsure of the beneficiary's verification state.

## Headers

**x-api-key** `string` *required*

Your secret API key.

**Content-Type** `string` *required*

Must be `application/json`.

**X-Real-IP** `string` *required*

Your whitelisted server IP address.

## Request Body Example

```json theme={"dark"}
{
    "order_id": "TEST_ORDER_ID_12345",
    "contact_id": "xxxxxxxxxxxx",
    "amount": "100.00",
    "payment_mode": "IMPS",
    "description": "TEST FUND TRANSFER",
    "transaction_purpose_code": "BS103",
    "va_id": "ec1f20ee-eba6-49d8-9d69-909894629544"
}
```

## Request Parameters

**contact\_id** `uuid` *required*

The `contact_id` generated when you created the beneficiary contact.

**payment\_mode** `string` *required*

Transfer mode. Accepted values: `IMPS`, `NEFT`, `RTGS`, `UPI`.

**amount** `string` *required*

Amount to transfer, expressed as a decimal string (e.g., `"200.00"`).

**order\_id** `string` *required*

Your unique internal transaction ID used to track this payout on your side.

**description** `string` *required*

Narration or remarks for the fund transfer.

**transaction\_purpose\_code** `string`

Permissible purpose code for the transaction. See [Transaction Purpose Codes](/docs/payouts/transaction-purpose-codes.md) for the full list of accepted `bs_code` values.

**va\_id** `string` *required*

The virtual account ID from which the funds will be debited.

## Sample Request

```sh Shell theme={"dark"}
curl --location 'https://api.bluswap.co/api/v1/merchants/initiate_pay_out_cust' \
  --header 'x-api-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --header 'X-Real-IP: YOUR_WHITELISTED_IP' \
  --data '{
    "order_id": "TEST_ORDER_ID_12345",
    "contact_id": "YOUR_CONTACT_ID",
    "amount": "100.00",
    "payment_mode": "IMPS",
    "description": "TEST FUND TRANSFER",
    "transaction_purpose_code": "BS103",
    "va_id": "YOUR_VA_ID"
  }'
```

```js Node.js theme={"dark"}
const response = await fetch('https://api.bluswap.co/api/v1/merchants/initiate_pay_out_cust', {
  method: 'POST',
  headers: { 'x-api-key': '<YOUR_API_KEY>', 'Content-Type': 'application/json', 'X-Real-IP': '<YOUR_WHITELISTED_IP>' },
  body: JSON.stringify({ order_id: 'TEST_ORDER_ID_12345', contact_id: 'YOUR_CONTACT_ID', amount: '100.00', payment_mode: 'IMPS', description: 'TEST FUND TRANSFER', transaction_purpose_code: 'BS103', va_id: 'YOUR_VA_ID' })
});
console.log(await response.json());
```

```python Python theme={"dark"}
import requests

response = requests.post(
    "https://api.bluswap.co/api/v1/merchants/initiate_pay_out_cust",
    headers={"x-api-key": "<YOUR_API_KEY>", "X-Real-IP": "<YOUR_WHITELISTED_IP>"},
    json={"order_id": "TEST_ORDER_ID_12345", "contact_id": "YOUR_CONTACT_ID", "amount": "100.00", "payment_mode": "IMPS", "description": "TEST FUND TRANSFER", "transaction_purpose_code": "BS103", "va_id": "YOUR_VA_ID"},
)
print(response.json())
```

```java Java theme={"dark"}
var body = "{\"order_id\":\"TEST_ORDER_ID_12345\",\"contact_id\":\"YOUR_CONTACT_ID\",\"amount\":\"100.00\",\"payment_mode\":\"IMPS\",\"description\":\"TEST FUND TRANSFER\",\"transaction_purpose_code\":\"BS103\",\"va_id\":\"YOUR_VA_ID\"}";
var request = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://api.bluswap.co/api/v1/merchants/initiate_pay_out_cust")).headers("x-api-key", "<YOUR_API_KEY>", "Content-Type", "application/json", "X-Real-IP", "<YOUR_WHITELISTED_IP>").POST(java.net.http.HttpRequest.BodyPublishers.ofString(body)).build();
var response = java.net.http.HttpClient.newHttpClient().send(request, java.net.http.HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

```go Go theme={"dark"}
package main
import ("net/http"; "strings")
func main() {
payload := strings.NewReader(`{"order_id":"TEST_ORDER_ID_12345","contact_id":"YOUR_CONTACT_ID","amount":"100.00","payment_mode":"IMPS","description":"TEST FUND TRANSFER","transaction_purpose_code":"BS103","va_id":"YOUR_VA_ID"}`)
request, _ := http.NewRequest(http.MethodPost, "https://api.bluswap.co/api/v1/merchants/initiate_pay_out_cust", payload)
request.Header.Set("x-api-key", "<YOUR_API_KEY>")
request.Header.Set("Content-Type", "application/json")
request.Header.Set("X-Real-IP", "<YOUR_WHITELISTED_IP>")
response, _ := http.DefaultClient.Do(request)
defer response.Body.Close()
}
```

```php PHP theme={"dark"}
<?php
$curl = curl_init('https://api.bluswap.co/api/v1/merchants/initiate_pay_out_cust');
curl_setopt_array($curl, [CURLOPT_POST => true, CURLOPT_HTTPHEADER => ['x-api-key: <YOUR_API_KEY>', 'Content-Type: application/json', 'X-Real-IP: <YOUR_WHITELISTED_IP>'], CURLOPT_POSTFIELDS => json_encode(['order_id' => 'TEST_ORDER_ID_12345', 'contact_id' => 'YOUR_CONTACT_ID', 'amount' => '100.00', 'payment_mode' => 'IMPS', 'description' => 'TEST FUND TRANSFER', 'transaction_purpose_code' => 'BS103', 'va_id' => 'YOUR_VA_ID']), CURLOPT_RETURNTRANSFER => true]);
echo curl_exec($curl);
curl_close($curl);
```

```ruby Ruby theme={"dark"}
require "json"
require "net/http"

uri = URI("https://api.bluswap.co/api/v1/merchants/initiate_pay_out_cust")
request = Net::HTTP::Post.new(uri, {"x-api-key" => "<YOUR_API_KEY>", "Content-Type" => "application/json", "X-Real-IP" => "<YOUR_WHITELISTED_IP>"})
request.body = {order_id: "TEST_ORDER_ID_12345", contact_id: "YOUR_CONTACT_ID", amount: "100.00", payment_mode: "IMPS", description: "TEST FUND TRANSFER", transaction_purpose_code: "BS103", va_id: "YOUR_VA_ID"}.to_json
puts Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request).body }
```

## Success Response

```json theme={"dark"}
{
    "status": "SUCCESS",
    "status_code": 200,
    "message": "Succefully initiated payout!",
    "detail": null,
    "data": {
        "bluswap_transaction_id": "xxxxxxxxxxx",
        "ref_id": "xxxxxxxxxxxxxx",
        "amount": "100.00",
        "order_id": "TEST_ORDER_ID_12345",
        "payment_mode": "IMPS",
        "status": "INITIATED",
        "currency": null,
        "total_balance": null,
        "available_balance": "112369.24",
        "remarks": "TEST FUND TRANSFER",
        "to_account_number": "xxxxxxxxxxxxx"
    }
}
```

> [!TIP]
>
> Save the `bluswap_transaction_id` from the response. You will need it to poll the [Check Transaction Status](/docs/payouts/check-transaction-status.md) endpoint or reconcile webhook callbacks.

## Error Responses

> [tab] Beneficiary Under Verification (422)
>
> This error occurs when the beneficiary verification process is still in progress.
>
> ```json theme={"dark"}
> {
>   "status": "FAILED",
>   "status_code": 422,
>   "message": "Beneficiary is under verification, Try Initiating Payout after some time.",
>   "detail": null,
>   "data": null
> }
> ```
>
> **Recommended Action:** Call the Get Contact Status API. Wait until the status becomes `VERIFIED`, then retry the payout request.

> [tab] Invalid Beneficiary Details (400)
>
> This error occurs when the beneficiary bank details are invalid or the contact status is invalid.
>
> ```json theme={"dark"}
> {
>   "status": "FAILED",
>   "status_code": 400,
>   "message": "Beneficiary Details is Invalid",
>   "detail": null,
>   "data": null
> }
> ```
>
> **Possible reasons:**
>
> * Bank account details are incorrect
> * Contact verification failed
> * Beneficiary account marked as invalid
>
> **Recommended Action:** Recreate the contact with correct bank account details and verify the contact status before retrying the payout.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.