Payouts

Learn more about payouts APIs and their usage.

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.

Quick Reference

URL	HTTP Verb	Functionality
/api/token	POST	To get auth token.
/api/v1/beneficiary/save	POST	To save beneficiary details.
/api/v1/beneficiary/transfer	POST	To transfer amount.
/api/v1/payout/withdraw	POST	To withdraw amount.
/api/v1/payout/balance	GET	To get nodal balance.
/api/v1/payout/transferstatus/{type}/{id}	GET	To get transfer status.
/api/v1/beneficiary/list	GET	To get list of beneficiary.
/api/v1/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

POST /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.

200

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

401

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

Sample code

CURL

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>"'

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;

Save beneficiary

POST /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.

200

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

Sample code

CURL

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": "[e-mail]",
  "mobile": "9999999999",
  "account_number": "000111122235",
  "ifsc": "HDFC0000008",
  "upi": "rohit@okaxis",
  "address": "Behala Manton Super Market, Room 43, Behala",
  "city": "Bangalore",
  "state": "Karnataka",
  "pincode": "560001"
}'

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": "[e-mail]",
  "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;

Transfer amount

POST /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.

200

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

Sample code

CURL

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"
}'

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;

Withdraw amount

POST /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.

200

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

Sample code

CURL

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"
}'

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;

Get balance

GET /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

200

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

Sample code

CURL

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

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;

Get transfer status

GET /api/v1/payout/transferstatus/{type}/{id}

This endpoint allows you to status of transaction.

Path Parameters

Name	Type	Description
type	string	Id type (transferid/referenceid) transferid: Transfer id which is return while transfer amount. referenceid: Reference id which is sent by merchant while transfer
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

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

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;

Get beneficiary list

GET /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

200

{
    "success": [
        {
            "beneficiary_id": "V00000010",
            "merchant_id": "M000054545",
            "type": "Vendor",
            "name": "Rohit Sharma",
            "email_id": "[e-mail]",
            "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": "[e-mail]",
            "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"
}

Sample code

CURL

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

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;

Beneficiary detail

POST /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

200

{
    "success": 
        {
            "beneficiary_id": "V00000010",
            "merchant_id": "M000054545",
            "type": "Vendor",
            "name": "Rohit Sharma",
            "email_id": "[e-mail]",
            "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"
}

Sample code

CURL

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"
}'

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;