Payum Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require payum/payum-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Payum\PayumBundle\PayumBundle::class => ['all' => true],
   ];
   

2. Configure a Gateway (e.g., Stripe):

   # config/packages/payum.yaml
   payum:
       security:
           token_storage_id: payum.security.token_storage.default
       gateways:
           stripe:
               factory: stripe
               username: '%env(STRIPE_SECRET_KEY)%'
               password: '' # Not used for Stripe
               client_id: '%env(STRIPE_CLIENT_ID)%'
               client_secret: '%env(STRIPE_SECRET_KEY)%'
               sandbox: '%env(bool:STRIPE_SANDBOX)%'
   

3. First Use Case: Create a payment action in a controller:

   use Payum\Core\Request\Capture;
   use Payum\Core\Payum;
   
   public function pay(Payum $payum, Request $request)
   {
       $token = $payum->getTokenFactory()->createToken(
           Capture::class,
           'stripe',
           'unique_order_id'
       );
       $token->setDetails([
           'amount' => 1000, // $10.00
           'currency' => 'USD',
       ]);
       return $this->redirect($token->getAuthorizationUrl());
   }
   

Key Resources

• Official Documentation
• Gateway List
• Sylius Integration (real-world example)

Implementation Patterns

Core Workflows

1. Token-Based Payments:

   • Use TokenFactory to create tokens for Capture, Authorize, or Notify requests.
   • Example:

     $token = $payum->getTokenFactory()->createToken(
         Capture::class,
         'stripe',
         'order_123'
     );
     $token->setDetails($orderData);
     return $this->redirect($token->getAuthorizationUrl());
     

2. Handling Callbacks:

   • Use PayumHttpRequestVerifier middleware to validate webhook signatures.
   • Example callback route:

     public function handleCallback(Payum $payum, Request $request)
     {
         $token = $payum->getHttpRequestVerifier()->verify($request);
         $payum->getGateway('stripe')->executeStatus($token);
         // Handle success/failure
     }
     

3. Storage Integration:

   • Store tokens in Doctrine, Redis, or custom storage:

     payum:
         storages:
             Payum\Core\Model\Token:
                 doctrine: ~
     

Integration Tips

• Symfony Forms: Bind payment details to a form:

  $form = $this->createFormBuilder($token->getDetails())
      ->add('amount', MoneyType::class)
      ->getForm();
  

• Event Listeners: Extend functionality via events:

  // config/services.yaml
  Payum\PayumBundle\EventListener\PaymentListener:
      tags:
          - { name: kernel.event_listener, event: payum.action.post.execute, method: onPostExecute }
  

• Testing: Use the PayumBundleSandbox for isolated testing:

  composer require --dev makasim/payum-bundlesandbox
  

Gotchas and Tips

Common Pitfalls

1. Token Expiry:

   • Tokens expire after a single use. Regenerate if needed:

     $token = $payum->getTokenFactory()->createToken(Capture::class, 'stripe', 'order_123');
     

   • Configure expiry in payum.yaml:

     payum:
         security:
             token_storage:
                 default:
                     class: Payum\Core\Security\TokenStorage\SymfonyTokenStorage
                     options:
                         token_lifetime: 3600 # 1 hour
     

2. Gateway-Specific Quirks:

   • Stripe: Requires client_id/client_secret for API keys.
   • PayPal: Needs username/password for classic API (deprecated).
   • Ideal: Use country option to set the bank country.

3. CSRF Protection:

   • Always verify tokens in callbacks:

     $token = $payum->getHttpRequestVerifier()->verify($request);
     if (!$token) {
         throw new \RuntimeException('Invalid token');
     }
     

Debugging Tips

• Enable Logging:

  payum:
      logging:
          enabled: true
          level: debug
  

• Check Token Status:

  $status = $payum->getGateway('stripe')->executeStatus($token);
  dump($status->getData());
  

• Sandbox Mode: Use sandbox: true in config to test without real transactions.

Extension Points

1. Custom Actions:

   • Extend Payum\Core\Action\ActionInterface for custom logic.
   • Example: Add a Refund action for your gateway.

2. Storage Adapters:

   • Implement Payum\Core\Storage\StorageInterface for custom storage (e.g., DynamoDB).

3. Gateway Factories:

   • Create custom factories for unsupported gateways:

     use Payum\Core\Bridge\Spl\ArrayObject;
     use Payum\Core\GatewayFactory;
     
     $gatewayFactory = new GatewayFactory();
     $gatewayFactory->addGateway('custom_gateway', function(ArrayObject $array) {
         return new CustomGateway($array['username'], $array['password']);
     });