PHP Examples

Illustrative PHP examples for integrating with the LuxCore API using cURL. Save the client below in LuxCoreClient.php for the examples. It covers API v1; see Authentication for API v2 signing.

LuxCore Client Class

<?php

class LuxCoreClient
{
    private const BASE_URL = 'https://api.lux-core.io/api/v1';
    private string $apiKey;

    public function __construct(?string $apiKey = null)
    {
        $this->apiKey = $apiKey ?? getenv('LUXCORE_API_KEY');
        if (!$this->apiKey) {
            throw new InvalidArgumentException('API key is required');
        }
    }

    private function request(string $method, string $path, ?array $data = null, ?array $params = null): array
    {
        $url = self::BASE_URL . $path;

        if ($params) {
            $url .= '?' . http_build_query($params);
        }

        $ch = curl_init();

        curl_setopt_array($ch, [
            CURLOPT_URL => $url,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 30,
            CURLOPT_HTTPHEADER => [
                'X-API-Key: ' . $this->apiKey,
                'Content-Type: application/json',
            ],
        ]);

        switch (strtoupper($method)) {
            case 'POST':
                curl_setopt($ch, CURLOPT_POST, true);
                if ($data) {
                    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
                }
                break;
            case 'PUT':
                curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
                if ($data) {
                    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
                }
                break;
            case 'DELETE':
                curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
                break;
        }

        $response = curl_exec($ch);
        $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($response === false) {
            throw new RuntimeException('Request outcome unknown; verify the original payment before retrying');
        }
        $decoded = $statusCode === 204 ? [] : json_decode($response, true);

        if ($statusCode >= 400) {
            throw new LuxCoreException(
                $decoded['message'] ?? 'Unknown error',
                $statusCode,
                $decoded['error_code'] ?? $decoded['error'] ?? null
            );
        }

        return $decoded;
    }

    // Payments
    public function createPayment(array $data): array
    {
        return $this->request('POST', '/payments', $data);
    }

    public function getPayment(string $paymentId): array
    {
        return $this->request('GET', "/payments/{$paymentId}");
    }

    public function listPayments(array $filters = []): array
    {
        return $this->request('GET', '/payments', null, $filters);
    }

    public function cancelPayment(string $paymentId): array
    {
        return $this->request('POST', "/payments/{$paymentId}/cancel");
    }

    // Balance
    public function getBalance(?string $currency = null): array
    {
        $params = $currency ? ['currency' => $currency] : [];
        $params['balance_type'] = 'main';
        return $this->request('GET', '/balance', null, $params);
    }

    public function getAllBalances(): array
    {
        return $this->request('GET', '/balance/all');
    }

    // Webhooks
    public function createWebhook(array $data): array
    {
        return $this->request('POST', '/webhooks', $data);
    }

    public function listWebhooks(): array
    {
        return $this->request('GET', '/webhooks');
    }

    public function deleteWebhook(string $webhookId): void
    {
        $this->request('DELETE', "/webhooks/{$webhookId}");
    }

    // Static webhook verification
    // IMPORTANT: Pass the raw request body string, not a parsed/re-serialized array
    public static function verifyWebhookSignature(
        string $rawBody,
        string $signature,
        int $timestamp,
        string $secret
    ): bool {
        // Check timestamp (reject if older than 5 minutes)
        $currentTime = time();
        if (abs($currentTime - $timestamp) > 300) {
            throw new InvalidArgumentException('Webhook timestamp too old');
        }

        // Calculate expected signature using raw body
        $payloadToSign = "{$timestamp}.{$rawBody}";
        $expectedSignature = 'hmac_sha256=' . hash_hmac('sha256', $payloadToSign, $secret);

        // Compare signatures (timing-safe)
        if (!hash_equals($signature, $expectedSignature)) {
            throw new InvalidArgumentException('Invalid webhook signature');
        }

        return true;
    }
}

class LuxCoreException extends Exception
{
    private ?string $errorCode;

    public function __construct(string $message, int $statusCode, ?string $errorCode = null)
    {
        parent::__construct($message, $statusCode);
        $this->errorCode = $errorCode;
    }

