README

A Laravel package wrapper for integrating with SmilePayz API. This SDK provides a simple and elegant way to handle payment processing through SmilePayz in your Laravel application.

Table of Contents

• Features
• Requirements
• Quick Start
• Installation
• Configuration
• Usage
  • Basic Setup
  • Processing a Pay-in Transaction
  • Processing a Pay-out Transaction
  • Verifying Signatures
• Response Handling
• Error Handling
• Common Use Cases
• Security
• Contributing
• License
• Author

Features

• Pay-in transaction processing
• Pay-out transaction processing
• Signature verification
• Comprehensive response handling
• Laravel integration with Service Provider and Facade

Requirements

• PHP 8.0 or higher
• Laravel 8.0 or higher
• Guzzle HTTP Client
• OpenSSL Extension

Quick Start

1. Install the package:

composer require kidacallos/smilepayz-sdk

1. Set up your environment variables in .env:

SMILEPAYZ_API_URL=https://sandbox-gateway.smilepayz.com
SMILEPAYZ_MERCHANT_ID=your-merchant-id
SMILEPAYZ_MERCHANT_SECRET=your-merchant-secret
SMILEPAYZ_PUBLIC_KEY=your-platform-public-key
SMILEPAYZ_PRIVATE_KEY=your-private-key

1. Process your first payment:

use Kidacallos\SmilepayzSdk\SmilePayz;

$smile_payz = new SmilePayz();
$smile_payz->setVault([
    'api_url' => env('SMILEPAYZ_API_URL'),
    'merchant_id' => env('SMILEPAYZ_MERCHANT_ID'),
    'merchant_secret' => env('SMILEPAYZ_MERCHANT_SECRET'),
    'public_key' => env('SMILEPAYZ_PUBLIC_KEY'),
    'private_key' => env('SMILEPAYZ_PRIVATE_KEY'),
]);

$response = $smile_payz->validateDeposit([
    'order_no' => 'ORDER123',
    'money' => [
        'amount' => 1000.00,
        'currency' => 'IDR'
    ]
    // ... other required fields
])->payIn();

Installation

You can install the package via composer:

composer require kidacallos/smilepayz-sdk

The package will automatically register its service provider and facade.

Configuration

Using Environment Variables

We recommend using environment variables for your SmilePayz configuration. Add the following to your .env file:

SMILEPAYZ_API_URL=https://sandbox-gateway.smilepayz.com
SMILEPAYZ_MERCHANT_ID=your-merchant-id
SMILEPAYZ_MERCHANT_SECRET=your-merchant-secret
SMILEPAYZ_PUBLIC_KEY=your-platform-public-key
SMILEPAYZ_PRIVATE_KEY=your-private-key

Then in your configuration:

$smile_payz = new SmilePayz();
$smile_payz->setVault([
    'api_url' => env('SMILEPAYZ_API_URL'),
    'merchant_id' => env('SMILEPAYZ_MERCHANT_ID'),
    'merchant_secret' => env('SMILEPAYZ_MERCHANT_SECRET'),
    'public_key' => env('SMILEPAYZ_PUBLIC_KEY'),
    'private_key' => env('SMILEPAYZ_PRIVATE_KEY'),
]);

Usage

Basic Setup

First, initialize SmilePayz and set your configuration:

use Kidacallos\SmilepayzSdk\SmilePayz;

$smile_payz = new SmilePayz();
$smile_payz->setVault([
    'api_url' => env('SMILEPAYZ_API_URL'),
    'merchant_id' => env('SMILEPAYZ_MERCHANT_ID'),
    'merchant_secret' => env('SMILEPAYZ_MERCHANT_SECRET'),
    'public_key' => env('SMILEPAYZ_PUBLIC_KEY'),
    'private_key' => env('SMILEPAYZ_PRIVATE_KEY'),
]);

Processing a Pay-in Transaction

$payload = [
    'area' => 10,
    'callback_url' => 'https://your-callback-url.com/callback',
    'expiry_period' => 3600, // Optional
    'merchant' => [
        'merchant_id' => 'your-merchant-id'
    ],
    'money' => [
        'amount' => 1000.00,
        'currency' => 'IDR'
    ],
    'order_no' => 'ORDER123456',
    'payer' => [
        'address' => '123 Main St',
        'email' => 'customer@example.com',
        'name' => 'John Doe',
        'phone' => '+639123456789'
    ],
    'payment_method' => 'BCA', // Optional
    'purpose' => 'Pay-in Transaction',
    'redirect_url' => 'https://your-redirect-url.com/success'
];

