# Payouts

### Guidelines

Below are some of the points you must be aware of while calling Payouts APIs:

* All API requests and responses are in JSON format.
* POST requests should include `ContentType: application/json` 
* All API response have **status,  message,** and **data**.
* Swipez uses API keys to allow access to the API. Once you have signed up at our merchant site, you will be able to see your [AccessKey and SecretKey](https://www.swipez.in/merchant/profile/accesskey).

### Quick Reference

| URL                                                                                             | HTTP Verb | Functionality                 |
| ----------------------------------------------------------------------------------------------- | --------- | ----------------------------- |
| [/api/token](https://docs.swipez.in/payouts#get-token)                                          | POST      | To get auth token.            |
| [/api/v1/beneficiary/save](https://docs.swipez.in/payouts#save-beneficiary)                     | POST      | To save beneficiary details.  |
| [/api/v1/beneficiary/transfer](https://docs.swipez.in/payouts#transfer-amount)                  | POST      | To transfer amount.           |
| [/api/v1/payout/withdraw](https://docs.swipez.in/payouts#withdraw-amount)                       | POST      | To withdraw amount.           |
| [/api/v1/payout/balance](https://docs.swipez.in/payouts#get-balance)                            | GET       | To get nodal balance.         |
| [/api/v1/payout/transferstatus/{type}/{id}](https://docs.swipez.in/payouts#get-transfer-status) | GET       | To get transfer status.       |
| [/api/v1/beneficiary/list](https://docs.swipez.in/payouts#get-beneficiary-list)                 | GET       | To get list of beneficiary.   |
| [/api/v1/beneficiary/detail](https://docs.swipez.in/payouts#beneficiary-detail)                 | POST      | To fetch beneficiary details. |

### **Authentication**

Calling the Authentication APIs allows you to get and verify bearer tokens returned by Swipez. Swipez require these token for all further communication.

> * Swipez libraries automatically call the Authorize API and internally store the token.
>
> * Do not store the token in an insecure manner. Regenerating a new token does not invalidate the already generated token. Token generated from one IP address cannot be used from a different IP address.
>
> * Token generated is valid for 60 Min . Please ensure that you get a new token by calling the authorize API once the token has expired.

### Rate limiting

The API is rate limited per user. You will receive a 429 HTTP status code if you exceed the rate limit. The rate limit is 30 requests per minute per user and is subject to change.

## Get token

<mark style="color:green;">`POST`</mark> `/api/token`

This endpoint allows you to get API token.

#### Request Body

| Name                | Type   | Description      |
| ------------------- | ------ | ---------------- |
| access\_key\_id     | string | Your access key. |
| secret\_access\_key | string | Your secret key. |

{% tabs %}
{% tab title="200 " %}

```
{
    "success": {
        "token": "<GENERATED TOEKN>"
    }
}
```

{% endtab %}

{% tab title="401 " %}

```
{
    "error": "Invalid Keys",
    "status": 0
}
```

{% endtab %}
{% endtabs %}

#### Sample code

{% tabs %}
{% tab title="CURL" %}

```javascript
curl --location --request POST '<BASE URL>/api/token' \
--form 'access_key_id="<GET ACCESS KEY ID FROM YOUR ACCOUNT>"' \
--form 'secret_access_key="<GET SECRET ACCESS KEY FROM YOUR ACCOUNT>"'


```

{% endtab %}

{% tab title="PHP" %}

```
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '<BASE URL>/api/token',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('access_key_id' => '<GET ACCESS KEY ID FROM YOUR ACCOUNT>','secret_access_key' => '<GET SECRET ACCESS KEY FROM YOUR ACCOUNT>'),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

```

{% endtab %}
{% endtabs %}

## Save beneficiary

<mark style="color:green;">`POST`</mark> `/api/v1/beneficiary/save`

This endpoint allows you to add beneficiary.

#### Headers

| Name          | Type   | Description       |
| ------------- | ------ | ----------------- |
| Authorization | string | Bearer auth token |
| Content-Type  | string | application/json  |

#### Request Body

| Name            | Type   | Description           |
| --------------- | ------ | --------------------- |
| name            | string | Beneficiary name.     |
| email\_id       | string | Beneficiary email id. |
| mobile          | string | Beneficiary mobile.   |
| account\_number | string | Bank account number.  |
| ifsc            | string | Bank IFSC code.       |
| address         | string | Beneficiary address.  |
| city            | string | Beneficiary city.     |
| state           | string | Beneficiary state.    |
| pincode         | string | Beneficiary pincode.  |

{% tabs %}
{% tab title="200 " %}

```
{
  "success":"Beneficiary added successfully",
  "status": "1",
  "beneficiary_id": "8545"
}
```

{% endtab %}
{% endtabs %}

#### Sample code

{% tabs %}
{% tab title="CURL" %}

```javascript
curl --location --request POST '<BASE URL>/api/v1/beneficiary/save' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Rohit Sharma",
  "email_id": "rohit@swipez.in",
  "mobile": "9999999999",
  "account_number": "000111122235",
  "ifsc": "HDFC0000008",
  "upi": "rohit@okaxis",
  "address": "Behala Manton Super Market, Room 43, Behala",
  "city": "Bangalore",
  "state": "Karnataka",
  "pincode": "560001"
}'
```

{% endtab %}

{% tab title="PHP" %}

```

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '<BASE URL>/api/v1/beneficiary/save',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "name": "Rohit Sharma",
  "email_id": "rohit@swipez.in",
  "mobile": "9999999999",
  "account_number": "000111122235",
  "ifsc": "HDFC0000008",
  "upi": "rohit@okaxis",
  "address": "Behala Manton Super Market, Room 43, Behala",
  "city": "Bangalore",
  "state": "Karnataka",
  "pincode": "560001"
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer <TOKEN>',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

{% endtab %}
{% endtabs %}

## Transfer amount

<mark style="color:green;">`POST`</mark> `/api/v1/beneficiary/transfer`

This endpoint allows you to transfer amount to beneficiary.

#### Headers

| Name          | Type   | Description       |
| ------------- | ------ | ----------------- |
| Authorization | string | Bearer auth token |
| Content-Type  | string | application/json  |

#### Request Body

| Name            | Type    | Description                      |
| --------------- | ------- | -------------------------------- |
| beneficiary\_id | string  | System generated beneficiary id. |
| amount          | integer | Transfer amount.                 |
| reference\_id   | string  | Your unique reference id.        |
| narrative       | string  | Narrative for transaction.       |

{% tabs %}
{% tab title="200 " %}

```
{
  "success":"Amount transfred successfully",
  "status": "1",
  "transfer_status": "SUCCESS", // SUCCESS or PENDING
  "utr_number": "UTR87542455"
}
```

{% endtab %}
{% endtabs %}

#### Sample code

{% tabs %}
{% tab title="CURL" %}

```javascript
curl --location --request POST '<BASE URL>/api/v1/beneficiary/transfer' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "beneficiary_id":"<SYSTEM GENERATED ID>",
  "amount": "100",
  "reference_id": "124",
  "mode" : "banktransfer", //banktransfer or upi
  "narrative": "First transfer"
}'
```

{% endtab %}

{% tab title="PHP" %}

```

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '<BASE URL>/api/v1/beneficiary/transfer',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "beneficiary_id":"<SYSTEM GENERATED ID>",
  "amount": "100",
  "reference_id": "124",
  "mode" : "banktransfer", //banktransfer or upi
  "narrative": "First transfer"
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer <TOKEN>',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

{% endtab %}
{% endtabs %}

## Withdraw amount

<mark style="color:green;">`POST`</mark> `/api/v1/payout/withdraw`

This endpoint allows you to withdraw amount to your bank account from nodal.

#### Headers

| Name          | Type   | Description       |
| ------------- | ------ | ----------------- |
| Authorization | string | Bearer auth token |
| Content-Type  | string | application/json  |

#### Request Body

| Name      | Type    | Description                         |
| --------- | ------- | ----------------------------------- |
| amount    | integer | Withdraw amount.                    |
| narrative | string  | Narrative for withdraw transaction. |

{% tabs %}
{% tab title="200 " %}

```
{
  "success":"Amount withdraw successfully",
  "status": "1",
}
```

{% endtab %}
{% endtabs %}

#### Sample code

{% tabs %}
{% tab title="CURL" %}

```javascript
curl --location --request POST '<BASE URL>/api/v1/payout/withdraw' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": "100",
  "narrative": "First withdraw"
}'
```

{% endtab %}

{% tab title="PHP" %}

```

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '<BASE URL>/api/v1/payout/withdraw',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "amount": "100",
  "narrative": "First withdraw"
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer <TOKEN>',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

{% endtab %}
{% endtabs %}

## Get balance

<mark style="color:blue;">`GET`</mark> `/api/v1/payout/balance`

This endpoint allows you to get the ledger balance and available balance of your account.

#### Headers

| Name          | Type   | Description       |
| ------------- | ------ | ----------------- |
| Authorization | string | Bearer auth token |
| Content-Type  | string | application/json  |

{% tabs %}
{% tab title="200 " %}

```
{
  "balance":"10000.00",
  "status": "1",
}
```

{% endtab %}
{% endtabs %}

#### Sample code

{% tabs %}
{% tab title="CURL" %}

```javascript
curl --location --request GET '<BASE URL>/api/v1/payout/balance' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
```

{% endtab %}

{% tab title="PHP" %}

```

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '<BASE URL>/api/v1/payout/balance',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  ,
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer <TOKEN>',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

{% endtab %}
{% endtabs %}

## Get transfer status

<mark style="color:blue;">`GET`</mark> `/api/v1/payout/transferstatus/{type}/{id}`

This endpoint allows you to status of transaction.

#### Path Parameters

| Name | Type   | Description                                                                                                                                                                     |
| ---- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type | string | <p>Id type (transferid/referenceid)<br>transferid: Transfer id which is return while transfer amount.<br>referenceid: Reference id which is sent by merchant while transfer</p> |
| id   | number | Reference id or transfer id as per mentioned type.                                                                                                                              |

#### Headers

| Name          | Type   | Description       |
| ------------- | ------ | ----------------- |
| Authorization | string | Bearer auth token |
| Content-Type  | string | application/json  |

{% tabs %}
{% tab title="200 " %}

```
{
	"status": "1",
	"success": {
		"transfer": {
			"referenceId": 17073,
			"bankAccount": "1212114454",
			"beneId": "54121",
			"amount": "100.00",
			"status": "SUCCESS",
			"utr": "HGFD542121",
			"addedOn": "2021-02-01 11:20:00",
			"processedOn": "2021-02-01 11:20:00",
			"acknowledged": 1
		}
	}
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="PHP" %}

```
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '<BASE URL>/api/v1/payout/transferstatus/{type}/{id}',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  ,
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer <TOKEN>',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

{% endtab %}
{% endtabs %}

## Get beneficiary list

<mark style="color:blue;">`GET`</mark> `/api/v1/beneficiary/list`

This endpoint allows you to fetch list of beneficiary.

#### Headers

| Name          | Type   | Description       |
| ------------- | ------ | ----------------- |
| Authorization | string | Bearer auth token |
| Content-Type  | string | application/json  |

{% tabs %}
{% tab title="200 " %}

```
{
    "success": [
        {
            "beneficiary_id": "V00000010",
            "merchant_id": "M000054545",
            "type": "Vendor",
            "name": "Rohit Sharma",
            "email_id": "rohit@swipez.in",
            "mobile": "9999999999",
            "address": "Behala Manton Super Market, Room 43, Behala",
            "city": "Bangalore",
            "state": "Karnataka",
            "zipcode": "410014",
            "bank_account_no": "000111122234",
            "ifsc_code": "SBIN0009302",
            "created_date": "2020-02-07 18:53:42"
        },
        {
            "beneficiary_id": "V00000011",
            "merchant_id": "M000054545",
            "type": "Vendor",
            "name": "Virat Kohli",
            "email_id": "virat@swipez.in",
            "mobile": "9999999999",
            "address": "Behala Manton Super Market, Room 43, Behala",
            "city": "Bangalore",
            "state": "Karnataka",
            "zipcode": "410014",
            "bank_account_no": "000111122235",
            "ifsc_code": "SBIN0009302",
            "created_date": "2020-02-07 18:53:42"
        }
    ],
    "status": "1"
}
```

{% endtab %}
{% endtabs %}

#### Sample code

{% tabs %}
{% tab title="CURL" %}

```javascript
curl --location --request GET '<BASE URL>/api/v1/beneficiary/list' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
```

{% endtab %}

{% tab title="PHP" %}

```
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '<BASE URL>/api/v1/beneficiary/list',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  ,
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer <TOKEN>',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

{% endtab %}
{% endtabs %}

## Beneficiary detail

<mark style="color:green;">`POST`</mark> `/api/v1/beneficiary/detail`

This endpoint allows you to fetch beneficiary details.

#### Headers

| Name          | Type   | Description       |
| ------------- | ------ | ----------------- |
| Authorization | string | Bearer auth token |
| Content-Type  | string | application/json  |

#### Request Body

| Name            | Type    | Description    |
| --------------- | ------- | -------------- |
| account\_number | integer | Account number |
| ifsc            | string  | IFSC code      |

{% tabs %}
{% tab title="200 " %}

```
{
    "success": 
        {
            "beneficiary_id": "V00000010",
            "merchant_id": "M000054545",
            "type": "Vendor",
            "name": "Rohit Sharma",
            "email_id": "rohit@swipez.in",
            "mobile": "9999999999",
            "address": "Behala Manton Super Market, Room 43, Behala",
            "city": "Bangalore",
            "state": "Karnataka",
            "zipcode": "410014",
            "bank_account_no": "000111122234",
            "ifsc_code": "SBIN0009302",
            "created_date": "2020-02-07 18:53:42"
        },
    "status": "1"
}
```

{% endtab %}
{% endtabs %}

#### Sample code

{% tabs %}
{% tab title="CURL" %}

```javascript
curl --location --request POST '<BASE URL>/api/v1/beneficiary/detail' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "account_number": "0000122121",
  "ifsc": "KKBK0001245"
}'
```

{% endtab %}

{% tab title="PHP" %}

```
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '<BASE URL>/api/v1/beneficiary/detail',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "account_number": "0000122121",
  "ifsc": "KKBK0001245"
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer <TOKEN>',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.swipez.in/payouts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.