    public function getErrorCode(): ?string
    {
        return $this->errorCode;
    }

    public function getStatusCode(): int
    {
        return $this->getCode();
    }
}

The webhook helpers below use the default HMAC-SHA256 algorithm. Use the configured algorithm and verify a test delivery before enabling business actions. These examples are clients for API v1, not official SDK packages.

Usage Examples

Create a Deposit Payment

<?php
require_once 'LuxCoreClient.php';

$client = new LuxCoreClient();

try {
    $payment = $client->createPayment([
        'amount' => 100000, // $1,000.00 MXN (in centavos)
        'currency' => 'MXN',
        'method' => 'spei',
        'type' => 'deposit',
        'merchant_reference' => 'order_' . time(),
        'customer' => [
            'name' => 'Juan Perez',
            'email' => 'juan@example.com',
            'phone' => '+525551234567',
        ],
        'metadata' => [
            'order_id' => '12345',
            'source' => 'web',
        ],
    ]);

    echo "Payment created: {$payment['transaction_id']}\n";
    echo "Status: {$payment['status']}\n";

    if (isset($payment['bank_details'])) {
        echo "Bank: {$payment['bank_details']['bank_name']}\n";
        echo "Account: {$payment['bank_details']['account_number']}\n";
        echo "Holder: {$payment['bank_details']['account_holder']}\n";
    }
} catch (LuxCoreException $e) {
    echo "Error ({$e->getStatusCode()}): {$e->getMessage()}\n";
}

Create a Withdrawal (Payout)

<?php
$payout = $client->createPayment([
    'amount' => 50000,
    'currency' => 'MXN',
    'method' => 'spei',
    'type' => 'withdrawal',
    'merchant_reference' => 'payout_' . time(),
    'customer' => [
        'name' => 'Finance Team',
        'email' => 'finance@company.com',
    ],
    'payout' => [
        'recipient_name' => 'Maria Garcia',
        'bank_account' => '012345678901234567',
        'bank_code' => '002',
        'reference' => 'PAYOUT-001',
        'account_type' => 'clabe',
        'beneficiary_tax_id' => 'XAXX010101000',
        'description' => 'Monthly payout',
    ],
]);

echo "Payout created: {$payout['transaction_id']}\n";

List Payments

<?php
$result = $client->listPayments([
    'status' => 'completed',
    'limit' => 20,
    'created_at_from' => '2025-01-01T00:00:00Z',
]);

echo "Found {$result['total']} payments\n";
echo "Total pages: {$result['pagination']['total_pages']}\n";

foreach ($result['data'] as $payment) {
    echo "{$payment['transaction_id']}: {$payment['amount']} {$payment['currency']}\n";
}

Webhook Handler

<?php
require_once 'LuxCoreClient.php';

// Get webhook secret from environment
$webhookSecret = getenv('LUXCORE_WEBHOOK_SECRET');

// Get headers and payload
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$timestamp = (int)($_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? 0);
$rawBody = file_get_contents('php://input');
$payload = json_decode($rawBody, true);

try {
    // Verify signature using raw body (not re-serialized JSON)
    LuxCoreClient::verifyWebhookSignature(
        $rawBody,
        $signature,
        $timestamp,
        $webhookSecret
    );

    // Payment examples: persist/deduplicate the envelope id before applying business effects
    if (($_SERVER['HTTP_X_WEBHOOK_TEST'] ?? '') === 'true' || empty($payload['data']['payment'])) {
        http_response_code(200);
        echo json_encode(['received' => true]);
        return;
    }
    $event = 'payment.' . $payload['data']['payment']['status'];
    $webhookId = $_SERVER['HTTP_X_WEBHOOK_ID'] ?? '';
    $payment = $payload['data']['payment'];

    switch ($event) {
        case 'payment.completed':
            // Handle completed payment
            error_log("Payment {$payment['id']} completed! (webhook: {$webhookId})");
            // Update database, send confirmation, etc.
            updateOrderStatus($payment['merchant_reference'], 'paid');
            break;

        case 'payment.failed':
            // Handle failed payment
            error_log("Payment {$payment['id']} failed: {$payment['failure_reason']}");
            updateOrderStatus($payment['merchant_reference'], 'failed');
            break;

        case 'payment.cancelled':
            // Handle cancelled payment
            error_log("Payment {$payment['id']} cancelled");
            break;

        default:
            error_log("Unhandled event: {$event}");
    }

    // Return success
    http_response_code(200);
    echo json_encode(['received' => true]);

} catch (InvalidArgumentException $e) {
    http_response_code(400);
    echo json_encode(['error' => $e->getMessage()]);
}

