Create a wallet funding invoice

Resellers only. Creates an unpaid invoice; does not add funds until the payment settles. No on-behalf access. Uses normal provider checkout. API keys must send an Idempotency-Key header.

post/v1/wallet/topups

Request

  • Base URL: https://api.trueproxies.com
  • URL: https://api.trueproxies.com/v1/wallet/topups
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Required for API-key requests; optional for dashboard sessions. Makes a retry safe. The first request carrying a given key is executed and its response recorded; repeating the same request with the same key replays that response, with Idempotency-Replayed: true, rather than buying or paying a second time. Reusing a key for a different request is refused with 409, as is a repeat that arrives while the first is still running. Keys are scoped to your account and to the endpoint. Successful and uncertain invoice commands are retained so that an old retry cannot create another invoice. Completed definite rejections are kept for at least 24 hours; after that, the same key may be evaluated again.

Request body

amount_centsinteger required

Amount in USD cents. Also limited by daily_remaining_cents returned by GET /v1/wallet; unpaid funding invoices count toward that rolling limit.

Response

Success

activated_atstring date-time

When this invoice's service activation, top-up, renewal, or charge-only processing committed. Payment receipt and an already-active service do not establish this outcome.

activation_failed_atstring date-time

Automatic fulfillment stopped and needs operator attention. Payment remains received; this does not mean a refund completed or previously purchased service was revoked.

amount_centsinteger required
created_atstring date-time required
currencystring required
discount_bpinteger
display_namestring required
due_atstring date-time required
expiredboolean

True when a cancelled invoice closed because it was not paid by due_at. Invoices cancelled before this field existed report false.

idstring uuid required

Internal API identifier. Use reference for customer-facing display.

kind'wallet_topup' | 'purchase' | 'renewal' | 'topup' | 'upgrade' | 'custom' | 'white_label' required
list_amount_centsinteger
offer_keystring required
paid_atstring date-time
promo_codestring
promo_discount_centsinteger
referencestring required

Stable, unique customer-facing reference.

service_idstring uuid
status'open' | 'paid' | 'cancelled' required
upgrade_credit_centsinteger

Plan upgrades only. Credit for unused time on the previous plan.

upgrade_price_centsinteger

Plan upgrades only. The new plan's price; amount_cents is this minus upgrade_credit_cents.

Example response

{
  "reference": "INV-001001"
}

Changes

No recorded changes to this operation across all 1 revision of this API.