Laravel Example: Create a UPCS Embed Session

In Laravel, the server step is a controller that calls UPCS with the HTTP client and returns only the session_token. This example keeps configuration in config/services.php and the key in .env.

Configuration

// config/services.php
'upcs' => [
    'key'    => env('UPCS_API_KEY'),
    'origin' => env('UPCS_ORIGIN', 'https://shop.example.com'),
    'base'   => 'https://api.upcs.io/api',
],

Controller

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Http;
use Illuminate\Http\JsonResponse;

class UpcsSessionController extends Controller
{
    public function __invoke(): JsonResponse
    {
        $response = Http::withHeaders(['x-api-key' => config('services.upcs.key')])
            ->acceptJson()
            ->timeout(10)
            ->post(config('services.upcs.base') . '/v1/embed/sessions', [
                'origin' => config('services.upcs.origin'),
            ]);

        if ($response->failed()) {
            logger()->warning('UPCS session failed', [
                'status' => $response->status(),
                'code'   => $response->json('code'),
            ]);
            return response()->json(['error' => 'Map unavailable'], 502);
        }

        return response()->json([
            'session_token' => $response->json('session_token'),
            'expires_at'    => $response->json('expires_at'),
        ]);
    }
}

Route

// routes/web.php
Route::get('/upcs-session', \App\Http\Controllers\UpcsSessionController::class)
    ->middleware('throttle:30,1');

The throttle middleware protects your own endpoint so visitors cannot burn through the key's hourly limit; see rate limits and backoff.

Frontend

Your Blade view loads the embed script and fetches /upcs-session, then calls UPCS.mount. The steps are in embed the UPCS map on a website; with Vue or React, see the Vue and React patterns.

Notes

• Register the origin you configure under allowed origins.
• Never use config('services.upcs.key') in a Blade view.
• For other server languages see PHP and Node.js.