# 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",
  "tx_explorer_url": "https://tronscan.org/#/transaction/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 | Aktuell ins?ttningsstatus; normalt `paid`, men AML kan ge `aml_lock`, som inte f?r krediteras automatiskt |
| `txid` | string | Blockchain-transaktionshash |
| `tx_explorer_url` | string \| null | Transaktionens URL i blockkedjeutforskaren. `null` om `txid` saknas eller överföringen är intern P2P. |
| `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`

## Livscykel och idempotens

En statisk plånbok är en återanvändbar insättningsidentitet, inte en faktura. Den har inget förväntat belopp och ingen utgångstid. En adress kan generera ett obegränsat antal insättningstransaktioner under sin livstid.

Skapande är idempotent för samma handlareprojekt, `order_id`, `currency` och `network`: den befintliga plånboken returneras. Håll den tupeln stabil och spara den returnerade plånboken `uuid`; använd inte en ny `order_id` varje gång samma kund öppnar insättningsskärmen.

Idempotens för insättningar skiljer sig från idempotens för plånbok:

- `order_id` identifierar den återanvändbara plånbok/kund-mappningen;
- plånbok `uuid` identifierar den permanenta plånboksregistreringen;
- webhook `uuid` identifierar en upptäckt insättningstransaktion;
- `txid` identifierar on-chain-överföringen och är nyckeln för primär duplikathantering vid kreditering.

Använd en unikhetsbegränsning i databasen för den behandlade chain/network/txid-identiteten och kräva den i samma transaktion som krediterar kundens interna saldo.

## Aktivera och inaktivera semantik

Att inaktivera en plånbok förhindrar att applikationen behandlar den som ett aktivt insättningsmål; det raderar inte adressen eller dess historik och kan inte stoppa en blockchain-överföring som redan skickats av en användare.

> **DANGER:** Berätta aldrig för användare att pengar som skickats till en inaktiv adress automatiskt returneras. Blockchain-överföringar är irreversible. Inaktivera endast efter att ha tagit bort adressen från ditt användargränssnitt, och behåll en fungerande återställningsprocedur för sena insättningar.

Återaktivering bevarar samma plånboksidentitet och adress. Skapa inte en ersättning enbart för att ändra etiketten; etiketter är inte uppgörelseidentifierare.

## Statisk plånboks specialfall

| Situation | Korrekt hantering |
|-----------|------------------|
| Dubbel skapande-förfrågan | Acceptera den returnerade befintliga plånboken och verifiera dess sparade tuppel istället för att förvänta dig en ny adress. |
| Flertal insättningar till en adress | Skapa en separat lokal insättningsrad för varje transaktion `uuid`/`txid`; markera aldrig plånboken själv som "betald." |
| Duplicera webhook | Returnera HTTP 200 efter att ha hittat den redan genomförda txid; ge aldrig kredit igen. |
| Bekräftelsefördröjning eller omobservation av kedjan | Håll bearbetningen idempotent och avstäm från `/v1/static-wallet/transactions`. |
| Insättning under en automatisk konverteringsminimi | Förvänta dig kredit i källvaluta utan slutförd `convert` block. |
| Automatisk konvertering lyckas | Spara värden för källbetalning och resultatet i mål `convert` separat. |
| Fel token eller fel nätverk | Fabricera inte en kredit. Dokumentera bevis och eskalera till support/återvinning eftersom återvinningsbarheten är kedjespecifik. |
| Memo/tag-baserad kedja | Visa och validera varje destinationsfält som plattformen returnerar; en adress ensam kan vara otillräcklig när ett memo krävs. |
| AML-lås | Kreditera inte slutanvändaren förrän den auktoritativa statusen har frigjorts genom regelefterlevnadsprocessen. |
| Plånbok inaktiverad efter adressvisning | Ta bort den från användargränssnittet omedelbart, men fortsätt övervaka operativa larm för sena överföringar. |

## Avstämningsmodell

Kör ett periodiskt jobb som bläddrar igenom `/v1/static-wallet/transactions`, uppdaterar insättningar efter txid och jämför deras `merchant_amount`, status och eventuellt konverteringsresultat med din interna huvudbok. Webhook-leverans bör göra avstämningen snabb, men avstämningen måste göra den fullständig.