Payments and Payouts/Payment API

Payment API

Create and manage cryptocurrency payment sessions with the 2328.io Payment API.

The Payment API lets you create payment sessions, redirect customers to a hosted checkout, and track payment status.

Create payment

Creates a payment session and returns a URL for the customer to pay.

Request parameters

Field	Type	Required	Description
`amount`	decimal	yes	Payment amount in the currency, e.g. `100.00`
`currency`	string	yes	Fiat currency (USD, EUR, RUB, …) or cryptocurrency (USDT, TRX, BTC, …)
`order_id`	string	yes	Your order ID, e.g. `ORDER-12345` (up to 128 chars)
`to_currency`	string	no	Preselected cryptocurrency
`network`	string	no*	Network code (required if `to_currency` is set or `currency` is a cryptocurrency)
`url_return`	string	no	Redirect URL after payment, e.g. `https://your-site.com/return`
`url_success`	string	no	Alternative to `url_return`
`url_callback`	string	no	URL for webhook notifications, e.g. `https://your-site.com/webhook`
`invite_code`	string	no	Referrer code
`fee_split`	decimal	no	Share of the merchant fee passed to the payer, 0–100 (%). 0 = merchant pays fully, 100 = payer pays fully. Overrides the project-level setting. Example: `30` (payer covers 30% of the fee).
`price_markup`	decimal	no	Markup or discount on the invoice amount, −99 to 100 (%). Overrides the project-level setting. Example: `5` (+5%) or `-10` (10% discount).
`description`	string	no	Optional invoice description (max 200 chars). Shown to the payer on the payment page. Example: `Premium plan — Order #12345`.
`ttl_seconds`	int	no	Invoice lifetime in seconds, from `300` (5 minutes) to `86400` (24 hours). After this period the invoice expires and can no longer be paid. Default: `3600` (1 hour). Example: `3600`.

Response

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

Redirect the customer to result.url to complete payment.
tg_deeplink — Telegram bot deeplink for payment via Telegram MiniApp.
qr — Base64-encoded QR code (data URI) of the deposit address. Present when an address is already assigned (when network is set together with to_currency, or when currency is a cryptocurrency); otherwise null.
txid, payment_amount — null until the customer pays. Filled in once the transaction is detected on-chain. Listen for the payment_status: paid webhook to know when.
exchange_rate — null if conversion isn't applicable yet (e.g. fiat → crypto rate hasn't been locked). Filled in once a payer currency is chosen.

Credentials

Project UUIDAPI key

RequestPOST/v1/payment

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"

Response

Click Try it to see the response here.

Payment info

Get the current payment status by uuid or order_id.

Request parameters

Field	Type	Required	Description	Values
`uuid`	string	yes*	Payment UUID (from `result.uuid` on creation)
`order_id`	string	yes*	Your order ID

At least one of uuid or order_id is required.

RequestPOST/v1/payment/info

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"

Response

Click Try it to see the response here.

Payment list

Get a list of all payments with filtering and pagination.

Request parameters

Field	Type	Required	Description
`status`	string	no	Filter by payment status (see References)
`date_from`	date	no	Start date (YYYY-MM-DD), e.g. `2026-01-01`
`date_to`	date	no	End date (YYYY-MM-DD), e.g. `2026-01-31`
`page`	int	no	Page number, default `1`
`per_page`	int	no	Items per page, default `15`, max `5000`

RequestPOST/v1/payment/list

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"

Response

Click Try it to see the response here.