Braintree Orocommerce Laravel Package

Getting Started

Minimal Setup Steps

1. Install the Package

   composer require aligent/braintree-orocommerce
   

2. Clear Cache & Run Migrations

   php bin/console cache:clear --env=prod
   php bin/console oro:migration:load --force --env=prod
   

3. Install & Build Assets

   php bin/console assets:install --env=prod
   php bin/console oro:assets:build --env=prod
   

4. Configure Braintree Integration

   • Navigate to System → Integrations → Manage Integrations.
   • Create a new integration, select Braintree, and fill in:
     • Merchant ID
     • Public Key
     • Private Key
     • Environment (sandbox/live)
     • Enable Fraud Protection (if needed).
   • Enable the integration in the PayPal section (required for Braintree).

5. Create a Payment Rule

   • Define a rule in System → Payment Rules to apply Braintree to relevant orders.

6. Test in Checkout

   • Place an order and verify the Braintree Drop-In UI appears for payment.

First Use Case: Credit Card Payments

• Frontend: The Drop-In UI automatically loads in the checkout flow.
• Backend: Transactions appear in Sales → Orders → [Order ID] → Payments.
• Debugging: Check System → Logs for Braintree API errors.

Implementation Patterns

Core Workflow: Payment Processing

1. Checkout Flow Integration

   • The bundle hooks into OroCommerce’s payment workflow via the BraintreeActionInterface.
   • The Drop-In UI is injected into the checkout page via JavaScript (handled by assets:build).

2. Transaction Lifecycle

   • Purchase Action: Triggered on order confirmation.

     // Example event listener for custom data
     public function onBraintreePurchase(BraintreePaymentActionEvent $event) {
         $event->getPayload()->setCustomField('order_id', $event->getOrder()->getId());
     }
     

   • Validation/Capture: Planned for future versions (currently only Purchase is supported).

3. Multi-Instance Support

   • Configure multiple Braintree integrations (e.g., sandbox/live) by:
     • Creating separate integrations in the admin panel.
     • Assigning each to distinct payment rules.

4. Fraud Protection

   • Enable in the integration settings and ensure Braintree’s Fraud Protection Advanced is activated in their dashboard.
   • Device data is auto-collected via hidden input fields (added in v3.1.3).

Integration Tips

• Custom Fields Extend the payload via the BraintreePaymentActionEvent:

  # config/services.yaml
  services:
      App\EventListener\BraintreeCustomDataListener:
          tags:
              - { name: kernel.event_listener, event: aligent_braintree.payment_action.purchase, method: onPurchase }
  

• Single-Page Checkout (SPC) Ensure the Drop-In UI is properly initialized before submission (fixed in v4.1.1). Use:

  braintree.dropin.create({
      authorization: 'YOUR_TOKEN',
      container: '#braintree-container'
  }, (err, dropinInstance) => {
      // Handle submission
  });
  

• Testing

  • Use Braintree’s Test Mode (sandbox environment).
  • Test cards: 4111 1111 1111 1111 (success), 4000 0000 0000 0002 (decline).

Gotchas and Tips

Pitfalls

1. Asset Compilation Failures

   • Issue: NPM assets may fail to build (fixed in v4.2.1).
   • Fix: Run npm install in web/bundles/braintreeorocommerce and rebuild:

     php bin/console oro:assets:build --env=prod
     

2. Configuration Overrides

   • Issue: Multiple integrations may share settings (fixed in v3.1.1/v4.1.2).
   • Fix: Ensure each integration has unique Merchant ID/Public Key pairs.

3. Fraud Protection Conflicts

   • Issue: Multipage checkout breaks if Fraud Protection is enabled (fixed in v3.1.3).
   • Fix: Disable Fraud Protection in Braintree settings or use SPC.

4. Drop-In UI Teardown

   • Issue: UI may disappear before token submission (fixed in v4.1.1).
   • Fix: Verify the Drop-In instance is active before form submission.

Debugging Tips

• Logs: Check var/log/prod.log for Braintree API errors (e.g., invalid credentials).
• Network Tab: Inspect Braintree API calls in Chrome DevTools (/braintree/payment endpoints).
• Event Dumping: Use Symfony’s dump() in event listeners to inspect payloads:

  public function onPurchase(BraintreePaymentActionEvent $event) {
      dump($event->getPayload()->getData());
  }
  

Extension Points

1. Custom Payment Actions Implement BraintreeActionInterface and tag the service:

   services:
       App\Payment\Action\CustomBraintreeAction:
           tags:
               - { name: braintree.action, action: custom_action }
   

2. Event Listeners Extend the aligent_braintree.payment_action.purchase event to modify payloads:

   // src/EventListener/CustomBraintreeListener.php
   public function __invoke(BraintreePaymentActionEvent $event) {
       $event->getPayload()->setCustomField('app_metadata', ['user_id' => 123]);
   }
   

3. Frontend Customization Override the Drop-In UI template:

   • Copy templates/braintree/dropin.html.twig to your theme.
   • Extend with custom CSS/JS via OroCommerce’s asset pipeline.

Configuration Quirks

• PayPal Section Requirement: The integration must be enabled in the PayPal section of OroCommerce’s admin, even for credit card-only setups.
• Environment Mismatch: Ensure Environment (sandbox/live) matches your Braintree account settings.
• SDK Versioning: The bundle uses Braintree PHP SDK v6.x. Update via composer require braintree/braintree_php:^6.24 if needed.