The Top-up object

Connect

Top-ups

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
String representing the object’s type. Objects of the same type share the same value.

balance_transactionnullable stringExpandable
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.

createdtimestamp
Time at which the object was created. Measured in seconds since the Unix epoch.

expected_availability_datenullable integer
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_codenullable string
Error code explaining reason for top-up failure if available (see the errors section for a list of codes).

failure_messagenullable string
Message to user further explaining reason for top-up failure if available.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

sourcenullable objectDeprecated

The source field is deprecated. It might not always be present in the API response.

source.idstring
Unique identifier for the object.

source.objectstring
String representing the object’s type. Objects of the same type share the same value.

source.allow_redisplaynullable enum

This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow. The field defaults to “unspecified”.

Possible enum values

always

Use always to indicate that this payment method can always be shown to a customer in a checkout flow.

limited

Use limited to indicate that this payment method can’t always be shown to a customer in a checkout flow. For example, it can only be shown in the context of a specific subscription.

unspecified

This is the default value for payment methods where allow_redisplay wasn’t set.

source.amountnullable integer
A positive integer in the smallest currency unit (that is, 100 cents for $1.00, or 1 for ¥1, Japanese Yen being a zero-decimal currency) representing the total amount associated with the source. This is the amount for which the source will be chargeable once ready. Required for single_use sources.

source.client_secretstring
The client secret of the source. Used for client-side retrieval using a publishable key.

source.code_verificationnullable object
Information related to the code verification flow. Present if the source is authenticated by a verification code (flow is code_verification).
- source.code_verification.attempts_remaininginteger
  The number of attempts remaining to authenticate the source object with a verification code.
- source.code_verification.statusstring
  The status of the code verification, either pending (awaiting verification, attempts_remaining should be greater than 0), succeeded (successful verification) or failed (failed verification, cannot be verified anymore as attempts_remaining should be 0).

source.createdtimestamp
Time at which the object was created. Measured in seconds since the Unix epoch.

source.currencynullable enum
Three-letter ISO code for the currency associated with the source. This is the currency for which the source will be chargeable once ready. Required for single_use sources.

source.customernullable string
The ID of the customer to which this source is attached. This will not be present when the source has not been attached to a customer.

source.flowstring
The authentication flow of the source. flow is one of redirect, receiver, code_verification, none.

source.livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

source.metadatanullable object
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.

source.ownernullable object
Information about the owner of the payment instrument that may be used or required by particular source types.
- source.owner.addressnullable object
  Owner’s address.
  source.owner.address.citynullable string
  City, district, suburb, town, or village.
  source.owner.address.countrynullable string
  Two-letter country code (ISO 3166-1 alpha-2).
  source.owner.address.line1nullable string
  Address line 1 (e.g., street, PO Box, or company name).
  source.owner.address.line2nullable string
  Address line 2 (e.g., apartment, suite, unit, or building).
  source.owner.address.postal_codenullable string
  ZIP or postal code.
  source.owner.address.statenullable string
  State, county, province, or region.
- source.owner.emailnullable string
  Owner’s email address.
- source.owner.namenullable string
  Owner’s full name.
- source.owner.phonenullable string
  Owner’s phone number (including extension).
- source.owner.verified_addressnullable object
  Verified owner’s address. Verified values are verified or provided by the payment method directly (and if supported) at the time of authorization or settlement. They cannot be set or mutated.
  source.owner.verified_address.citynullable string
  City, district, suburb, town, or village.
  source.owner.verified_address.countrynullable string
  Two-letter country code (ISO 3166-1 alpha-2).
  source.owner.verified_address.line1nullable string
  Address line 1 (e.g., street, PO Box, or company name).
  source.owner.verified_address.line2nullable string
  Address line 2 (e.g., apartment, suite, unit, or building).
  source.owner.verified_address.postal_codenullable string
  ZIP or postal code.
  source.owner.verified_address.statenullable string
  State, county, province, or region.
- source.owner.verified_emailnullable string
  Verified owner’s email address. Verified values are verified or provided by the payment method directly (and if supported) at the time of authorization or settlement. They cannot be set or mutated.
