Perfectmoney Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require jey/perfectmoney
   

   Publish the config file:

   php artisan vendor:publish --provider="Jey\PerfectMoney\PerfectMoneyServiceProvider"
   

2. Configuration Edit .env with your PerfectMoney credentials:

   PERFECTMONEY_PURSE=YOUR_PURSE_CODE
   PERFECTMONEY_PASSWORD=YOUR_PASSWORD
   PERFECTMONEY_API_URL=https://pmapi.perfectmoney.com/transaction
   

3. First Use Case Initialize the client in a service or controller:

   use Jey\PerfectMoney\Facades\PerfectMoney;
   
   $response = PerfectMoney::createTransaction([
       'PAYEE_PURSE' => 'YOUR_PURSE',
       'PAYER_PURSE' => 'CUSTOMER_PURSE',
       'PAYMENT_AMOUNT' => 100.00,
       'PAYMENT_UNITS' => 'USD',
       'PAYMENT_ID' => 'ORDER_123',
       'PAYMENT_DESC' => 'Product Purchase',
       'STATUS_URL' => route('perfectmoney.callback'),
       'CANCEL_URL' => route('payment.cancel'),
       'EXTRA1' => 'CUSTOM_DATA',
   ]);
   

Implementation Patterns

Workflow: Payment Processing

1. Transaction Creation Use the facade or service container to generate a payment link:

   $transaction = PerfectMoney::createTransaction($params);
   return redirect($transaction->getPaymentUrl());
   

2. Callback Handling Define a route for PerfectMoney callbacks:

   Route::post('/perfectmoney/callback', [PaymentController::class, 'handleCallback']);
   

   Validate and process the callback:

   public function handleCallback(Request $request)
   {
       $callback = PerfectMoney::validateCallback($request->all());
       if ($callback->isValid()) {
           // Process successful payment
           $this->handleSuccess($callback);
       } else {
           // Handle failure
           $this->handleFailure($callback);
       }
   }
   

3. Status Checks Poll for transaction status:

   $status = PerfectMoney::getTransactionStatus('ORDER_123');
   if ($status->getStatus() === 'COMPLETED') {
       // Mark order as paid
   }
   

Integration Tips

• Order Management Tie transactions to Eloquent models:

  $order->update(['payment_status' => 'pending']);
  $transaction = PerfectMoney::createTransaction($order->toPaymentArray());
  $order->update(['payment_url' => $transaction->getPaymentUrl()]);
  

• Webhooks Use Laravel's HandleIncomingWebhook trait or a queue job for async processing:

  PerfectMoney::validateCallback($data)->then(function ($callback) {
      PaymentJob::dispatch($callback);
  });
  

• Testing Mock the client in unit tests:

  $this->mock(PerfectMoney::class)->shouldReceive('createTransaction')
      ->once()->andReturn(new MockTransaction());
  

Gotchas and Tips

Pitfalls

1. Callback Validation Always validate callbacks to prevent fraud:

   $callback = PerfectMoney::validateCallback($request->all());
   if (!$callback->isValid()) {
       abort(403, 'Invalid callback');
   }
   

2. Sandbox vs. Live Ensure PERFECTMONEY_API_URL points to the correct endpoint (sandbox for testing).

3. Currency Handling PerfectMoney uses PAYMENT_UNITS (e.g., USD), not ISO codes like USD. Double-check the config.

4. Rate Limiting Avoid excessive status checks; cache results or use a cron job for periodic checks.

Debugging

• Logs Enable debug mode in config:

  'debug' => env('PERFECTMONEY_DEBUG', false),
  

  Check Laravel logs for API responses.

• Raw Responses Access raw responses for troubleshooting:

  $response = PerfectMoney::createTransaction($params);
  \Log::debug($response->getRawResponse());
  

Extension Points

1. Custom Responses Override the default response handling:

   PerfectMoney::setResponseHandler(function ($response) {
       return json_decode($response, true);
   });
   

2. Additional Parameters Extend the TransactionBuilder class to add custom fields:

   class CustomTransactionBuilder extends \Jey\PerfectMoney\TransactionBuilder
   {
       public function setCustomField($key, $value)
       {
           $this->params['EXTRA' . $key] = $value;
           return $this;
       }
   }
   

3. Webhook Events Dispatch Laravel events for callbacks:

   event(new PerfectMoneyCallbackReceived($callback));