Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Connect
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks
Sign in →

Top-ups

To top up your Stripe balance, you create a top-up object. You can retrieve individual top-ups, as well as list all top-ups. Top-ups are identified by a unique, random ID.

Related guide: Topping up your platform account

Endpoints

The Top-up object

Attributes

  • idstring

    Unique identifier for the object.

  • amountinteger

    Amount transferred.

  • currencystring

    Three-letter ISO currency code, in lowercase. Must be a supported currency.

  • descriptionnullable string

    An arbitrary string attached to the object. Often useful for displaying to users.

  • metadatadictionary

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

  • statusenum

    The status of the top-up is either canceled, failed, pending, reversed, or succeeded.

    Possible enum values
    canceled
    failed
    pending
    reversed
    succeeded

More attributes

  • objectstring

  • balance_transactionnullable stringExpandable

  • createdtimestamp

  • expected_availability_datenullable integer

  • failure_codenullable string

  • failure_messagenullable string

  • livemodeboolean

  • sourcenullable dictionaryDeprecated

  • statement_descriptornullable string

  • transfer_groupnullable string

The Top-up object
{
  "id": "tu_1NG6yj2eZvKYlo2C1FOBiHya",
  "object": "topup",
  "amount": 2000,
  "balance_transaction": null,
  "created": 123456789,
  "currency": "usd",
  "description": "Top-up for Jenny Rosen",
  "expected_availability_date": 123456789,
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "source": null,
  "statement_descriptor": "Top-up",
  "status": "pending",
  "transfer_group": null
}

Create a top-up

Top up the balance of an account

Parameters

  • amountintegerRequired

    A positive integer representing how much to transfer.

  • currencystringRequired

    Three-letter ISO currency code, in lowercase. Must be a supported currency.

  • descriptionstring

    An arbitrary string attached to the object. Often useful for displaying to users.

  • metadatadictionary

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

More parameters

  • sourcestring

  • statement_descriptorstring

  • transfer_groupstring

Returns

Returns the top-up object.

POST /v1/topups
import stripe
stripe.api_key = "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc"
stripe.Topup.create(
  amount=2000,
  currency="usd",
  description="Top-up for Jenny Rosen",
  statement_descriptor="Top-up",
)
Response
{
  "id": "tu_1NG6yj2eZvKYlo2C1FOBiHya",
  "object": "topup",
  "amount": 2000,
  "balance_transaction": null,
  "created": 123456789,
  "currency": "usd",
  "description": "Top-up for Jenny Rosen",
  "expected_availability_date": 123456789,
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "source": null,
  "statement_descriptor": "Top-up",
  "status": "pending",
  "transfer_group": null
}

Update a top-up

Updates the metadata of a top-up. Other top-up details are not editable by design.

Parameters

  • descriptionstring

    An arbitrary string attached to the object. Often useful for displaying to users.

  • metadatadictionary

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

Returns

The newly updated top-up object if the call succeeded. Otherwise, this call raises an error.

POST /v1/topups/:id
import stripe
stripe.api_key = "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc"
stripe.Topup.modify(
  "tu_1NG6yj2eZvKYlo2C1FOBiHya",
  metadata={"order_id": "6735"},
)
Response
{
  "id": "tu_1NG6yj2eZvKYlo2C1FOBiHya",
  "object": "topup",
  "amount": 2000,
  "balance_transaction": null,
  "created": 123456789,
  "currency": "usd",
  "description": "Top-up for Jenny Rosen",
  "expected_availability_date": 123456789,
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "source": null,
  "statement_descriptor": "Top-up",
  "status": "pending",
  "transfer_group": null,
  "metadata": {
    "order_id": "6735"
  }
}

Retrieve a top-up

Retrieves the details of a top-up that has previously been created. Supply the unique top-up ID that was returned from your previous request, and Stripe will return the corresponding top-up information.

Parameters

No parameters.

Returns

Returns a top-up if a valid identifier was provided, and raises an error otherwise.

GET /v1/topups/:id
import stripe
stripe.api_key = "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc"
stripe.Topup.retrieve("tu_1NG6yj2eZvKYlo2C1FOBiHya")
Response
{
  "id": "tu_1NG6yj2eZvKYlo2C1FOBiHya",
  "object": "topup",
  "amount": 2000,
  "balance_transaction": null,
  "created": 123456789,
  "currency": "usd",
  "description": "Top-up for Jenny Rosen",
  "expected_availability_date": 123456789,
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "source": null,
  "statement_descriptor": "Top-up",
  "status": "pending",
  "transfer_group": null
}
Stripe Shell
Test mode

Welcome to the Stripe Shell!

Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your
Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe
resources in test mode.

- View supported Stripe commands: 
- Find webhook events: 
- Listen for webhook events: 
- Call Stripe APIs: stripe [api resource] [operation] (e.g., )
The Stripe Shell is best experienced on desktop.
$