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

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
    }
  ]
}

Cancel a top-up 

Cancels a top-up. Only pending top-ups can be canceled.

Parameters

No parameters.

Returns

Returns the canceled top-up. If the top-up is already canceled or can’t be canceled, an error is returned.

POST /v1/topups/:id/cancel
curl -X POST https://api.stripe.com/v1/topups/tu_1NG6yj2eZvKYlo2C1FOBiHya/cancel \
  -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": "canceled",
  "transfer_group": null
}

Transfers 

A Transfer object is created when you move funds between Stripe accounts as part of Connect.

Before April 6, 2017, transfers also represented movement of funds from a Stripe account to a card or bank account. This behavior has since been split out into a Payout object, with corresponding payout endpoints. For more information, read about the transfer/payout split.

Related guide: Creating separate charges and transfers

Endpoints

Transfer Reversals 

Stripe Connect platforms can reverse transfers made to a connected account, either entirely or partially, and can also specify whether to refund any related application fees. Transfer reversals add to the platform’s balance and subtract from the destination account’s balance.

Reversing a transfer that was made for a destination charge is allowed only up to the amount of the charge. It is possible to reverse a transfer_group transfer only if the destination account has enough balance to cover the reversal.

Related guide: Reverse transfers

Endpoints