# Payment API

> Skapa och hantera betalningssessioner för kryptovalutor med 2328.io Payment API.

Payment API:et låter dig skapa betalningssessioner, omdirigera kunder till en värdbaserad kassa och spåra betalningsstatus.

## Skapa betalning

Skapar en betalningssession och returnerar en URL där kunden kan betala.

### Parametrar i förfrågan

| Fält | Typ | Obligatoriskt | Beskrivning | Värden |
|-------|------|----------|-------------|--------|
| `amount` | decimal | ja | Betalningsbelopp i den angivna valutan, t.ex. `100.00` |  |
| `currency` | string | ja | Fiatvaluta (USD, EUR, RUB, …) eller kryptovaluta (USDT, TRX, BTC, …) | `USD`, `EUR`, `RUB`, `KZT`, `UAH`, `UZS`, `USDT`, `USDC`, `BTC`, `ETH`, `GRAM`, `SOL`, `TRX`, `BNB`, `POL`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `order_id` | string | ja | Ditt order-ID, t.ex. `ORDER-12345` (upp till 128 tecken) |  |
| `to_currency` | string | nej | Förvald kryptovaluta | `USDT`, `USDC`, `BTC`, `ETH`, `GRAM`, `SOL`, `TRX`, `BNB`, `POL`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `network` | string | nej\* | Nätverkskod (krävs om `to_currency` är satt eller `currency` är en kryptovaluta) | `TRX-TRC20`, `ETH-ERC20`, `BASE`, `BSC-BEP20`, `AVAX-C`, `POL-MATIC`, `TON`, `SOL`, `BTC`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `url_return` | string | nej | URL att omdirigera till efter betalning, t.ex. `https://your-site.com/return` |  |
| `url_success` | string | nej | Alternativ till `url_return` |  |
| `url_callback` | string | ja | URL för webhook-notifieringar, t.ex. `https://your-site.com/webhook` |  |
| `invite_code` | string | nej | Hänvisarkod |  |
| `fee_split` | decimal | nej | Andel av handlaravgiften som skickas vidare till betalaren, 0–100 (%). 0 = handlaren betalar fullt ut, 100 = betalaren betalar fullt ut. Åsidosätter inställningen på projektnivå. **Exempel: `30`** (betalaren täcker 30 % av avgiften). |  |
| `price_markup` | decimal | nej | Påslag eller rabatt på fakturabeloppet, −99 till 100 (%). Åsidosätter inställningen på projektnivå. **Exempel: `5`** (+5 %) eller `-10` (10 % rabatt). |  |
| `description` | string | nej | Valfri fakturabeskrivning (max 200 tecken). Visas för betalaren på betalningssidan. **Exempel: `Premium plan — Order #12345`**. |  |
| `ttl_seconds` | int | nej | Fakturans livslängd i sekunder, från `300` (5 minuter) till `86400` (24 timmar). Efter denna tid förfaller fakturan och kan inte längre betalas. Standard: `3600` (1 timme). **Exempel: `3600`**. |  |

### Svar

```json
{
  "state": 0,
  "result": {
    "uuid": "abc123-def456-...",
    "order_id": "ORDER-12345",
    "amount": "100.00",
    "currency": "USD",
    "amount_usd": "100.00",
    "exchange_rate": null,
    "url": "https://2328.io/pay/abc123-def456-...",
    "tg_deeplink": "https://t.me/my2328bot?start=pay_abc123-def456-...",
    "expires_at": "2026-01-11T21:00:00Z",
    "created_at": "2026-01-11T20:00:00Z",
    "payer_currency": "USDT",
    "payer_amount": "100.50",
    "network": "TRX-TRC20",
    "address": "TXYZabc123...",
    "payment_status": "check",
    "txid": null,
    "payment_amount": null,
    "qr": "data:image/png;base64,iVBORw0..."
  }
}
```

