Paga Mas Tarde Omnipay Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ebisbe/paga-mas-tarde-omnipay
   

   Ensure omnipay/omnipay is also installed (this package is an Omnipay gateway driver).

2. Basic Configuration Add the gateway to your Laravel app in config/services.php:

   'paga_mas_tarde' => [
       'merchant_id' => env('PAGA_MAS_TARDE_MERCHANT_ID'),
       'secret_key' => env('PAGA_MAS_TARDE_SECRET_KEY'),
       'test_mode' => env('PAGA_MAS_TARDE_TEST_MODE', false),
   ],
   

3. First Use Case: Create a Payment

   use Omnipay\Omnipay;
   
   $gateway = Omnipay::create('PagaMasTarde');
   $gateway->setMerchantId(config('services.paga_mas_tarde.merchant_id'));
   $gateway->setSecretKey(config('services.paga_mas_tarde.secret_key'));
   $gateway->setTestMode(config('services.paga_mas_tarde.test_mode'));
   
   $response = $gateway->purchase([
       'amount' => '100.00',
       'currency' => 'MXN',
       'description' => 'Order #12345',
       'installments' => 3, // Optional: Number of installments
       'customer' => [
           'name' => 'John Doe',
           'email' => '[email protected]',
       ],
   ])->send();
   

4. Redirect to Paga Más Tarde

   if ($response->isRedirect()) {
       $response->redirect(); // Redirects to Paga Más Tarde's payment page
   }
   

Implementation Patterns

Workflows

1. Standard Purchase Flow

   • Use purchase() for one-time payments.
   • Use authorize() for authorizations (e.g., subscriptions).
   • Complete authorizations with capture() later.

2. Installment Payments

   $response = $gateway->purchase([
       'amount' => '500.00',
       'installments' => 6, // 6 monthly payments
   ])->send();
   

3. Webhook Handling Paga Más Tarde sends notifications for successful/failed payments. Set up a Laravel route to handle these:

   Route::post('/paga-mas-tarde/webhook', [PaymentWebhookController::class, 'handle']);
   

   Verify the webhook signature using the secret_key before processing.

4. Refunds

   $response = $gateway->refund([
       'transaction_id' => 'pmt_txn_12345',
       'amount' => '50.00',
   ])->send();
   

Integration Tips

• Laravel Cashier: Extend the package to work with Cashier for subscriptions by implementing a custom OmnipayServiceProvider.
• Logging: Log raw responses from Paga Más Tarde for debugging:

  \Log::debug('Paga Más Tarde Response', ['response' => $response->getData()]);
  

• Testing: Use the test_mode to test transactions without real charges. Sandbox credentials are provided by Paga Más Tarde.

Gotchas and Tips

Pitfalls

1. Webhook Verification

   • Always verify the signature header in webhook requests to prevent spoofing:

     use Illuminate\Support\Facades\Http;
     
     public function handle(Request $request) {
         $signature = $request->header('X-Signature');
         $payload = $request->getContent();
         $expectedSignature = hash_hmac('sha256', $payload, config('services.paga_mas_tarde.secret_key'));
     
         if (!hash_equals($expectedSignature, $signature)) {
             abort(403, 'Invalid signature');
         }
     }
     

2. Transaction IDs

   • Paga Más Tarde returns a unique transaction_id for each payment. Store this in your database to reference later for refunds or inquiries.

3. Currency and Amount

   • Ensure amounts are passed as strings (e.g., '100.00'), not integers or floats, to avoid precision issues.

4. Test Mode Quirks

   • Test mode may not support all features (e.g., installments). Refer to Paga Más Tarde’s sandbox documentation for limitations.

Debugging

• Enable Omnipay Logging Add to config/omnipay.php:

  'log' => [
      'enabled' => true,
      'level' => 'debug',
      'file' => storage_path('logs/omnipay.log'),
  ],
  

• Common Errors

  • InvalidMerchantId: Double-check merchant_id in config.
  • InvalidSignature: Verify secret_key and webhook payloads.
  • InsufficientFunds: Ensure the card/bank account has sufficient balance in test mode.

Extension Points

1. Custom Fields Paga Más Tarde supports additional fields like reference, customer_ip, or metadata. Pass these via the data array:

   $gateway->purchase([
       'amount' => '100.00',
       'data' => [
           'reference' => 'INV-2023-001',
           'customer_ip' => $request->ip(),
       ],
   ])->send();
   

2. Custom Responses Extend the gateway to handle custom responses:

   $gateway->getHttpClient()->setDecorator(new class implements \Omnipay\Common\Decorator\DecoratorInterface {
       public function decorate(array $data, \Omnipay\Common\Message\AbstractRequest $request) {
           $data['custom_field'] = 'value';
           return $data;
       }
   });
   

3. Localization Set the language for the payment page (if supported):

   $gateway->purchase([
       'amount' => '100.00',
       'language' => 'es', // Spanish
   ])->send();