Top up the balance | SignalWire

Charges one of the space’s payment methods and deposits the amount to the balance. The minimum is 5,000,000 microdollars (5.00 USD), and the amount must be a whole number of cents.

Every top-up needs an Idempotency-Key header, a key you generate, so the request is safe to retry. Repeating a request with the same key and the same body replays the original top-up and returns 200 with the same balance adjustment instead of charging the card again; the first successful request returns 201. The same key with a different body is rejected with 400, and a top-up still in flight for that key returns 409.

A declined card returns 422 with the processor’s decline_code rather than the standard validation body. Cards are added in the Dashboard; List payment methods returns the ids to charge.

Permissions

Authenticate with a Personal access token whose holder is an owner or admin of the space. A project API token is not accepted on this endpoint, and a Personal access token has no scopes: the holder’s role in the space is the whole authorization decision.

Charges one of the space's payment methods and deposits the amount to the balance. The minimum is 5,000,000 microdollars (5.00 USD), and the amount must be a whole number of cents. Every top-up needs an `Idempotency-Key` header, a key you generate, so the request is safe to retry. Repeating a request with the same key and the same body replays the original top-up and returns `200` with the same balance adjustment instead of charging the card again; the first successful request returns `201`. The same key with a different body is rejected with `400`, and a top-up still in flight for that key returns `409`. A declined card returns `422` with the processor's `decline_code` rather than the standard validation body. Cards are added in the Dashboard; [List payment methods](/docs/apis/rest/space/billing/list-payment-methods) returns the ids to charge. #### Permissions Authenticate with a [Personal access token](/docs/apis/authorization#personal-access-tokens) whose holder is an owner or admin of the space. A project API token is not accepted on this endpoint, and a Personal access token has no scopes: the holder's role in the space is the whole authorization decision.

Authentication

AuthorizationBasic

Personal access token authentication for space-wide administration.

Send HTTP Basic auth with an empty username and the Personal access token as the password. A Personal access token carries your own authority rather than a project’s: it is created from your user menu in the Dashboard, is prefixed pat_, and has no scopes. The holder must be an owner or admin of the space named by the subdomain, and the token acts only on that space.

Example:

Authorization: Basic base64(:pat_...)

Personal access token authentication for space-wide administration. Send HTTP Basic auth with an empty username and the Personal access token as the password. A Personal access token carries your own authority rather than a project's: it is created from your user menu in the Dashboard, is prefixed `pat_`, and has no scopes. The holder must be an owner or admin of the space named by the subdomain, and the token acts only on that space. Example: ``` Authorization: Basic base64(:pat_...) ```

Request

This endpoint expects an object.

amount_in_microdollarslongRequired>=5000000

The amount to charge and deposit, in microdollars. At least 5,000,000 (5.00 USD) and a whole number of cents, so a multiple of 10,000.

payment_method_idstringRequiredformat: "uuid"

The payment method to charge. Must name a payment method on this space (payment_method_invalid). List them with List payment methods.

Response

The request has succeeded.

typeenum

The object type. Always balance_adjustment.

idstringformat: "uuid"

The unique identifier of the adjustment.

kindstring

The kind of adjustment, for example balance_top_up, auto_balance_top_up, balance_credit_by_signalwire, balance_debit_by_signalwire, coupon_code_credit, or sign_up_free_credit.

amount_in_microdollarslong

The signed amount in microdollars. Credits and debits carry the sign they were recorded with.

amountdouble

The same amount in US dollars.

created_atdatetime

The date and time when the adjustment was recorded.

payment_method_last4string or null

The last four digits of the card that was charged, or null when the adjustment was not charged to a card.

Errors

400

Bad Request Error

401

Unauthorized Error

409

Conflict Error

422

Unprocessable Entity Error

500

Internal Server Error

502

Bad Gateway Error

Charges one of the space’s payment methods and deposits the amount to the balance. The minimum is 5,000,000 microdollars (5.00 USD), and the amount must be a whole number of cents.

A declined card returns 422 with the processor’s decline_code rather than the standard validation body. Cards are added in the Dashboard; List payment methods returns the ids to charge.

Permissions

Authentication

Headers

Request

Response

Errors

Permissions