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? Yes No

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

• id string Unique identifier for the object.
• amount integer Amount transferred.
• currency string Three-letter ISO currency code, in lowercase. Must be a supported currency.
• description nullable string An arbitrary string attached to the object. Often useful for displaying to users.
• metadata map 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.
• status enum The status of the top-up is either canceled, failed, pending, reversed, or succeeded. Possible enum values canceled failed pending reversed succeeded

More attributes

• object string, value is "topup"
• balance _ transaction nullable string Expandable
• created timestamp
• expected _ availability _ date nullable integer
• failure _ code nullable string
• failure _ message nullable string
• initiated _ by nullable enum
• livemode boolean
• payment _ method nullable string Preview feature Expandable
• payment _ method _ options nullable object Preview feature
• source nullable object Deprecated
• statement _ descriptor nullable string
• transfer _ group nullable 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

POST / v1 / topups

Top up the balance of an account

Parameters

• amount integer Required A positive integer representing how much to transfer.
• currency string Required Three-letter ISO currency code, in lowercase. Must be a supported currency.
• description string An arbitrary string attached to the object. Often useful for displaying to users.
• metadata map 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 _ method string Preview feature
• payment _ method _ options object Preview feature
• source string
• statement _ descriptor string
• transfer _ group string

Returns

Returns the top-up object.

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}