- source.owner.verified_namenullable string
  Verified owner’s full name. Verified values are verified or provided by the payment method directly (and if supported) at the time of authorization or settlement. They cannot be set or mutated.
- source.owner.verified_phonenullable string
  Verified owner’s phone number (including extension). Verified values are verified or provided by the payment method directly (and if supported) at the time of authorization or settlement. They cannot be set or mutated.

source.receivernullable object
Information related to the receiver flow. Present if the source is a receiver (flow is receiver).
- source.receiver.addressnullable string
  The address of the receiver source. This is the value that should be communicated to the customer to send their funds to.
- source.receiver.amount_chargedinteger
  The total amount that was moved to your balance. This is almost always equal to the amount charged. In rare cases when customers deposit excess funds and we are unable to refund those, those funds get moved to your balance and show up in amount_charged as well. The amount charged is expressed in the source’s currency.
- source.receiver.amount_receivedinteger
  The total amount received by the receiver source. amount_received = amount_returned + amount_charged should be true for consumed sources unless customers deposit excess funds. The amount received is expressed in the source’s currency.
- source.receiver.amount_returnedinteger
  The total amount that was returned to the customer. The amount returned is expressed in the source’s currency.
- source.receiver.refund_attributes_methodstring
  Type of refund attribute method, one of email, manual, or none.
- source.receiver.refund_attributes_statusstring
  Type of refund attribute status, one of missing, requested, or available.

source.redirectnullable object
Information related to the redirect flow. Present if the source is authenticated by a redirect (flow is redirect).
- source.redirect.failure_reasonnullable string
  The failure reason for the redirect, either user_abort (the customer aborted or dropped out of the redirect flow), declined (the authentication failed or the transaction was declined), or processing_error (the redirect failed due to a technical error). Present only if the redirect status is failed.
- source.redirect.return_urlstring
  The URL you provide to redirect the customer to after they authenticated their payment.
- source.redirect.statusstring
  The status of the redirect, either pending (ready to be used by your customer to authenticate the transaction), succeeded (succesful authentication, cannot be reused) or not_required (redirect should not be used) or failed (failed authentication, cannot be reused).
- source.redirect.urlstring
  The URL provided to you to redirect a customer to as part of a redirect authentication flow.

source.source_ordernullable object
Information about the items and shipping associated with the source. Required for transactional credit (for example Klarna) sources before you can charge it.
- source.source_order.amountinteger
  A positive integer in the smallest currency unit (that is, 100 cents for $1.00, or 1 for ¥1, Japanese Yen being a zero-decimal currency) representing the total amount for the order.
- source.source_order.currencyenum
  Three-letter ISO currency code, in lowercase. Must be a supported currency.
- source.source_order.emailnullable string
  The email address of the customer placing the order.
- source.source_order.itemsnullable array of objects
  List of items constituting the order.
  source.source_order.items.amountnullable integer
  The amount (price) for this order item.
  source.source_order.items.currencynullable string
  This currency of this order item. Required when amount is present.
  source.source_order.items.descriptionnullable string
  Human-readable description for this order item.
  source.source_order.items.parentnullable string
  The ID of the associated object for this line item. Expandable if not null (e.g., expandable to a SKU).
  source.source_order.items.quantitynullable integer
  The quantity of this order item. When type is sku, this is the number of instances of the SKU to be ordered.
  source.source_order.items.typenullable string
  The type of this order item. Must be sku, tax, or shipping.
- source.source_order.shippingnullable object
  The shipping address for the order. Present if the order is for goods to be shipped.
  source.source_order.shipping.addressnullable object
  Shipping address.
  source.source_order.shipping.address.citynullable string
  City, district, suburb, town, or village.
  source.source_order.shipping.address.countrynullable string
  Two-letter country code (ISO 3166-1 alpha-2).
  source.source_order.shipping.address.line1nullable string
  Address line 1 (e.g., street, PO Box, or company name).
  source.source_order.shipping.address.line2nullable string
  Address line 2 (e.g., apartment, suite, unit, or building).
  source.source_order.shipping.address.postal_codenullable string
  ZIP or postal code.
  source.source_order.shipping.address.statenullable string
  State, county, province, or region.
  source.source_order.shipping.carriernullable string
  The delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc.
  source.source_order.shipping.namenullable string
  Recipient name.
  source.source_order.shipping.phonenullable string
  Recipient phone (including extension).
  source.source_order.shipping.tracking_numbernullable string
  The tracking number for a physical product, obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas.

