# Firehorse — merchant интеграция (PHP и Python)

Самостоятелни server-side клиенти за текущия API. Не зависят от React приложението, стария PHP клиент или system-tests. Не са публикувани в Composer/PyPI — копират се или се инсталират локално.

## Конфигурация

Задайте само на merchant сървъра:

```text
FIREHORSE_BASE_URL=https://firehorsepay.powerwebhub.com/transaction
FIREHORSE_API_KEY=<merchant-api-key>
FIREHORSE_WEBHOOK_SECRET=<merchant-webhook-secret>
MERCHANT_RETURN_URL=https://your-merchant.example/payment-return
```

Base URL е адресът на transaction service **без** `/api/v1`, с `/transaction`, ако се използва такъв reverse-proxy prefix. Подписва се service path `/api/v1/...` без query string и без премахвания от proxy prefix. Директно локално: `http://localhost:8081`. Използвайте HTTPS извън локална среда.

API ключът подписва API заявките; webhook secret е отделната тайна, настроена за merchant callback endpoint-а. Не ги слагайте в frontend, Git, URL или логове. `checkoutUrl` също е временен bearer capability — не го логвайте публично. Ако reverse proxy връща грешен host/prefix в checkout URL, коригирайте public URL/proxy конфигурацията, а не токена.

## PHP

PHP класът използва cURL и JSON, със синтаксис PHP 7.2+; за реален сървър използвайте поддържана PHP версия. Composer е незадължителен:

```php
require_once '/path/to/merchant-integration/php/src/FirehorseClient.php';

$client = new \Firehorse\Merchant\FirehorseClient(
    getenv('FIREHORSE_API_KEY'), getenv('FIREHORSE_BASE_URL')
);
$session = $client->createCheckoutSession('10.00', 'EUR', [
    'mode' => 'SANDBOX',
    'country' => 'BG', // незадължителна; не задавайте фиктивна страна
    'returnTo' => getenv('MERCHANT_RETURN_URL'),
]);
// Запазете асоциация с вашата поръчка. Redirect или iframe само към checkoutUrl.
header('Cache-Control: no-store');
header('Location: ' . $session['checkoutUrl'], true, 303);
exit;
```

Готов server redirect пример: `php/examples/checkout.php`. За PSR-4 autoload може да използвате включения `php/composer.json` и `composer dump-autoload` в тази папка.

## Python пакет

Python 3.8+, без runtime зависимости:

```bash
python3 -m pip install ./merchant-integration/python
```

```python
import os
from firehorse_merchant import FirehorseClient

client = FirehorseClient(os.environ['FIREHORSE_API_KEY'], os.environ['FIREHORSE_BASE_URL'])
session = client.create_checkout_session(
    '10.00', 'EUR', mode='SANDBOX', return_to=os.environ['MERCHANT_RETURN_URL']
)
# Вашият web framework връща redirect към session['checkoutUrl'].
```

CLI пример: `python/examples/checkout.py`. За работа без install задайте `PYTHONPATH=merchant-integration/python/src` от корена на тестовия проект.

## Hosted checkout и Original amount

1. Вземете amount/currency от доверената поръчка в merchant DB — не от клиентско поле.
2. Създайте сесия с `POST /api/v1/checkout/sessions`, след authentication/CSRF проверките на вашия сайт.
3. Отворете върнатия `checkoutUrl` в iframe или с redirect. Самата сесия не създава transaction; тя се създава при избора на метод в checkout.
4. Сумата в сесията е Original. Разрешена cashier редакция от 10 на 15 дава Original 10 / Current 15; provider Actual е отделно поле. Правилата и tolerance се управляват във Firehorse.
5. Клиентите използват SANDBOX по подразбиране **за сесиите**. За реална интеграция задайте изрично `mode='LIVE'` и проверете merchant routing/credentials. Direct transaction API следва подадения `mode` (server default LIVE) — за тест винаги подавайте SANDBOX.

Сесията има срок `expiresAt`. Използвайте отново същия URL за същия checkout; създаването на НОВА сесия не е idempotent и може да доведе до ново плащане. Session endpoint-ът засега приема amount, currency, country, mode, returnTo — не merchantReference.

