Beneficiaries

Payouts can only be sent to validated beneficiaries. Register recipients via API or the merchant panel, run penny-drop validation, then use beneficiary_id in payout requests.

End-to-End Flow

1. POST /api/v1/beneficiaries          → create beneficiary (status: pending)
2. POST /api/v1/beneficiaries/{id}/validate → penny-drop validation (status: validated)
3. POST /api/v1/payout/create          → pass beneficiary_id in payout body
4. Wallet debited, money sent to beneficiary

List Beneficiaries

GET https://paygo.sanvexo.in/api/v1/beneficiaries

Query Parameters

Parameter	Required	Description
`validation_status`	No	Filter: `pending`, `validated`, `failed`
`per_page`	No	Page size (max 100, default 20)

Example

curl -X GET https://paygo.sanvexo.in/api/v1/beneficiaries \
  -H "X-API-Key: " \
  -H "X-Secret-Key: "

$ch = curl_init("https://paygo.sanvexo.in/api/v1/beneficiaries");
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => ["X-API-Key: ", "X-Secret-Key: "],
  CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);

const res = await fetch("https://paygo.sanvexo.in/api/v1/beneficiaries", {
  headers: { "X-API-Key": API_KEY, "X-Secret-Key": SECRET },
});
const data = await res.json();

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://paygo.sanvexo.in/api/v1/beneficiaries"))
  .header("X-API-Key", API_KEY)
  .header("X-Secret-Key", SECRET)
  .GET().build();

Create Beneficiary

POST https://paygo.sanvexo.in/api/v1/beneficiaries

Request Body

Parameter	Type	Required	Description
`payout_mode`	string	Yes	`bank`, `upi`, `imps`, `neft`
`name`	string	Yes	Beneficiary full name
`account_number`	string	Yes*	Bank account (bank/imps/neft)
`ifsc_code`	string	Yes*	IFSC code (bank/imps/neft)
`vpa`	string	Yes*	UPI ID (upi mode)
`bank_name`	string	No	Bank name
`mobile`	string	No	Mobile number

Example

curl -X POST https://paygo.sanvexo.in/api/v1/beneficiaries \
  -H "X-API-Key: " \
  -H "X-Secret-Key: " \
  -H "Content-Type: application/json" \
  -d '{"payout_mode":"imps","name":"Rahul Sharma","account_number":"1234567890","ifsc_code":"HDFC0001234"}'

$payload = ["payout_mode" => "imps", "name" => "Rahul Sharma", "account_number" => "1234567890", "ifsc_code" => "HDFC0001234"];
$ch = curl_init("https://paygo.sanvexo.in/api/v1/beneficiaries");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_HTTPHEADER => ["X-API-Key: ...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode($payload), CURLOPT_RETURNTRANSFER => true]);

await fetch("https://paygo.sanvexo.in/api/v1/beneficiaries", {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ payout_mode: "imps", name: "Rahul Sharma", account_number: "1234567890", ifsc_code: "HDFC0001234" }),
});

String body = "{\"payout_mode\":\"imps\",\"name\":\"Rahul Sharma\",\"account_number\":\"1234567890\",\"ifsc_code\":\"HDFC0001234\"}";
HttpRequest.newBuilder().uri(URI.create("https://paygo.sanvexo.in/api/v1/beneficiaries")).POST(HttpRequest.BodyPublishers.ofString(body))...

Success Response

HTTP 201 Created

{
  "success": true,
  "message": "Beneficiary created. Run validation before payouts.",
  "data": {
    "id": 1,
    "name": "Rahul Sharma",
    "validation_status": "pending"
  }
}

Validate Beneficiary (Penny Drop)

POST https://paygo.sanvexo.in/api/v1/beneficiaries/{id}/validate

Simulates a ₹1 penny drop and name match. On success, validation_status becomes validated and the beneficiary can receive payouts.

Example

curl -X POST https://paygo.sanvexo.in/api/v1/beneficiaries/1/validate \
  -H "X-API-Key: " \
  -H "X-Secret-Key: "

$ch = curl_init("https://paygo.sanvexo.in/api/v1/beneficiaries/1/validate");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_HTTPHEADER => ["X-API-Key: ..."], CURLOPT_RETURNTRANSFER => true]);

await fetch("https://paygo.sanvexo.in/api/v1/beneficiaries/1/validate", { method: "POST", headers: { "X-API-Key": API_KEY } });

HttpRequest.newBuilder().uri(URI.create("https://paygo.sanvexo.in/api/v1/beneficiaries/1/validate")).POST(HttpRequest.BodyPublishers.noBody())...

Get Beneficiary

GET https://paygo.sanvexo.in/api/v1/beneficiaries/{id}

Use in Payout

Once validated, pass the beneficiary ID when creating a payout:

{
  "reference_id": "PAY-001",
  "amount": 1000,
  "payout_mode": "imps",
  "beneficiary_id": 1,
  "beneficiary_name": "Rahul Sharma",
  "beneficiary_account": "1234567890",
  "beneficiary_ifsc": "HDFC0001234"
}

You can also manage beneficiaries in Merchant Panel → Beneficiaries. The same records are used by the API.

If you send payout details without beneficiary_id, the system auto-creates a pending beneficiary — payouts will fail until validation completes.