source.statement_descriptornullable string
Extra information about a source. This will appear on your customer’s statement every time you charge the source.

source.statusstring
The status of the source, one of canceled, chargeable, consumed, failed, or pending. Only chargeable sources can be used to create a charge.

source.typeenum
The type of the source. The type is a payment method, one of ach_credit_transfer, ach_debit, alipay, bancontact, card, card_present, eps, giropay, ideal, multibanco, klarna, p24, sepa_debit, sofort, three_d_secure, or wechat. An additional hash is included on the source with a name matching this value. It contains additional information specific to the payment method used.
Possible enum values
ach_credit_transfer
ach_debit
alipay
bancontact
card
card_present
eps
giropay
ideal
klarna
Show 6 more

source.usagenullable string
Either reusable or single_use. Whether this source should be reusable or not. Some source types may or may not be reusable by construction, while others may leave the option at creation. If an incompatible value is passed, an error will be returned.

statement_descriptornullable string
Extra information about a top-up. This will appear on your source’s bank statement. It must contain at least one letter.

transfer_groupnullable string
A string that identifies this top-up as part of a group.

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
}

The Top-up object

Attributes

idstring

amountinteger

currencystring

descriptionnullable string

metadataobject

statusenum

More attributesCollapse all

objectstring

balance_transactionnullable stringExpandable

createdtimestamp

expected_availability_datenullable integer

failure_codenullable string

failure_messagenullable string

livemodeboolean

sourcenullable objectDeprecated

source.idstring

source.objectstring

source.allow_redisplaynullable enum

source.amountnullable integer

source.client_secretstring

source.code_verificationnullable object

source.code_verification.attempts_remaininginteger

source.code_verification.statusstring

source.createdtimestamp

source.currencynullable enum

source.customernullable string

source.flowstring

source.livemodeboolean

source.metadatanullable object

source.ownernullable object

source.owner.addressnullable object

source.owner.address.citynullable string

source.owner.address.countrynullable string

source.owner.address.line1nullable string

source.owner.address.line2nullable string

source.owner.address.postal_codenullable string

source.owner.address.statenullable string

source.owner.emailnullable string

source.owner.namenullable string

source.owner.phonenullable string

source.owner.verified_addressnullable object

source.owner.verified_address.citynullable string

source.owner.verified_address.countrynullable string

source.owner.verified_address.line1nullable string

source.owner.verified_address.line2nullable string

source.owner.verified_address.postal_codenullable string

source.owner.verified_address.statenullable string

source.owner.verified_emailnullable string

source.owner.verified_namenullable string

source.owner.verified_phonenullable string

source.receivernullable object

source.receiver.addressnullable string

source.receiver.amount_chargedinteger

source.receiver.amount_receivedinteger

source.receiver.amount_returnedinteger

source.receiver.refund_attributes_methodstring

source.receiver.refund_attributes_statusstring

source.redirectnullable object

source.redirect.failure_reasonnullable string

source.redirect.return_urlstring

source.redirect.statusstring

source.redirect.urlstring

source.source_ordernullable object

source.source_order.amountinteger

source.source_order.currencyenum

source.source_order.emailnullable string

source.source_order.itemsnullable array of objects

source.source_order.items.amountnullable integer

source.source_order.items.currencynullable string

source.source_order.items.descriptionnullable string

source.source_order.items.parentnullable string

source.source_order.items.quantitynullable integer

source.source_order.items.typenullable string

source.source_order.shippingnullable object

source.source_order.shipping.addressnullable object

source.source_order.shipping.address.citynullable string

source.source_order.shipping.address.countrynullable string

source.source_order.shipping.address.line1nullable string

More attributes