Create Payment Address

Creates a new on-chain payment address for a specific cryptocurrency ticker. The user sends funds directly to this address, which are then forwarded to your payout wallet. This behaves similarly to KingPay’s /{'{ticker}'}/create/ endpoint.

GET https://api-service.kingpay.online/{'{ticker}'}/create/

The ticker is part of the path (for example, /btc/create/ or /trc20/usdt/create/). All other parameters are sent as query string. The response returns an address_in that you can show to the user as the destination address for the payment.

Notices

Each unique callback URL will always return the same address_in. You can treat the callback URL (with its query parameters) as a logical “payment ID”.
We strongly recommend URL-encoding the callback URL so that its own query parameters are preserved.
If you don’t provide address, funds are forwarded to the default payout address configured for this ticker in your dashboard.
To avoid repeated callbacks, your IPN endpoint should respond with *ok* as plain text when you successfully process the notification.
You can reuse the same payment address for multiple payments; all incoming transactions for that address will also be visible in the /ticker/logs/ (or equivalent) endpoint.

Path & query parameters (required)

ticker string • path • required

Cryptocurrency and network identifier used for this payment address. Examples: btc, ltc, trc20/usdt.

The ticker is part of the URL path: https://api-service.kingpay.online/btc/create/

apikey string • required

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

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

callback string • required

IPN callback URL that will receive payment notifications when funds are sent to the generated address_in.

Example: https://example.com/ipn/payment?order_id=1234

Query parameters (optional)

address string • optional

Your own payout address where funds should ultimately be forwarded. If omitted, the default address configured for this ticker in your dashboard will be used.

priority string • optional

Confirmation priority for forwarding transactions (for example, low, default, high). Affects how many network confirmations are required before a payout is processed.

pending integer • optional

Legacy notification option, retained for compatibility. UTXO progress webhooks use payment_status regardless of this option. Pending payments are never credited before confirmation.

post integer • optional

post=1 — send IPN callbacks for this payment using HTTP POST instead of GET. The payload fields remain the same; only the HTTP method changes.

Request example (cURL)

curl -G \
  'https://api-service.kingpay.online/btc/create/' \
  --data-urlencode 'apikey=YOUR_PROJECT_API_KEY' \
  --data-urlencode 'callback=https://example.com/ipn/payment?order_id=1234' \
  --data-urlencode 'address=1YourPayoutAddressHere' \
  --data-urlencode 'priority=default' \
  --data-urlencode 'pending=1' \
  --data-urlencode 'post=1'

Response (200 • application/json)

{
  "status": "success",
  "address_in": "14PqCsA7KMgseZMPwg6mJy754MtQkrgszu",
  "address_out": "1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP",
  "callback_url": "https://example.com/ipn/payment?order_id=1234",
  "priority": "default",
  "minimum_transaction_coin": 0.008
}

Response fields

status — request result, "success" on successful address creation.
address_in — unique payment address you should display to the user. All incoming funds are monitored on this address.
address_out — forwarding address where funds will be sent after confirmation (your payout address).
callback_url — the effective callback URL that will receive IPNs for this payment.
priority — confirmation profile used for forwarding transactions.
minimum_transaction_coin — minimum accepted transaction value for this currency; smaller payments may be ignored.