Core Resources
Payment Methods
Money Management
Products
Product Catalog
Commerce
Agentic Commerce
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury for Platforms
Payment Records
Account Evaluation
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Tax Reporting
Forwarding
Privacy
Webhooks

The Top-up object v1

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.

  • metadatamap

    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, value is "topup"

  • balance_transactionnullable stringExpandable

  • createdtimestamp

  • expected_availability_datenullable integer

  • failure_codenullable string

  • failure_messagenullable string

  • initiated_bynullable enum

  • livemodeboolean

  • payment_methodnullable stringPreview featureExpandable

  • payment_method_optionsnullable objectPreview feature

  • sourcenullable objectDeprecated

  • statement_descriptornullable string

  • transfer_groupnullable string

The Top-up object
{
  "id": "",
  "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 v1

POST /v1/topups

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.

  • metadatamap

    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

  • payment_methodstringPreview feature

  • payment_method_optionsobjectPreview feature

  • sourcestring

  • statement_descriptorstring

  • transfer_groupstring

Returns

Returns the top-up object.

curl https://api.stripe.com/v1/topups \
  -u "sk_test_...sk_test_...:" \
  -H "Stripe-Version: 2026-10-28.endive" \
  -d amount=2000 \
  -d currency=usd \
  -d "description=Top-up for Jenny Rosen" \
  -d statement_descriptor=Top-up
Response
{
  "id": "",
  "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 v1

POST /v1/topups/:id

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

Parameters

  • idstringRequired

    Unique identifier for the object.

  • descriptionstring

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

  • metadatamap

    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.

curl https://api.stripe.com/v1/topups/ \
  -u "sk_test_...sk_test_...:" \
  -H "Stripe-Version: 2026-10-28.endive" \
  -d "metadata[order_id]=6735"
Response
{
  "id": "",
  "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"
  }
}