# PRIMO Gateway API v1

Base URL: `https://YOUR-DOMAIN.example`

## Authentication
Send your merchant secret only from your server:
`Authorization: Bearer sk_live_...`

Never put the secret in browser JavaScript.

## Create Pay-in
`POST /api/v1/payment/create.php`

JSON:
```json
{"amount":100,"customer_reference":"ORDER-1001","callback_url":"https://merchant.example/webhook","idempotency_key":"ORDER-1001"}
```

Response contains `transaction_id` and `payment_url`. Redirect the customer's browser to `payment_url`.

## Query
`GET /api/v1/payment/status.php?transaction_id=TX...`

## Payout Request
`POST /api/v1/payout/create.php`

JSON:
```json
{"amount":100,"payment_method":"bkash","payment_number":"01XXXXXXXXX","customer_reference":"WD-1001"}
```

This creates a pending payout request and reserves the amount. An authorized payout provider/admin must complete it.

## Provider Webhook
`POST /api/v1/webhook.php`

The provider-side integration must sign the exact fields documented in the code before a transaction can become `success`.

## Production requirements
- Use HTTPS.
- Keep secrets server-side.
- Add rate limiting and request logging.
- Use an authorized payment provider for real bKash/Nagad collection/payout.
- Do not credit balance from a browser redirect; credit only after verified server-to-server confirmation.
- Add webhook replay protection and provider idempotency before live launch.