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.

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

Sample code

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

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.

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

Sample code

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

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.

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

Sample code

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

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.

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

Sample code

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

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

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

Sample code

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

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

{
	"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
		}
	}
}
$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

{
    "success": [
        {
            "beneficiary_id": "V00000010",
            "merchant_id": "M000054545",
            "type": "Vendor",
            "name": "Rohit Sharma",
            "email_id": "[email protected]",
            "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": "[email protected]",
            "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 --location --request GET '<BASE URL>/api/v1/beneficiary/list' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \

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

{
    "success": 
        {
            "beneficiary_id": "V00000010",
            "merchant_id": "M000054545",
            "type": "Vendor",
            "name": "Rohit Sharma",
            "email_id": "[email protected]",
            "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 --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"
}'
PreviousPayment APINextE-Invoice

Last updated

Was this helpful?