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}