Payment API

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

Skapa betalning

{
  "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..."
  }
}

curl -X POST https://api.2328.io/api/v1/payment \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

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.

{
  "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.

{
  "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.

Faktura för ett exakt kryptobelopp

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

{
  "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.

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

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

curl -X POST https://api.2328.io/api/v1/payment/info \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Betalningslista

curl -X POST https://api.2328.io/api/v1/payment/list \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"