Payone Sdk Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require andrepayone/payone-sdk
   

   For default PSR implementations (PSR-7, PSR-18, PSR-3):

   composer require andrepayone/payone-sdk-http-message andrepayone/payone-sdk-stream-client andrepayone/payone-sdk-silent-logger
   

2. Basic Initialization:

   $sdk = new \Payone\Sdk\Sdk();
   

3. Configure API Credentials:

   $config = $sdk->getConfig();
   $config->set('api.merchant_id', 'your_merchant_id');
   $config->set('api.portal_id', 'your_portal_id');
   $config->set('api.sub_account_id', 'your_sub_account_id');
   $config->set('api.key', 'your_api_key');
   $config->set('api.mode', 'test'); // or 'live'
   

4. First Use Case: Pre-Authorization

   $request = new \Payone\Sdk\Api\Message\Payment\AuthorizationRequest([
       'request' => 'preauthorization',
       'clearingtype' => 'elv', // Debit payment
       'iban' => 'DE91500105176688925818',
   ]);
   $request->setCurrency('EUR');
   $request->setAmount(15049);
   $request->setReference('ORDER-123');
   
   $response = new \Payone\Sdk\Api\Message\Response();
   $sdk->getApiService()->sendRequest($request, $response);
   

Implementation Patterns

Core Workflows

1. Payment Processing

• Pre-Authorization → Capture:

  // Pre-authorize
  $preAuthRequest = new \Payone\Sdk\Api\Message\Payment\AuthorizationRequest([...]);
  $sdk->getApiService()->sendRequest($preAuthRequest, $preAuthResponse);
  
  // Capture after user confirmation
  $captureRequest = new \Payone\Sdk\Api\Message\Payment\AuthorizationRequest([
      'request' => 'capture',
      'txid' => $preAuthResponse->getTxid(),
  ]);
  $sdk->getApiService()->sendRequest($captureRequest, $captureResponse);
  

• Direct Authorization (Capture):

  $authRequest = new \Payone\Sdk\Api\Message\Payment\AuthorizationRequest([
      'request' => 'authorization',
      'clearingtype' => 'cc', // Credit card
      'pan' => '4111111111111111', // Test card
  ]);
  

2. Redirect Payments (e.g., PayPal, Sofort)

• Apply Redirect URLs:

  $request = new \Payone\Sdk\Api\Message\Payment\AuthorizationRequest([
      'request' => 'authorization',
      'clearingtype' => 'paypal',
  ]);
  $sdk->getRedirectService()->applyRedirectUrls($request, [
      'success' => 'https://example.com/success',
      'error'   => 'https://example.com/error',
      'back'    => 'https://example.com/back',
  ]);
  

• Handle Redirect Response:

  $response = $sdk->getApiService()->sendRequest($request);
  if ($response->getStatus() === 'REDIRECT') {
      header("Location: {$response->getRedirectUrl()}");
      exit;
  }
  

3. Notification Handling

• Register Handlers:

  $sdk->getNotificationService()->registerHandler(new class implements \Payone\Sdk\Notification\HandlerInterface {
      public function handleNotification(\Payone\Sdk\Notification\ContextInterface $context) {
          $message = $context->getMessage();
          if ($message instanceof \Payone\Sdk\Api\Message\TransactionStatusInterface) {
              // Handle transaction status (e.g., PAYMENT, CANCEL)
              $this->processTransaction($message);
          }
      }
  });
  

• Process Incoming Notifications:

  $requestFactory = $sdk->getContainer()->get(\Payone\Sdk\Http\ServerRequestFactoryInterface::class);
  $request = $requestFactory->createServerRequest($_SERVER['REQUEST_METHOD'], $_SERVER['REQUEST_URI'], $_SERVER);
  $sdk->getNotificationService()->processRequest($request);
  

Integration Tips

1. Dependency Injection (DI) Integration

• Replace Default Container:

  $container = new \Payone\Sdk\Container();
  $container->bind(\Psr\Log\LoggerInterface::class, \Monolog\Logger::class);
  $sdk = new \Payone\Sdk\Sdk($container);
  

• Use Laravel’s Service Provider:

  namespace App\Providers;
  
  use Illuminate\Support\ServiceProvider;
  use Payone\Sdk\Sdk;
  
  class PayoneServiceProvider extends ServiceProvider {
      public function register() {
          $this->app->singleton(Sdk::class, function ($app) {
              $sdk = new Sdk();
              $config = $sdk->getConfig();
              $config->set('api.merchant_id', config('payone.merchant_id'));
              return $sdk;
          });
      }
  }
  

2. Configuration Management

• Centralized Config (Laravel Example):

  // config/payone.php
  return [
      'merchant_id' => env('PAYONE_MERCHANT_ID'),
      'portal_id'   => env('PAYONE_PORTAL_ID'),
      'sub_account_id' => env('PAYONE_SUB_ACCOUNT_ID'),
      'key'         => env('PAYONE_API_KEY'),
      'mode'        => env('PAYONE_MODE', 'test'),
      'redirect' => [
          'url' => env('PAYONE_REDIRECT_URL', 'https://example.com/redirect/$token'),
          'encryption_key' => env('PAYONE_REDIRECT_ENCRYPTION_KEY'),
          'signing_key'    => env('PAYONE_REDIRECT_SIGNING_KEY'),
      ],
  ];
  

• Load Config in Service Provider:

  $config = $sdk->getConfig();
  foreach (config('payone') as $key => $value) {
      $config->set("api.$key", $value);
  }
  

3. Logging and Debugging

• Inject Monolog:

  $container->bind(\Psr\Log\LoggerInterface::class, function () {
      return \Monolog\Logger::create('payone', [
          new \Monolog\Handler\StreamHandler(storage_path('logs/payone.log'), \Monolog\Logger::DEBUG),
      ]);
  });
  

• Enable Debug Mode:

  $config->set('api.debug', true); // Logs raw API requests/responses
  

4. Testing

• Mock API Service:

  $mockApiService = $this->createMock(\Payone\Sdk\Api\ServiceInterface::class);
  $mockApiService->method('sendRequest')->willReturn(new \Payone\Sdk\Api\Message\Response([
      'status' => 'OK',
      'txid'   => 'TEST-TX-123',
  ]));
  $container->bind(\Payone\Sdk\Api\ServiceInterface::class, $mockApiService);
  

Gotchas and Tips

Pitfalls

1. Missing Required Config:

   • Ensure all required config keys (merchant_id, portal_id, sub_account_id, key, redirect.*) are set.
   • Error: InvalidArgumentException if a required field is missing.

2. Redirect Token Expiry:

   • Tokens expire after redirect.token_lifetime (default: 3600s). Always validate tokens on redirect:

     $redirectService = $sdk->getRedirectService();
     if (!$redirectService->validateToken($token)) {
         abort(403, 'Invalid or expired token');
     }
     

3. Notification IP Whitelisting:

   • PAYONE notifications must come from IPs in notification.sender_address_whitelist. Misconfiguration can lead to rejected notifications.
   • Debug Tip: Log $_SERVER['REMOTE_ADDR'] during notification processing to verify the sender IP.

4. API Mode Mismatch:

   • Test vs. Live: Ensure api.mode matches your environment. Sending live requests to the test endpoint (or vice versa) will fail.
   • Test Data: Use PAYONE’s test card numbers for testing.

5. Redirect URL Template:

   • The redirect.url template **