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

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": "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.

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

POST /v1/topups
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": "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.

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

Returns

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

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

List all top-ups 

Returns a list of top-ups.

Parameters

  • statusstring

    Only return top-ups that have the given status. One of canceled, failed, pending or succeeded.

More parameters

  • amountobject

  • createdobject

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

A dictionary containing the data property, which is an array of separate top-up objects. The number of top-ups in the array is limited to the number designated in limit. If no more top-ups are available, the resulting array will be empty.

GET /v1/topups
curl -G https://api.stripe.com/v1/topups \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d limit=3
Response
{
  "object": "list",
  "url": "/v1/topups",
  "has_more": false,
  "data": [
    {
      "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
    }
  ]
}