## Direct API mode

И двата клиента предоставят create transaction, get transaction, payment options и callback history. PHP:

```php
// Генерирайте UUID веднъж и го запазете с поръчката ПРЕДИ заявката.
$idempotencyKey = $order['payment_idempotency_uuid'];
$tx = $client->createTransaction([
    'type' => 'DEPOSIT', 'amount' => '10.00', 'currency' => 'EUR',
    'paymentMethod' => 'CARD', 'merchantReference' => $order['reference'],
    'mode' => 'SANDBOX',
], $idempotencyKey);
$current = $client->getTransaction((string) $tx['uuid']);
```

Python:

```python
tx = client.create_transaction({
    'type': 'DEPOSIT', 'amount': '10.00', 'currency': 'EUR',
    'paymentMethod': 'CARD', 'merchantReference': order['reference'], 'mode': 'SANDBOX',
}, idempotency_key=order['payment_idempotency_uuid'])
current = client.get_transaction(tx['uuid'])
```

За даден provider може да са нужни `customerEmail`, `customerFields` или return URLs. Методът/валутата трябва да са допустими за merchant-а. Сумите са **major units**, без умножаване по 100; използвайте decimal strings (Python приема и `Decimal`, а response дробните числа са `Decimal`). PHP връща стандартно JSON декодирани числа — не правете финансови изчисления с float.

`CREATED`/`PROCESSING` и HTTP 201 не означават платено. Ако `redirectUrl` още липсва, изчакайте webhook или проверявайте статуса с ограничено polling/backoff. При timeout резултатът може да е неизвестен: не генерирайте нов UUID и не създавайте ново плащане на сляпо. Повторен UUID може да върне HTTP 409 — сверете съществуващата поръчка/транзакция. Клиентите не повтарят заявки автоматично и не следват HTTP redirect-и с merchant credentials.

Грешки: PHP `FirehorseException` (`getCode()` = HTTP status, `getResponseBody()`); Python `FirehorseError` (`status`, `response_body`). Status 0 означава transport error. Не изпращайте пълни response bodies/тайни към клиента.

## Merchant webhook

Валидирайте `X-FireHorse-Signature: sha256=<hex>` върху **оригиналните body bytes**, преди JSON decode. Използвайте merchant webhook secret, не provider webhook token.

```python
if not client.verify_webhook(raw_body_bytes, signature_header, os.environ['FIREHORSE_WEBHOOK_SECRET']):
    # Вашият framework връща HTTP 401; не обработвайте плащането.
    raise ValueError('Invalid webhook signature')
```

PHP използва `FirehorseClient::verifyWebhook($rawBody, $signatureHeader, $secret)`. Примерът `php/examples/webhook.php` умишлено връща 503 след валидирането, докато не добавите durable DB/queue обработка — не потвърждава неприбрани събития с 200.

Записвайте/дедупликирайте събитията, свързвайте ги с правилната поръчка и проверявайте сумата, валутата и статуса. Изпълнявайте поръчката само веднъж при проверен SUCCESS. Browser return URL/query параметрите не са доказателство за платено. Не понижавайте финален статус при закъснял callback. Върнете 2xx само след надеждно приемане на събитието.

## Локални проверки (без реални плащания)

От `api-test-client`:

```bash
npm test
npm run build
php merchant-integration/php/tests/client_test.php
PYTHONPATH=merchant-integration/python/src python3 -m unittest discover -s merchant-integration/python/tests -v
PYTHONPATH=merchant-integration/python/src python3 merchant-integration/python/tests/transport_contract.py -v
```

Unit тестовете използват фиктивни ключове и mock transport. `transport_contract.py` стартира HTTP stub само на loopback, проверява реален PHP cURL и Python HTTP transport, query/path подписване, Original amount, грешки и забрана за redirect. Изисква PHP с ext-curl; по желание задайте `TEST_PHP_BINARY=php8.3`. Няма production заявки или реални плащания.
