# 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 %}