Introduktion/Allmän information

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:

Skapa ett handlarkonto och ett projekt på 2328.io
Hämta ditt project UUID och din API key i projektinställningarna
Generera en separat Payout API key om du planerar att använda uttag
Läs avsnittet Authentication för att lära dig hur du signerar förfrågningar
Gör ditt första anrop till Create Payment

Bas-URL

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

Text

https://api.2328.io/api

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.

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.