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

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

Was this section helpful?YesNo
Create a top-up
POST/v1/topups
Update a top-up
POST/v1/topups/:id
Retrieve a top-up
GET/v1/topups/:id
List all top-ups
GET/v1/topups
Cancel a top-up
POST/v1/topups/:id/cancel

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.

  • metadataobject

    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 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

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.

  • metadataobject

    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.

curl https://api.stripe.com/v1/topups \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -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
}