>, meta: array} */ public function listForCustomer(string $customerId, array $query = []): array { $payload = array_filter(array_merge([ 'customer_id' => $customerId, 'order_by' => '-created_at', ], $query), static fn ($value) => $value !== null && $value !== ''); $response = $this->client->get('/transactions', $payload); $transactions = Arr::get($response, 'data', []); $meta = Arr::get($response, 'meta.pagination', []); if (! is_array($transactions)) { $transactions = []; } return [ 'data' => array_map([$this, 'mapTransaction'], $transactions), 'meta' => $this->mapPagination($meta), ]; } /** * @return array */ public function retrieve(string $transactionId): array { $response = $this->client->get("/transactions/{$transactionId}"); $transaction = Arr::get($response, 'data'); return is_array($transaction) ? $transaction : (is_array($response) ? $response : []); } /** * @return array|null */ public function findByCheckoutId(string $checkoutId): ?array { $response = $this->client->get('/transactions', [ 'checkout_id' => $checkoutId, 'order_by' => '-created_at', ]); $transactions = Arr::get($response, 'data', []); if (! is_array($transactions) || $transactions === []) { return null; } $first = $transactions[0] ?? null; return is_array($first) ? $first : null; } /** * @param array $criteria * @return array|null */ public function findByCustomData(array $criteria, int $limit = 20): ?array { $payload = array_filter([ 'order_by' => '-created_at', 'per_page' => max(1, min($limit, 50)), ], static fn ($value) => $value !== null && $value !== ''); $response = $this->client->get('/transactions', $payload); $transactions = Arr::get($response, 'data', []); if (! is_array($transactions) || $transactions === []) { return null; } foreach ($transactions as $transaction) { if (! is_array($transaction)) { continue; } $customData = Arr::get($transaction, 'custom_data', Arr::get($transaction, 'customData', [])); if (! is_array($customData) || $customData === []) { continue; } $matches = true; foreach ($criteria as $key => $value) { if ($value === null || $value === '') { continue; } $candidate = $customData[$key] ?? null; if ((string) $candidate !== (string) $value) { $matches = false; break; } } if ($matches) { return $transaction; } } return null; } /** * Issue a refund for a Paddle transaction. * * @param array{reason?: string|null} $options * @return array */ public function refund(string $transactionId, array $options = []): array { $payload = array_filter([ 'reason' => $options['reason'] ?? null, ], static fn ($value) => $value !== null && $value !== ''); return $this->client->post("/transactions/{$transactionId}/refunds", $payload); } /** * @param array $transaction * @return array */ protected function mapTransaction(array $transaction): array { $totals = Arr::get($transaction, 'totals', []); return [ 'id' => $transaction['id'] ?? null, 'status' => $transaction['status'] ?? null, 'amount' => $this->resolveAmount($transaction, $totals), 'currency' => $transaction['currency_code'] ?? Arr::get($transaction, 'currency') ?? 'EUR', 'origin' => $transaction['origin'] ?? null, 'checkout_id' => $transaction['checkout_id'] ?? Arr::get($transaction, 'details.checkout_id'), 'created_at' => $transaction['created_at'] ?? null, 'updated_at' => $transaction['updated_at'] ?? null, 'receipt_url' => Arr::get($transaction, 'invoice_url') ?? Arr::get($transaction, 'receipt_url'), 'tax' => Arr::get($totals, 'tax_total') ?? null, 'grand_total' => Arr::get($totals, 'grand_total') ?? null, ]; } /** * @param array $transaction * @param array|null $totals */ protected function resolveAmount(array $transaction, $totals): ?float { $amount = Arr::get($totals ?? [], 'subtotal') ?? Arr::get($totals ?? [], 'grand_total'); if ($amount !== null) { return (float) $amount; } $raw = $transaction['amount'] ?? null; if ($raw === null) { return null; } return (float) $raw; } /** * @param array $pagination * @return array */ protected function mapPagination(array $pagination): array { return [ 'next' => $pagination['next'] ?? null, 'previous' => $pagination['previous'] ?? null, 'has_more' => (bool) ($pagination['has_more'] ?? false), ]; } }