# Statiska plånböcker

> Permanenta inbetalningsadresser knutna till en specifik order eller användare, perfekta för återkommande och långsiktiga betalningar.

Statiska plånböcker är permanenta adresser för att ta emot kryptobetalningar. De är kopplade till ett specifikt `order_id` och är unika utifrån kombinationen `project_id + order_id + currency + network`.

Använd statiska plånböcker för:

- Återkommande insättningar från samma användare
- Långsiktiga betalningsadresser som visas i en användarprofil
- Inbetalningsflöden med hög volym där du vill ha en stabil adress per användare

## Skapa statisk plånbok

`POST /v1/static-wallet`

### Parametrar i förfrågan

| Fält | Typ | Obligatoriskt | Beskrivning |
|-------|------|----------|-------------|
| `currency` | string | ja | Kryptovaluta (USDT, BTC, ETH, etc.) |
| `network` | string | ja | Nätverkskod |
| `order_id` | string | ja | Ditt order-/användar-ID (upp till 255 tecken) |
| `label` | string | nej | Plånboksetikett (upp till 255 tecken) |
| `url_callback` | string | ja | URL för webhook-notifieringar |
| `invite_code` | string | nej | Hänvisarkod |

### Exempel på förfrågan

```json
{
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "USER-123",
  "label": "User deposit #123",
  "url_callback": "https://your-site.com/webhook/static"
}
```

### Exempel på svar

```json
{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "label": "User deposit #123",
    "order_id": "USER-123",
    "status": "active",
    "url": "https://go.2328.io/static/019b2265-34d8-7001-a230-8f97de90d481",
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}
```

## Plånboksinformation

Hämta information om en statisk plånbok via `uuid` eller `address`.

`POST /v1/static-wallet/info`

### Parametrar i förfrågan

| Fält | Typ | Obligatoriskt | Beskrivning |
|-------|------|----------|-------------|
| `uuid` | string | ja* | UUID för den statiska plånboken |
| `address` | string | ja* | Plånbokens blockchain-adress |

> **INFO:** Minst en av `uuid` eller `address` är obligatorisk.

### Exempel på svar

```json
{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "status": "active",
    "total_received": "1250.50",
    "transactions_count": 3,
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}
```

- `total_received` — summan av alla insättningar som tagits emot av denna plånbok, i `currency`.
- `transactions_count` — antal insättningar som mottagits hittills.
- `qr` — Base64-kodad QR data URI för inbetalningsadressen (alltid närvarande för statiska plånböcker, eftersom adressen tilldelas vid skapandet).

## Plånbokslista

`POST /v1/static-wallet/list`

### Parametrar i förfrågan

| Fält | Typ | Obligatoriskt | Beskrivning |
|-------|------|----------|-------------|
| `status` | string | nej | Filtrera efter status (`active`, `inactive`) |
| `currency` | string | nej | Filtrera efter valuta |
| `network` | string | nej | Filtrera efter nätverk |
| `order_id` | string | nej | Filtrera efter order_id |
| `page` | int | nej | Sidnummer (standard: 1) |
| `per_page` | int | nej | Antal per sida (standard: 20, max: 100) |

### Exempel på svar

```json
{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "019b2265-...",
        "address": "TXYZabc123...",
        "currency": "USDT",
        "network": "TRX-TRC20",
        "status": "active",
        "total_received": "1250.50",
        "transactions_count": 3
      }
    ],
    "paginate": {
      "count": 1,
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "total_pages": 1,
      "has_more": false
    }
  }
}
```

## Aktivera / inaktivera plånbok

Växla om en statisk plånbok ska acceptera nya betalningar.

`POST /v1/static-wallet/disable`

`POST /v1/static-wallet/enable`

### Förfrågan

Båda endpoints tar en enda parameter:

```json
{
  "uuid": "019b2265-34d8-7001-a230-8f97de90d481"
}
```

### Exempel på svar

```json
{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "status": "inactive",
    "message": "Static wallet disabled successfully"
  }
}
```

För `enable` är `status` `"active"` och `message` lyder `"Static wallet enabled successfully"`.

## Plånbokstransaktioner

Hämta en lista över alla insättningar som mottagits av en statisk plånbok.

`POST /v1/static-wallet/transactions`

### Parametrar i förfrågan

