Guide to Using Bayarcash Payment Gateway API v3 with PHP SDK

The PHP SDK simplifies the integration process, allowing developers to focus on building their applications rather than dealing with the complexities of payment processing.

Installation Process

To install the Bayarcash PHP SDK, you need to use Composer. Run the following command in your project directory:

composer require webimpian/bayarcash-php-sdk

Basic Usage & Configuration Options

After installing the SDK, you can create an instance of the Bayarcash class and configure it to use the sandbox environment for testing:

$bayarcash = new Webimpian\BayarcashSdk\Bayarcash('YOUR_API_TOKEN');
$bayarcash->useSandbox(); // Switch to sandbox environment

You can set the API version to v3 using the following method:

$bayarcash->setApiVersion('v3');

Portal Management

You can retrieve available portals and payment channels using the following methods:

// Get all available portals
$portals = $bayarcash->getPortals();

// Get available payment channels for a specific portal
$channels = $bayarcash->getChannels('your_portal_key');

Payment Processing

To create a payment intent, you can generate a checksum for enhanced security. Below is an example of how to prepare the payment data and create a payment intent:

$data = [
    'portal_key' => $bayarcash_portal_key,// Portal key from your configuration
    'order_number' => $order_no, // Unique order number
    'amount' => $order_amount, // Order amount
    'payer_name' => $buyer_name, // Payer's name
    'payer_email' => $buyer_email, // Payer's email
    'payer_telephone_number' => $buyer_tel, // Payer's telephone number
    'callback_url' => $config['return_url'], // Callback URL for payment notifications
    'return_url' => $config['return_url'], // Return URL after payment completion
    'payment_channel' => $payment_channel, // Payment channel (e.g., FPX, DuitNow, etc.)
];

// Generate checksum for payment intent
$checksum = $bayarcash->createPaymentIntenChecksumValue('API_SECRET_KEY', $data);
$data['checksum'] = $paymentIntentRequestChecksum;

// Send payment request
$response = $bayarcash->createPaymentIntent($data);
header("Location: " . $response->url); // Redirect payer to Bayarcash checkout page

Callback Verification

You can verify callbacks using the following methods:

// Pre-transaction callback
$validPreTransaction = $bayarcash->verifyPreTransactionCallbackData($callbackData, 'API_SECRET_KEY');

// Transaction callback
$validTransaction = $bayarcash->verifyTransactionCallbackData($callbackData, 'API_SECRET_KEY');

// Return URL callback
$validReturnUrl = $bayarcash->verifyReturnUrlCallbackData($callbackData, 'API_SECRET_KEY');

Transaction and Payment Intent Management

In API v3, you can retrieve transaction details based on the payment_intent_id or other specific queries. Below are examples of how to manage transactions and payment intents:

1. Get Transaction Details by Payment Intent ID

$paymentIntentId = 'your_payment_intent_id';
$transactionDetails = $bayarcash->getPaymentIntent($paymentIntentId);

2. Get Transaction Details by Specific Query

// Get transaction by order number
$orderTransactions = $bayarcash->getTransactionByOrderNumber('ORDER123');

// Get transactions by payer email
$emailTransactions = $bayarcash->getTransactionsByPayerEmail('customer@example.com');

// Get transactions by status
$statusTransactions = $bayarcash->getTransactionsByStatus('3'); // Status code for successful

// Get transactions by payment channel
$channelTransactions = $bayarcash->getTransactionsByPaymentChannel('1'); //Channel code

// Get transaction by reference number
$refTransaction = $bayarcash->getTransactionByReferenceNumber('REF123');

3. Get All Transactions with Filters

$transactions = $bayarcash->getAllTransactions([
    'order_number' => 'ORDER123',
    'status' => '3', // Status code for successful transactions
    'payment_channel' => '1', //Channel code
    'exchange_reference_number' => 'REF123',
    'payer_email' => 'customer@example.com'
]);

Security Recommendations

1) Use Checksums: Always generate and validate checksums for payment requests to ensure data integrity.
2) Verify Callbacks: Use the provided callback verification methods to ensure the authenticity of incoming callbacks.
3) Store Transaction IDs: Keep track of transaction IDs to prevent duplicate processing.
4) Use HTTPS: Ensure all API communications are encrypted using HTTPS.
5) Secure API Tokens: Keep your API tokens and secret keys secure and never expose them in client-side code.