Skip to content
TrueProxies Docs

Create a wallet funding invoice

POST
/v1/wallet/topups
curl --request POST \
  --url https://api.trueproxies.com/v1/wallet/topups \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "amount_cents": 1 }'

Resellers only. Creates an unpaid invoice; does not add funds until the payment settles. No on-behalf access. Uses normal provider checkout.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
<= 200 characters

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 Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
amount_cents
required

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

integer
>= 1000 <= 1000000
Examplegenerated
{
  "amount_cents": 1
}

Responses

Section titled “Responses”

201

Section titled “201”

Success

Media typeapplication/json
object
activated_at

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.

string format: date-time
activation_failed_at

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

string format: date-time
amount_cents
required
integer
bill_to

Who the invoice is issued to, copied from the account’s billing details when the invoice was created. Absent when the account had no billing details then; saving details later does not change it.

object
address
string
company
string
country
string
name
string
vat_id
string
created_at
required
string format: date-time
currency
required
string
discount_bp
integer
display_name
required
string
due_at
required
string format: date-time
expired

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

boolean
id
required

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

string format: uuid
kind
required
string
Allowed values: wallet_topup purchase renewal topup custom white_label
list_amount_cents
integer
offer_key
required
string
options
object
city
string
gb

GB for top-ups; taken from the offer otherwise

integer
paid_at
string format: date-time
payments
required
Array<object>
object
amount_received_cents
integer
attempt
required
integer
checkout_url

Present only while the invoice is payable and the pending checkout has not reached its known expiry

string
created_at
required
string format: date-time
expires_at
string format: date-time
failure_reason

Staff views only. Why the checkout ended unpaid, as the provider reports it: not_attempted (no payment submitted), not_completed (started, never confirmed), or the card issuer’s code such as card_declined/insufficient_funds.

string
id
required
string format: uuid
provider
required
One of:

Payment provider identifier (stripe or cryptomus).

string
refund_amount_cents
integer
>= 1
refund_amount_unknown

A provider refund was reported without a trustworthy amount. Reconciliation is required before any additional refund.

boolean
refund_completed_at
string format: date-time
refund_reason
string
refund_reference
string
refund_retryable

The recorded request can be retried unchanged within the provider idempotency window.

boolean
refund_status
string
Allowed values: processing uncertain manual_required submitted failed refunded
refunded_at

Refund request recorded at; not proof of completion

string format: date-time
status
required
string
Allowed values: pending paid expired failed paid_unapplied paid_duplicate
promo_code
string
promo_discount_cents
integer format: int64
reference
required

Stable, unique customer-facing reference.

string
/^INV-[0-9]{6,}$/
service_id
string format: uuid
status
required
string
Allowed values: open paid cancelled
Example
{
  "kind": "wallet_topup",
  "payments": [
    {
      "provider": "manual",
      "refund_status": "processing",
      "status": "pending"
    }
  ],
  "reference": "INV-001001",
  "status": "open"
}

400

Section titled “400”

Error

Media typeapplication/json
object
code
required
string
Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL
details

What a client needs to act on the error (ids, flags), never display text.

object
key
additional properties
any
message
required
string
Example
{
  "code": "BAD_REQUEST"
}

401

Section titled “401”

Error

Media typeapplication/json
object
code
required
string
Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL
details

What a client needs to act on the error (ids, flags), never display text.

object
key
additional properties
any
message
required
string
Example
{
  "code": "BAD_REQUEST"
}

403

Section titled “403”

Error

Media typeapplication/json
object
code
required
string
Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL
details

What a client needs to act on the error (ids, flags), never display text.

object
key
additional properties
any
message
required
string
Example
{
  "code": "BAD_REQUEST"
}

404

Section titled “404”

Error

Media typeapplication/json
object
code
required
string
Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL
details

What a client needs to act on the error (ids, flags), never display text.

object
key
additional properties
any
message
required
string
Example
{
  "code": "BAD_REQUEST"
}

409

Section titled “409”

Error

Media typeapplication/json
object
code
required
string
Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL
details

What a client needs to act on the error (ids, flags), never display text.

object
key
additional properties
any
message
required
string
Example
{
  "code": "BAD_REQUEST"
}

429

Section titled “429”

Error

Media typeapplication/json
object
code
required
string
Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL
details

What a client needs to act on the error (ids, flags), never display text.

object
key
additional properties
any
message
required
string
Example
{
  "code": "BAD_REQUEST"
}

500

Section titled “500”

Error

Media typeapplication/json
object
code
required
string
Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL
details

What a client needs to act on the error (ids, flags), never display text.

object
key
additional properties
any
message
required
string
Example
{
  "code": "BAD_REQUEST"
}

503

Section titled “503”

Error

Media typeapplication/json
object
code
required
string
Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL
details

What a client needs to act on the error (ids, flags), never display text.

object
key
additional properties
any
message
required
string
Example
{
  "code": "BAD_REQUEST"
}

default

Section titled “default”

Error

Media typeapplication/json
object
code
required
string
Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL
details

What a client needs to act on the error (ids, flags), never display text.

object
key
additional properties
any
message
required
string
Example
{
  "code": "BAD_REQUEST"
}