- Omdirigera kunden till `result.url` för att slutföra betalningen.
- `tg_deeplink` — deeplink till Telegram-bot för betalning via Telegram MiniApp.
- `qr` — Base64-kodad QR-kod (data URI) för inbetalningsadressen. Finns när en adress redan tilldelats (när `network` är satt tillsammans med `to_currency`, eller när `currency` är en kryptovaluta); annars `null`.
- `txid`, `payment_amount` — `null` tills kunden betalar. Fylls i när transaktionen upptäcks on-chain. Lyssna på webhooken `payment_status: paid` för att veta när.
- `exchange_rate` — `null` om konvertering ännu inte är tillämplig (t.ex. om växelkursen fiat → krypto inte har låsts än). Fylls i när en betalningsvaluta valts.

> Use your project UUID and the endpoint-appropriate API key from the merchant dashboard.

#### Interactive request: `POST /v1/payment`
  - `amount` (decimal, required)
  - `currency` (enum, required): USD,EUR,RUB,KZT,UAH,UZS,USDT,USDC,BTC,ETH,GRAM,SOL,TRX,BNB,POL,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `order_id` (string, required)
  - `to_currency` (enum): USDT,USDC,BTC,ETH,GRAM,SOL,TRX,BNB,POL,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `network` (enum): TRX-TRC20,ETH-ERC20,BASE,BSC-BEP20,AVAX-C,POL-MATIC,TON,SOL,BTC,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `url_return` (string)
  - `url_success` (string)
  - `url_callback` (string, required)
  - `invite_code` (string)
  - `fee_split` (decimal)
  - `price_markup` (decimal)
  - `description` (string)
  - `ttl_seconds` (integer)

## Värdbaserad kassa, H2H och exakta kryptobelopp

Samma slutpunkt stöder tre olika fakturatyper. Välj en medvetet; blanda inte deras beloppssemantik.

### Värdbaserad kassa med betalval

Skicka `amount`, `currency`, `order_id` och `url_callback`, men utelämna `to_currency` och `network`. Svar innehåller `result.url`; `address`, `qr` och ibland betalarens fält förblir `null` tills betalaren väljer en riktning på värdsidan.

```json
{
  "amount": "125.00",
  "currency": "EUR",
  "order_id": "ORDER-2026-1042",
  "url_callback": "https://merchant.example/webhooks/2328",
  "url_return": "https://merchant.example/orders/ORDER-2026-1042"
}
```

### Direktadresserad H2H-faktura

Skicka både `to_currency` och `network`. 2328.io skapar blockchain-fakturan under API-anropet, så ett lyckat svar kan visas direkt i din kassa utan att omdirigera kunden.

```json
{
  "amount": "100.00",
  "currency": "USD",
  "to_currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1043",
  "url_callback": "https://merchant.example/webhooks/2328"
}
```

Visa dessa värden exakt som de returneras:

- `payer_amount` och `payer_currency` — betalningsinstruktionen;
- `network` och `address` — den enda destinationen för denna faktura;
- `qr` — en data-URI för samma adress;
- `expires_at` — fakturans förfallodatum;
- `url` — en användbar hostad fallback när den anpassade kassan inte kan slutföras.

> **DANGER:** Generera aldrig eller ersätt en adress, återanvänd en adress från en annan faktura, eller beräkna `payer_amount` från ett offentligt spotpris. API-svaret är auktoritativt.

### Faktura för ett exakt kryptobelopp

Sätt kryptovalutan i `currency` när fakturan själv är denominerad i krypto:

```json
{
  "amount": "25.000000",
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1044",
  "url_callback": "https://merchant.example/webhooks/2328"
}
```

Det begärda kryptovärdet bevaras i `payer_currency` / `payer_amount`. Tjänsten kan också internt hålla ett USD-värde för bokföring och kursfält; ersätt inte den exakta kryptoinstruktionen med det värdet. Bevara returnedekimala strängar, inklusive efterföljande precision.

För en kryptovaluta med endast ett stöds nätverk kan nätverket väljas automatiskt. Det rekommenderas fortfarande att ange `network` uttryckligen för en deterministisk integration. För flernätverks tillgångar såsom stablecoins, skicka det alltid.

## Idempotens och försök igen

`order_id` är begränsat till det autentiserade handlarprojektet och fungerar som idempotensnyckel för skapande. Om en betalning redan finns returnerar API:t den sessionen med `state: 0`.

