README

Official PHP SDK for integrating with CashPay Payment Gateway.

Installation

Via Composer (Recommended)

You can install the SDK via Composer:

composer require cashpayyy/sdk

Via GitHub VCS

If you prefer to use the latest version directly from our repository, add this to your composer.json:

{
    "require": {
        "cashpayyy/sdk": "dev-main"
    },
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/Annesbadusha/cashpay-php-sdk.git"
        }
    ]
}

Manual Installation

Alternatively, clone the repository into your project and configure path-based loading.

Quick Start

<?php
require_once 'vendor/autoload.php';

use CashPay\CashPay;

$cashpay = new CashPay(
    apiKey: 'cpk_live_xxx',
    apiSecret: 'cps_live_xxx',
    environment: 'production' // or 'sandbox'
);

Usage Examples

Check Balance

// Get unified balance
$balance = $cashpay->balance->get();
echo "Total Balance: ₹" . ($balance['totalBalance'] / 100);

// Get settlement balance
$settlement = $cashpay->balance->getSettlement();
echo "Available for withdrawal: ₹" . ($settlement['availableWithdrawalAmount'] / 100);

// Get payout balance
$payout = $cashpay->balance->getPayout();
echo "Payout Balance: ₹" . ($payout['payoutBalance'] / 100);

Payins

// 1. Create a Hosted Payment Page (Direct Redirect Flow)
$page = $cashpay->payins->createPaymentPage([
    'amount' => 10000, // ₹100
    'orderId' => 'ORDER_123',
    'customerName' => 'John Doe',
    'customerEmail' => 'john@example.com',
    'customerPhone' => '9876543210',
    'returnUrl' => 'https://yoursite.com/payment/result'
]);
echo "Payment URL: " . $page['paymentUrl'];

// 2. Create UPI Intent (Minimal)
$intent = $cashpay->payins->createIntent([
    'amount' => 1000,
    'orderId' => 'ORDER_124'
]);
echo "UPI DeepLink: " . $intent['intentUrl'];

// 3. Create Card Payment
$card = $cashpay->payins->createCard([
    'amount' => 10000,
    'orderId' => 'ORDER_125',
    'cardNumber' => '4111111111111111',
    'expiryMonth' => '12',
    'expiryYear' => '2025',
    'cvv' => '123'
]);

// 4. Create NetBanking 
$nb = $cashpay->payins->createNetBanking([
    'amount' => 10000,
    'orderId' => 'ORDER_126',
    'bankCode' => 'HDFC',
    'returnUrl' => 'https://yoursite.com/callback'
]);

// Get payin status by payment ID
$status = $cashpay->payins->getStatus('payment-uuid');

// Get payin by order ID
$payin = $cashpay->payins->getByOrderId('ORDER_124');
echo "Status: {$payin['status']}, UTR: {$payin['utr']}";

Payment Links

// Create a shareable payment link or QR
$link = $cashpay->paymentLinks->create([
    'amount' => 50000,
    'description' => 'Invoice #001',
    'type' => 'one-time', // or 'reusable'
    'outputType' => 'link' // or 'qr'
]);
echo "Short URL: " . $link['shortUrl'];

// List payment links
$links = $cashpay->paymentLinks->list(page: 1, limit: 10, status: 'active');

// Deactivate a link
$cashpay->paymentLinks->deactivate('link-uuid');

Beneficiaries & Bank Accounts

// Add a beneficiary for payouts
$beneficiary = $cashpay->beneficiaries->create([
    'name' => 'John Doe',
    'accountNumber' => '50100123456789',
    'ifsc' => 'HDFC0001234'
]);

// Add a merchant bank account for settlements
$bank = $cashpay->bankAccounts->create([
    'accountNumber' => '50100123456789',
    'ifsc' => 'HDFC0001234',
    'accountHolderName' => 'My Business'
]);

Payouts

// Create a payout
$payout = $cashpay->payouts->create(
    beneficiaryId: 'ben_xxx',
    amount: 10000, // ₹100 in paise
    referenceId: 'PAY-001',
    narration: 'Salary payment',
    mode: 'IMPS',
    idempotencyKey: 'unique-key'
);
echo "Payout ID: {$payout['id']}, Status: {$payout['status']}";

// Create bulk payouts (max 100)
$bulkResult = $cashpay->payouts->createBulk([
    ['beneficiaryId' => 'ben_1', 'amount' => 10000, 'referenceId' => 'PAY-001'],
    ['beneficiaryId' => 'ben_2', 'amount' => 20000, 'referenceId' => 'PAY-002'],
], 'bulk-key');
echo "Success: {$bulkResult['successCount']}, Failed: {$bulkResult['failureCount']}";

// List payouts
$payouts = $cashpay->payouts->list(page: 1, limit: 20, status: 'COMPLETED');

// Get payout by ID
$payoutDetails = $cashpay->payouts->get('payout-uuid');

// Get payout by reference ID
$payoutByRef = $cashpay->payouts->getByReferenceId('PAY-001');

// Cancel payout
$cancelled = $cashpay->payouts->cancel('payout-uuid');

Settlements

// Create settlement with saved bank account
$settlement = $cashpay->settlements->create(
    amount: 100000, // ₹1000 in paise
    bankAccountId: 'bank_xxx',
    referenceId: 'SET-001',
    idempotencyKey: 'unique-key'
);

// Create settlement with direct bank details
$directSettlement = $cashpay->settlements->create(
    amount: 100000,
    accountNumber: '50100123456789',
    ifsc: 'HDFC0001234',
    accountHolderName: 'John Doe',
    referenceId: 'SET-002'
);

// Create bulk settlements
$bulkSettlements = $cashpay->settlements->createBulk([
    ['amount' => 50000, 'bankAccountId' => 'bank_1', 'referenceId' => 'SET-001'],
    ['amount' => 75000, 'bankAccountId' => 'bank_2', 'referenceId' => 'SET-002'],
]);

// List settlements
$settlements = $cashpay->settlements->list(status: 'COMPLETED');

// Get settlement by ID
$settlementDetails = $cashpay->settlements->get('settlement-uuid');

// Cancel settlement
$cancelledSettlement = $cashpay->settlements->cancel('settlement-uuid');

Webhook Verification

<?php
// webhook.php
require_once 'vendor/autoload.php';

use CashPay\CashPay;

$cashpay = new CashPay('cpk_live_xxx', 'cps_live_xxx');

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

$isValid = $cashpay->verifyWebhook($payload, $signature, 'your-webhook-secret');

if (!$isValid) {
    http_response_code(401);
    echo 'Invalid signature';
    exit;
}

$event = json_decode($payload, true);

switch ($event['type']) {
    case 'payin.completed':
        // Handle payment completed
        break;
    case 'payout.completed':
        // Handle payout completed
        break;
    case 'settlement.completed':
        // Handle settlement completed
        break;
}

http_response_code(200);
echo 'OK';

Error Handling

use CashPay\CashPay;
use CashPay\CashPayException;

try {
    $payout = $cashpay->payouts->create(
        beneficiaryId: 'invalid-id',
        amount: 10000
    );
} catch (CashPayException $e) {
    echo "Error: {$e->getMessage()}\n";
    echo "Status: {$e->statusCode}\n";
    echo "Code: {$e->errorCode}\n";
    print_r($e->details);
}

Configuration Options

Requirements

• PHP >= 7.4
• Guzzle HTTP Client >= 7.0

Support

• Documentation: https://docs.cashpay.com
• Email: support@cashpay.com
• GitHub Issues: https://github.com/cashpay/cashpay-php-sdk/issues