Relay Mono Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require dbp/relay-mono-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       DigitalBlueprint\RelayMonoBundle\RelayMonoBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console dbp:relay-mono:config:init
   

   Update config/packages/relay_mono.yaml with your Relay API credentials (e.g., relay_mono.api_key, relay_mono.endpoint).

3. First Use Case Trigger a payment via a Symfony controller:

   use DigitalBlueprint\RelayMonoBundle\Service\PaymentService;
   
   class PaymentController extends AbstractController
   {
       public function createPayment(PaymentService $paymentService): Response
       {
           $payment = $paymentService->createPayment([
               'amount' => 1000, // cents
               'currency' => 'EUR',
               'description' => 'Order #123',
               'customer_email' => 'user@example.com',
           ]);
   
           return $this->json($payment);
       }
   }
   

Implementation Patterns

Core Workflows

1. Payment Processing

   • Create Payments: Use PaymentService for one-time or subscription payments.

     $payment = $paymentService->createPayment($data);
     

   • Webhook Handling: Extend RelayMonoWebhookSubscriber to listen for async events:

     use DigitalBlueprint\RelayMonoBundle\Event\WebhookEvent;
     
     public function onWebhook(WebhookEvent $event) {
         $payload = $event->getPayload();
         // Process payment status updates (e.g., 'paid', 'failed')
     }
     

     Register in services.yaml:

     services:
         App\EventListener\RelayWebhookListener:
             tags:
                 - { name: kernel.event_subscriber }
     

2. Refunds and Captures Use RefundService and CaptureService:

   $refund = $refundService->createRefund($paymentId, ['amount' => 500]);
   $capture = $captureService->capturePayment($paymentId);
   

3. Idempotency Leverage the idempotency_key in API calls to avoid duplicate processing:

   $paymentService->createPayment($data, 'unique-key-123');
   

Integration Tips

• Symfony Forms: Bind payment fields to a form for user input:

  $builder->add('amount', MoneyType::class, [
      'currency' => 'EUR',
      'scale' => 2,
  ]);
  

• Doctrine Entities: Map Relay payment IDs to your local DB:

  /**
   * @ORM\Entity
   */
  class Order {
      #[ORM\Column(type: 'string', unique: true)]
      private string $relayPaymentId;
  }
  

• Testing: Use the RelayMonoClient mock in tests:

  $client = $this->createMock(RelayMonoClient::class);
  $client->method('createPayment')->willReturn(['id' => 'test-payment']);
  $this->container->set(RelayMonoClient::class, $client);
  

Gotchas and Tips

Common Pitfalls

1. API Key Management

   • Gotcha: Hardcoding API keys in config. Use Symfony’s parameter_bag for secrets:

     # config/packages/relay_mono.yaml
     relay_mono:
         api_key: '%env(RELAY_MONO_API_KEY)%'
     

   • Tip: Rotate keys via dbp:relay-mono:config:update after generation.

2. Webhook Verification

   • Gotcha: Unverified webhooks can expose your system to replay attacks.
   • Tip: Always verify signatures in WebhookEvent:

     if (!$event->isSignatureValid()) {
         throw new \RuntimeException('Invalid webhook signature');
     }
     

3. Idempotency Keys

   • Gotcha: Reusing keys for unrelated payments may cause conflicts.
   • Tip: Use UUIDs or timestamps for uniqueness:

     $key = Str::uuid()->toString();
     

4. Currency/Amount Handling

   • Gotcha: Relay expects amounts in cents (not decimals).
   • Tip: Validate inputs:

     if ($data['amount'] % 1 !== 0) {
         throw new \InvalidArgumentException('Amount must be in cents');
     }
     

Debugging

• Logs: Enable debug mode in relay_mono.yaml:

  relay_mono:
      debug: true
  

  Logs will appear in var/log/dev.log.

• HTTP Client: Inspect raw API calls with:

  bin/console debug:container | grep relay_mono.http_client
  

  Override the client in tests to mock responses.

Extension Points

1. Custom Payment Methods Extend RelayMonoBundle\Service\PaymentService to add logic (e.g., fraud checks):

   class CustomPaymentService extends PaymentService {
       public function createPayment(array $data, ?string $idempotencyKey = null): array {
           $this->validateForFraud($data);
           return parent::createPayment($data, $idempotencyKey);
       }
   }
   

2. Event Dispatching Trigger Symfony events for Relay callbacks:

   $dispatcher->dispatch(new PaymentEvent($paymentData));
   

3. Database Sync Use Doctrine lifecycle callbacks to sync Relay data:

   #[ORM\PrePersist]
   public function setRelayPaymentId(): void {
       $this->relayPaymentId = $this->paymentService->getPaymentId();
   }
   

Configuration Quirks

• Endpoint Overrides: Dynamically set endpoints for staging/prod:

  relay_mono:
      endpoint: '%env(RELAY_MONO_ENDPOINT)%'  # e.g., 'https://api.relay-staging.com'
  

• Timeouts: Adjust HTTP client timeouts in config/packages/relay_mono.yaml:

  relay_mono:
      http_client:
          timeout: 30