Sample - Stripe API
POST/v1/topups

Create a top-up

Creates a top-up to add funds to the account balance. Supply amount and currency, and provide a payment_method or source when the funding method must be selected explicitly. The response includes the created top-up and its processing status.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

10 body fields

Top-up details submitted as form-encoded data.

amountintegerrequired
A positive integer representing how much to transfer.
currencystringrequired
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
descriptionstringoptional
An arbitrary string attached to the object. Often useful for displaying to users.
expandarray<string>optional
Specifies which fields in the response should be expanded.
metadataobjectoptional
Set of [key-value pairs](https://docs.stripe.com/api/metadata) 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`.
payment_methodstringoptional
The ID of a PaymentMethod representing the payment method to be used for the top-up. A PaymentMethod of type `us_bank_account` can be used.
payment_method_optionsobjectoptional
Payment method-specific configuration for this top-up.
sourcestringoptional
The ID of a source to transfer funds from. For most users, this should be left unspecified which will use the bank account that was set up in the dashboard for the specified currency. In test mode, this can be a test bank token (see [Testing Top-ups](https://docs.stripe.com/connect/testing#testing-top-ups)).
statement_descriptorstringoptional
Extra information about a top-up for the source's bank statement. Limited to 15 ASCII characters.
transfer_groupstringoptional
A string that identifies this top-up as part of a group.

2 status codes
200Returns the created top-up object with its amount, currency, identifier, creation time, status, funding method, and balance impact details.
amountintegerrequired
Amount transferred.
balance_transactionstringoptional
ID of the balance transaction that describes the impact of this top-up on your account balance. May not be specified depending on status of top-up.
createdintegerrequired
Time at which the object was created. Measured in seconds since the Unix epoch.
currencystringrequired
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
descriptionstringoptional
An arbitrary string attached to the object. Often useful for displaying to users.
expected_availability_dateintegeroptional
Date the funds are expected to arrive in your Stripe account for payouts. This factors in delays like weekends or bank holidays. May not be specified depending on status of top-up.
failure_codestringoptional
Error code explaining reason for top-up failure if available (see [the errors section](/api/errors) for a list of codes).
failure_messagestringoptional
Message to user further explaining reason for top-up failure if available.
idstringrequired
Unique identifier for the object.
initiated_bystringoptional
Indicates whether the top-up was initiated by Stripe or by the user.
Allowed:stripeuser
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
metadataobjectrequired
Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:topup
payment_methodstringoptional
The ID of a PaymentMethod representing the payment method used for the top-up. A PaymentMethod of type `us_bank_account` can be used.
payment_method_optionsobjectoptional
Payment-method-specific configuration for this top-up.
sourceobjectoptional
The source field is deprecated. It might not always be present in the API response.
statement_descriptorstringoptional
Extra information about a top-up. This will appear on your source's bank statement. It must contain at least one letter.
statusstringrequired
The status of the top-up is either `canceled`, `failed`, `pending`, `reversed`, or `succeeded`.
Allowed:canceledfailedpendingreversedsucceeded
transfer_groupstringoptional
A string that identifies this top-up as part of a group.
defaultError response.
errorobjectrequired

Error handling

amount and currency are required. currency must be a lowercase, three-letter supported ISO currency code, and statement_descriptor must not exceed 15 ASCII characters when supplied.