Create Deposit Request

Creates a reusable deposit payment session that can receive multiple top-ups over time. This is ideal for account balance funding, exchanges, casinos and any system where users can deposit arbitrary amounts. This behaves similarly to KingPay’s /deposit/request/.

GET https://api-service.kingpay.online/deposit/request/

All parameters are passed via query string. The response contains a payment_url that can be shown to the user as a “deposit page” and reused for multiple deposits.

Notices

Deposit requests are not tied to a fixed amount. The user can send any value above the network minimum.
Provide notify_url or configure the project's default IPN callback URL. A callback destination is required and receives this deposit's payment notifications.
The same deposit can receive multiple transactions (top-ups), all of them will be reported in the /deposit/logs/ endpoint.
The optional value parameter is only a UI hint for your frontend or payment page and does not limit the actual deposit amount.

Query parameters (required)

apikey string • required

Project API key generated in your merchant dashboard. Identifies which project this deposit belongs to.

May be sent either as a query parameter or via the apikey HTTP header.

notify_url string • required

IPN callback URL that will receive all deposit notifications. Every time a user sends funds to this deposit, your server will receive a callback at this URL.

Example: https://example.com/ipn/deposit?user_id=123

Query parameters (optional)

currency string • optional

Fiat currency code used for displaying or interpreting the value (e.g. USD, EUR). If omitted, no specific fiat is enforced.

value float • optional

Suggested deposit amount (in fiat, using the selected currency). This is only a hint for the payment page or your UI and does not limit how much the user can deposit.

Example: &value=50&currency=USD

customer_email string • optional

Customer email address. Stored in the invoice for your records and may be used in notifications.

customer_name string • optional

Customer name or identifier. Saved to the invoice metadata and may be displayed on the payment page.

item_description string • optional

Human-readable description of what this deposit is for (e.g. “Wallet top-up for user_id=123”).

redirect_url string • optional

URL where the user should be redirected after completing a deposit. If omitted, you can keep the user on the hosted payment page or handle redirects manually.

external_id string • optional

Merchant-side order identifier or reference (e.g. ORDER-12345). Stored in the invoice and returned in callbacks so you can easily match payments to your internal orders.

expire_at integer • optional

Link lifetime in seconds from creation, not a Unix timestamp. Minimum: 3600 (1 hour); maximum: 604800 (7 days). Defaults to 3600 when omitted, as for checkout and subscriptions. Expiration does not prevent a late incoming payment from being credited.

json integer · optional

json=1 sends callbacks as POST application/json, preserving types and null values for signature verification. Takes precedence over post. Omit both flags for GET; use only post=1 for form-encoded POST.

post integer • optional

post=1 — send IPN callbacks for this deposit using HTTP POST instead of GET. The structure of the payload is the same, only the transport changes.

Request example (cURL)

curl -G \
  'https://api-service.kingpay.online/deposit/request/' \
  --data-urlencode 'apikey=YOUR_PROJECT_API_KEY' \
  --data-urlencode 'notify_url=https://example.com/ipn/deposit?user_id=123' \
  --data-urlencode 'value=50' \
  --data-urlencode 'currency=USD' \
  --data-urlencode 'item_description=Wallet top-up for user 123' \
  --data-urlencode 'redirect_url=https://example.com/wallet' \
  --data-urlencode 'post=1'

Response (200 • application/json)

{
  "status": "success",
  "deposit_id": "de2d1c9f4a3b8e7d1f2a9c3b4e6f8a1",
  "success_token": "8c0d3a9b9a1c4f3e8b1d2c3a4f6e7b1f4c0d9a8e1b2c3d4e5f6a7b8c9d0e1f2",
  "payment_url": "https://pay.yourdomain.com/pay/de2d1c9f4a3b8e7d1f2a9c3b4e6f8a1"
}

Response fields

status — request result, "success" on successful deposit creation.
deposit_id — unique identifier of the deposit session. Use this as token when calling /deposit/logs/.
success_token — token that can be returned on success redirects, allowing you to validate the redirect on your backend.
payment_url — hosted payment page URL where the user can send funds. The same URL can be reused for multiple deposits.