Payment API

Met de Payment API kun je betalingssessies aanmaken, klanten doorverwijzen naar een gehoste checkout en de status van betalingen volgen.

Betaling aanmaken

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

Gehoste checkout, H2H en exacte crypto-bedragen

Dezelfde endpoint ondersteunt drie verschillende factuurvormen. Kies er bewust één; mix hun bedragsemantiek niet.

Gehoste checkout met keuze voor betaler

Verzend amount, currency, order_id en url_callback, maar laat to_currency en network weg. De respons bevat result.url; address, qr en soms betaler-velden blijven null totdat de betaler een richting kiest op de gehoste pagina.

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

Direct-adres H2H factuur

Stuur zowel to_currency als network. 2328.io maakt de blockchainfactuur aan tijdens het API-verzoek, zodat een succesvolle respons kan worden weergegeven binnen uw checkout zonder de klant door te verwijzen.

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

Geef deze waarden exact weer zoals teruggestuurd:

• payer_amount en payer_currency — de betalingsinstructie;
• network en address — de enige bestemming voor deze factuur;
• qr — een data-URI voor hetzelfde adres;
• expires_at — de factuurdeadline;
• url — een nuttige gehoste fallback wanneer de aangepaste checkout niet kan worden voltooid.

Factuur voor een exact cryptobedrag

Plaats de cryptocurrency in currency wanneer de factuur zelf in crypto is genoteerd:

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

De gevraagde crypto-waarde wordt behouden in payer_currency / payer_amount. De dienst kan ook intern een USD-waardering bijhouden voor boekhoudkundige en tariefvelden; vervang de exacte crypto-instructie niet door die waardering. Behoud geretourneerde decimale strings, inclusief de achtervoegende precisie.

Voor een cryptocurrency met slechts één ondersteund netwerk, kan het netwerk automatisch worden geselecteerd. Het expliciet opgeven van network wordt nog steeds aanbevolen voor een deterministische integratie. Voor activa met meerdere netwerken, zoals stablecoins, stuur het altijd.

Idempotentie en herhaalde pogingen

order_id is gekoppeld aan het geauthenticeerde handelsproject en fungeert als de idempotentiesleutel voor het aanmaken. Als er al een betaling bestaat, retourneert de API die sessie met state: 0.

Aanbevolen creatie-algoritme:

1. Voeg uw lokale betalingspoging en unieke order_id in één database-transactie in.
2. Stuur het ondertekende API-verzoek.
3. Sla de geretourneerde uuid en volledige respons op.
4. Als het HTTP-resultaat verloren gaat, probeer dan hetzelfde verzoek opnieuw of vraag /v1/payment/info op via order_id.
5. Maak nooit een tweede lokale bestelling alleen omdat het upstream-verzoek is verlopen.

Betalings randgevallen

De browserreturn-URL is alleen voor navigatie. Een klant kan deze openen zonder te betalen, sluiten na betaling, of later opnieuw afspelen. Alleen een geverifieerde API/webhook-status kan de bestelling van de handelaar afhandelen.

Betalingsinformatie

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"

Betalingenlijst

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"