| Fält | Typ | Obligatoriskt | Beskrivning |
|-------|------|----------|-------------|
| `uuid` | string | ja | UUID för den statiska plånboken |
| `date_from` | date | nej | Startdatum (YYYY-MM-DD) |
| `date_to` | date | nej | Slutdatum (YYYY-MM-DD) |
| `page` | int | nej | Sidnummer (standard: 1) |
| `per_page` | int | nej | Antal per sida (standard: 15, max: 5000) |

### Exempel på svar

```json
{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "abc123-def456-...",
        "order_id": "USER-123",
        "amount": "100.00",
        "currency": "USDT",
        "payment_status": "paid",
        "txid": "0xabc123def456...",
        "fee_amount": "3.00",
        "net_amount": "97.00",
        "created_at": "2026-01-20T15:30:00Z"
      }
    ],
    "paginate": {
      "count": 1,
      "hasPages": true,
      "perPage": 15,
      "page": 1
    }
  }
}
```

- `fee_amount` — plattformsavgift som dragits från denna insättning, i `currency`.
- `net_amount` — belopp som krediterats handlarsaldot efter avgift.

## Webhooks för statiska plånböcker

När en betalning tas emot på en statisk plånbok skickar systemet en webhook till `url_callback`.

> **WARNING:** Webhook-formatet för statiska plånböcker skiljer sig från vanliga betalnings-webhooks. Notera att webhooks för statiska plånböcker inkluderar fältet `merchant_amount` som du bör använda för kreditering.

### Webhook-payload

```json
{
  "uuid": "a28b293f-5c76-4053-8062-ae9ca4ab784b",
  "order_id": "USER-7666308594",
  "amount": "10.00000000",
  "currency": "USDT",
  "amount_usd": "10.00000000",
  "exchange_rate": "1.00000000",
  "payer_currency": "USDT",
  "payer_amount": "10.00000000",
  "network": "TRX-TRC20",
  "address": "TMU9Tgpchvgbywkbj5SdC8KJS73t5m3M7G",
  "payment_status": "paid",
  "txid": "8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "payment_amount": "10.00000000",
  "merchant_amount": "9.920000000000000000",
  "created_at": "2026-05-09T16:13:04+03:00",
  "sign": "dd958d1405febce670a9a196e9141784b9f2a5f39cd6d1832d6f3f68d0de1e10"
}
```

> **INFO:** Webhooks för statiska plånböcker innehåller **inte** `url` eller `expires_at` (eftersom adressen är permanent, inte en session). De innehåller `exchange_rate` och `created_at`.

### Fältreferens

| Fält | Typ | Beskrivning |
|-------|------|-------------|
| `uuid` | string | UUID för transaktionen (fakturan) för denna insättning |
| `order_id` | string | Din statiska plånboks `order_id` |
| `amount` | decimal (8 dp) | Mottaget kryptobelopp |
| `currency` | string | Mottagen krypto (matchar plånbokens `currency`) |
| `amount_usd` | decimal (8 dp) | USD-värde vid mottagandet |
| `exchange_rate` | decimal | Använd kurs krypto / USD |
| `payer_currency` | string | Samma som `currency` för statiska plånböcker |
| `payer_amount` | decimal (8 dp) | Samma som `amount` för statiska plånböcker |
| `network` | string | Blockchain-nätverk |
| `address` | string | Adressen för den statiska plånboken |
| `payment_status` | string | Alltid `paid` för statiska |
| `txid` | string | Blockchain-transaktionshash |
| `payment_amount` | decimal (8 dp) | Samma som `amount` |
| `merchant_amount` | decimal (18 dp) | **Belopp efter avgiftsavdrag** — använd detta för kreditering |
| `created_at` | string (ISO 8601) | När insättningen togs emot |
| `sign` | string (hex) | HMAC-SHA256-signatur av payloaden |

## Bästa praxis

- **Unikt `order_id`** — Använd ett unikt `order_id` för varje användare eller order
- **Idempotens** — Kontrollera `txid` innan bearbetning för att undvika dubbla krediteringar
- **Verifiera signaturer** — Verifiera ALLTID `sign`-signaturen innan du krediterar medel
- **Använd `merchant_amount`** — Kreditera användare baserat på `merchant_amount`, inte `payment_amount`