# Allmän information

> Teknisk specifikation för integration av kryptobetalningar och uttag med 2328.io.

Välkommen till API-dokumentationen för 2328.io. Den här referensen beskriver hur du integrerar bearbetning av kryptobetalningar och uttag i din applikation.

## Komma igång

För att påbörja integrationen:

1. Skapa ett handlarkonto och ett projekt på [2328.io](https://2328.io)
2. Hämta ditt **project UUID** och din **API key** i projektinställningarna
3. Generera en separat **Payout API key** om du planerar att använda uttag
4. Läs avsnittet [Authentication](/docs/authentication) för att lära dig hur du signerar förfrågningar
5. Gör ditt första anrop till [Create Payment](/docs/payments)

## Bas-URL

Alla API-förfrågningar i produktion använder följande bas-URL:

```
https://api.2328.io/api
```

> **WARNING:** Alla förfrågningar måste göras över **HTTPS**. Förfrågningar utan HTTPS blockeras.

## Vad du kan göra

Med 2328.io API kan du:

- **Ta emot kryptobetalningar** — skapa betalningssessioner och omdirigera kunder till en värdbaserad kassa eller Telegram MiniApp
- **Göra uttag** — skicka uttag programmatiskt från ditt handlarsaldo till valfri blockchain-adress
- **Kontrollera saldon** — visa merchant-saldon per valuta, USD-motsvarigheter och AML-låsta belopp
- **Använda statiska plånböcker** — generera permanenta inbetalningsadresser knutna till en användare eller order
- **Hämta växelkurser** — få realtidskurser för fiat- och kryptopar
- **Ta emot webhooks** — bli notifierad direkt när en betalningsstatus ändras
## Hastighetsgränser

API:et tillåter upp till **10 förfrågningar per sekund och projekt**. Förfrågningar utöver gränsen får ett HTTP-svar `429 Too Many Requests` — vänta och försök igen.

## Välj rätt integrationsmönster

| Krav | Rekommenderat mönster | Varför |
|-------------|---------------------|-----|
| Låt kunden välja hur de vill betala | Hostad kassa | Skapa en betalning och omdirigera till `result.url`; 2328.io visar de aktuellt tillgängliga riktningarna. |
| Håll kunden inne i din egen kassa | Faktura med direktadress **H2H** | Skicka `to_currency` och `network` vid skapande av betalningen; rendera de returnerade `address`, `payer_amount` och `qr`. |
| Ta ut exakt `25 USDT` eller `0.001 BTC` | Faktura denominerad i kryptovaluta | Sätt kryptovalutan i `currency` och det exakta decimalbeloppet i `amount`. |
| Ge varje användare en återanvändbar insättningsadress | Statisk plånbok | Adressen är permanent och kan ta emot många oberoende insättningar. |
| Normalisera inkommande tillgångar till en balansvaluta | Autokonvertera | Konfigurera projektsregler i instrumentpanelen och använd `convert`-resultatet när konverteringen är klar. |
| Växla en befintlig handlares balans | Manuell konvertering | Förhandsgranska med `/v1/convert/price`, sedan utför med `/v1/convert`. |
| Skicka medel till en blockchain-adress | Utbetalning | Använd den separata Payout API-nyckeln, beräkna först och stäm sedan av utbetalningsstatusen. |

> **INFO:** Hosted checkout och H2H är två presentationer av samma Payment API. H2H skapar inte en svagare eller osignerad betalning: backend skapar fortfarande fakturan, 2328.io äger fortfarande adressen och statusen, och signerade webhooks förblir auktoritativa för avveckling.

## Integrationsinvarianter

Dessa regler gäller för varje produktionsintegration:

- **Backend only** — håll API-nycklar utanför webbläsare, mobila applikationer, loggar, analysverktyg och support-skärmdumpar.
- **Decimal strings** — skicka och lagra pengar som strängar. Aldrig avrunda kryptovaluta eller växelkurser med binär flyttalsaritmetik.
- **Immutable idempotency keys** — generera `order_id` innan den första förfrågan och spara hela förfrågan med det. Ett nytt försök med samma `order_id` kan returnera det ursprungliga objektet istället för att tillämpa ändrade fält.
- **Webhook-first settlement** — vidarebefordringar, klientpollning, transaktionshashar som tillhandahålls av användare och HTTP-timeouter är inte betalningsbevis.
- **Verify, deduplicate, then mutate** — verifiera HMAC, hämta ett idempotensregister atomärt, uppdatera order/balans en gång och returnera HTTP 200 snabbt.
- **Reconciliation** — kontrollera periodiskt betalnings-, statisk plånboks- och utbetalningsstatus så att en förlorad webhook inte kan orsaka permanent oenighet.
- **Dynamic availability** — validera valuta-/nätverksparet med `/v1/directions`; en stödd tillgång kan fortfarande ha en insättnings- eller uttagsriktning tillfälligt inaktiverad.
- **Explicit status policy** — bestäm hur din produkt hanterar delbetalning, överbetalning, utgång, AML-lås, konverteringsfallback och tvetydiga upstream-timeouter innan lansering.

## Rekommenderade data att spara

För betalningar, spara åtminstone `uuid`, `order_id`, originalförfrågningskroppen, `amount`, `currency`, `payer_currency`, `payer_amount`, `network`, `address`, `expires_at`, senaste `payment_status`, `txid`, `payment_amount`, `merchant_amount`, det valfria `convert`-blocket och den råa verifierade webhook-payloaden.

För statiska plånböcker, håll plånboken `uuid`, adress, valuta, nätverk, kund-/kontoreferens, status och callback-URL separat från insättningsposter. Varje insättning behöver sin egen transaktion `uuid`, `txid`, status, mottaget belopp, handlarbelopp och konverteringsresultat.