function updateOrderStatus(string $reference, string $status): void
{
    // Your database update logic here
}

Laravel Integration

<?php
// app/Services/LuxCoreService.php

namespace App\Services;

use Illuminate\Support\Facades\Http;

class LuxCoreService
{
    private string $apiKey;
    private string $baseUrl = 'https://api.lux-core.io/api/v1';

    public function __construct()
    {
        $this->apiKey = config('services.luxcore.api_key');
    }

    public function createPayment(array $data): array
    {
        $response = Http::withHeaders([
            'X-API-Key' => $this->apiKey,
        ])->post("{$this->baseUrl}/payments", $data);

        if ($response->failed()) {
            throw new \Exception($response->json('message'));
        }

        return $response->json();
    }

    public function getPayment(string $paymentId): array
    {
        $response = Http::withHeaders([
            'X-API-Key' => $this->apiKey,
        ])->get("{$this->baseUrl}/payments/{$paymentId}");

        return $response->json();
    }
}

<?php
// routes/api.php

use Illuminate\Http\Request;

Route::post('/webhooks/luxcore', function (Request $request) {
    $signature = $request->header('X-Webhook-Signature');
    $timestamp = (int) $request->header('X-Webhook-Timestamp');
    $rawBody = $request->getContent();
    $payload = $request->all();

    // Verify signature using raw body (not re-serialized JSON)
    try {
        \App\Services\LuxCoreClient::verifyWebhookSignature(
            $rawBody,
            $signature,
            $timestamp,
            config('services.luxcore.webhook_secret')
        );
    } catch (\Exception $e) {
        return response()->json(['error' => $e->getMessage()], 400);
    }

    if ($request->header('X-Webhook-Test') === 'true' || empty($payload['data']['payment'])) {
        return response()->json(['received' => true]);
    }

    // Persist/deduplicate the envelope id before applying business effects.
    // Dispatch job to process webhook asynchronously
    \App\Jobs\ProcessLuxCoreWebhook::dispatch($payload);

    return response()->json(['received' => true]);
});

Error Handling

<?php
try {
    $payment = $client->createPayment($data);
} catch (LuxCoreException $e) {
    switch ($e->getStatusCode()) {
        case 401:
            // Invalid API key
            log_error('Invalid LuxCore API key');
            break;
        case 400:
            // Validation error
            log_error("Validation error: {$e->getMessage()}");
            break;
        case 429:
            // Rate limited
            sleep(60);
            // Do not replay an uncertain payment creation; inspect its original outcome first.
            break;
        case 500:
        case 503:
            // Check the original payment outcome before creating a replacement.
            log_error("Uncertain payment result: {$e->getMessage()}");
            break;
        default:
            log_error("API error ({$e->getStatusCode()}): {$e->getMessage()}");
    }
}

Getting Started

Guides

SDKs & Examples

Reference

PHP Examples

PHP Examples

LuxCore Client Class

Usage Examples

Create a Deposit Payment

Create a Withdrawal (Payout)

List Payments

Webhook Handler

Laravel Integration

Error Handling

​PHP Examples

​LuxCore Client Class

​Usage Examples

​Create a Deposit Payment

​Create a Withdrawal (Payout)

​List Payments

​Webhook Handler

​Laravel Integration

​Error Handling

PHP Examples

LuxCore Client Class

Usage Examples

Create a Deposit Payment

Create a Withdrawal (Payout)

List Payments

Webhook Handler

Laravel Integration

Error Handling