try {
    $response = $smile_payz->validateDeposit($payload)->payIn();

    // Access response data
    $trade_no = $response->getTradeNo();
    $status = $response->getStatus();
    $transaction_time = $response->getTransactionTime();

} catch (InvalidArgumentException $e) {
    // Handle validation errors
} catch (VaultNotFoundException $e) {
    // Handle missing configuration
} catch (FailedResponseException $e) {
    // Handle API errors
}

Processing a Pay-out Transaction

$payload = [
    'area' => 10,
    'callback_url' => 'https://your-callback-url.com/callback',
    'cash_account' => 'ACCOUNT123',
    'merchant' => [
        'merchant_id' => 'your-merchant-id'
    ],
    'money' => [
        'amount' => 1000.00,
        'currency' => 'IDR'
    ],
    'order_no' => 'ORDER123456',
    'payment_method' => 'ACEH',
    'purpose' => 'Pay-out Transaction'
];

try {
    $response = $smile_payz->validateWithdrawal($payload)->payOut();

    // Access response data
    $trade_no = $response->getTradeNo();
    $status = $response->getStatus();
    $disbursement_time = $response->getDisbursementTime();

} catch (InvalidArgumentException $e) {
    // Handle validation errors
} catch (VaultNotFoundException $e) {
    // Handle missing configuration
} catch (FailedResponseException $e) {
    // Handle API errors
}

Verifying Signatures

try {
    $is_valid = $smile_payz->verifySignature(
        $trade_no,
        $timestamp,
        $signature
    );

    if ($is_valid === 1) {
        // Signature is valid
    } else if ($is_valid === 0) {
        // Signature is invalid
    } else {
        // Error occurred during verification
    }
} catch (Exception $e) {
    // Handle verification errors
}

Response Handling

Both pay-in and pay-out operations return response objects (PayInResponse and PayOutResponse respectively) with the following methods:

• getCode(): Get the response code
• getMessage(): Get the response message
• getOrderNo(): Get the order number
• getMerchant(): Get merchant information
• getMoney(): Get transaction amount and currency
• getChannel(): Get payment channel information
• getTradeNo(): Get the trade number
• getStatus(): Get transaction status

Pay-in responses additionally include:

• getTransactionTime(): Get the transaction timestamp

Pay-out responses additionally include:

• getDisbursementTime(): Get the disbursement timestamp

Error Handling

The SDK throws the following exceptions:

• InvalidArgumentException: When payload validation fails
• VaultNotFoundException: When SDK configuration is missing
• FailedResponseException: When the API request fails
• Exception: For general errors

Common Use Cases

Processing a Simple Payment

use Kidacallos\SmilepayzSdk\SmilePayz;

$smile_payz = new SmilePayz();
$smile_payz->setVault([
    'api_url' => env('SMILEPAYZ_API_URL'),
    'merchant_id' => env('SMILEPAYZ_MERCHANT_ID'),
    'merchant_secret' => env('SMILEPAYZ_MERCHANT_SECRET'),
    'public_key' => env('SMILEPAYZ_PUBLIC_KEY'),
    'private_key' => env('SMILEPAYZ_PRIVATE_KEY'),
]);

$response = $smile_payz->validateDeposit([
    'order_no' => 'ORDER123',
    'money' => [
        'amount' => 1000.00,
        'currency' => 'IDR'
    ],
    'payer' => [
        'email' => 'customer@example.com',
        'name' => 'John Doe'
    ]
])->payIn();

Handling Callbacks

public function handleCallback(Request $request)
{
    $is_valid = $smile_payz->verifySignature(
        $request->trade_no,
        $request->timestamp,
        $request->signature
    );

    if ($is_valid === 1) {
        // Update your order status
        Order::where('trade_no', $request->trade_no)
            ->update(['status' => $request->status]);
    }
}

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

The MIT License (MIT). Please see License File for more information.

Author

• Kenneth I. Dacallos (kennethdacallos@gmail.com)