> **WARNING:** Ett nytt försök med samma `order_id` gör **not** betyder "uppdatera denna faktura." Ändrat belopp, valuta, callback, påslag, TTL eller riktningsfält kan ignoreras eftersom den befintliga sessionen returneras. Spara den första begäran och avvisa motstridiga försök i din egen applikation.

Rekommenderad skapandealgoritm:

1. Infoga ditt lokala betalningsförsök och unika `order_id` i en databastransaktion.
2. Skicka den signerade API-förfrågan.
3. Spara det returnerade `uuid` och hela svaret.
4. Om HTTP-resultatet går förlorat, försök samma förfrågan igen eller fråga `/v1/payment/info` via `order_id`.
5. Skapa aldrig en andra lokal order bara för att den uppströms förfrågan tidsgränsade.

## Betalningskantfall

| Situation | Korrekt hantering |
|-----------|------------------|
| `address` / `qr` är `null` | Betalarens riktning har inte initierats. Omdirigera till `url`, eller skapa en ny korrekt specificerad H2H-faktura med en ny `order_id`. |
| HTTP `400` valideringsfel | Läs fältnivå `errors`; försök inte igen med oförändrad inmatning. |
| HTTP `429` | Försök igen med jitterad exponentiell backoff och behåll samma `order_id`. |
| HTTP `503` / `direction_disabled` | Uppdatera `/v1/directions`; dölj riktningen tillfälligt eller försök igen senare. |
| Klientförfrågan timeout | Behandla resultatet som okänt. Fråga via `order_id` innan du skapar något annat. |
| `underpaid_check` | Spara den partiella händelsen och vänta på en påfyllning eller senare status. Kreditera inte två gånger när fler txids anländer. |
| `underpaid` | Slutgiltigt underbetalningstillstånd. Tillämpa din konfigurerade uppfyllnads-/manuell granskning-policy på det faktiska krediterade beloppet. |
| `overpaid` | Lyckad betalning med överskjutande medel. Utför idempotent och behåll de faktiska beloppen för avstämning/återbetalningspolicy. |
| `aml_lock` | Utför inte eller frigör medel automatiskt; rutt till efterlevnads-/supportflöde. |
| `cancel` | Faktura har gått ut eller avbrutits. Dra inte slutsatsen att en sen on-chain-överföring är omöjlig; stäm av eventuella senare händelser med support. |

Webbläsarens retur-URL är endast för navigering. En kund kan öppna den utan att betala, stänga den efter att ha betalat eller spela upp den senare. Endast ett verifierat API/webhook-tillstånd kan slutföra handlarens beställning.

## Betalningsinformation

Hämta aktuell betalningsstatus med `uuid` eller `order_id`.

### Parametrar i förfrågan

| Fält | Typ | Obligatoriskt | Beskrivning | Värden |
|-------|------|----------|-------------|--------|
| `uuid` | string | ja\* | Betalningens UUID (från `result.uuid` vid skapandet) |  |
| `order_id` | string | ja\* | Ditt order-ID |  |

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

#### Interactive request: `POST /v1/payment/info`
  - `uuid` (string)
  - `order_id` (string)

## Betalningslista

Hämta en lista över alla betalningar med filtrering och paginering.

### Parametrar i förfrågan

| Fält | Typ | Obligatoriskt | Beskrivning | Värden |
|-------|------|----------|-------------|--------|
| `status` | string | nej | Filtrera efter betalningsstatus (se [References](/docs/references)) | `pending`, `check`, `paid`, `underpaid_check`, `underpaid`, `overpaid`, `cancel` |
| `date_from` | date | nej | Startdatum (YYYY-MM-DD), t.ex. `2026-01-01` |  |
| `date_to` | date | nej | Slutdatum (YYYY-MM-DD), t.ex. `2026-01-31` |  |
| `page` | int | nej | Sidnummer, standard `1` |  |
| `per_page` | int | nej | Antal per sida, standard `15`, max `5000` |  |

#### Interactive request: `POST /v1/payment/list`
  - `status` (enum): pending,check,paid,underpaid_check,underpaid,overpaid,cancel
  - `date_from` (string)
  - `date_to` (string)
  - `page` (integer)
  - `per_page` (integer)