API reference
Topups
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
https://api.knoxapi.comCreate a top-up
POST/v1/topups
Top up the balance of an account
Body parameters
amountintegerRequiredA positive integer representing how much to transfer.
currencystringRequiredThree-letter ISO currency code, in lowercase. Must be a supported currency.
descriptionstringAn arbitrary string attached to the object. Often useful for displaying to users.
expandarray of stringsSpecifies which fields in the response should be expanded.
metadataobjectSet 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.payment_methodstringThe ID of a PaymentMethod representing the payment method to be used for the top-up. A PaymentMethod of type
us_bank_accountcan be used.payment_method_optionsobjectPayment method-specific configuration for this top-up.
Show 1 child parameter
us_bank_accountobjectShow 1 child parameter
networkstringRequiredPossible valuesach
sourcestringThe 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).
statement_descriptorstringExtra information about a top-up for the source's bank statement. Limited to 15 ASCII characters.
transfer_groupstringA string that identifies this top-up as part of a group.
Returns
The topup object.
curl https://api.knoxapi.com/v1/topups \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d amount=1000 \
-d currency=usdconst Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const topup = await stripe.topups.create({
amount: 1000,
currency: 'usd',
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
topup = client.v1.topups.create(params={
"amount": 1000,
"currency": "usd",
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
topup = Stripe::Topup.create({
amount: 1000,
currency: 'usd',
}){
"amount": 1000,
"balance_transaction": null,
"created": 1234567890,
"currency": "usd",
"description": "Top-up description",
"expected_availability_date": 123456789,
"failure_code": null,
"failure_message": null,
"id": "tu_1Pgc7BB7WZ01zgkWwH7rkBgR",
"livemode": false,
"metadata": {
"order_id": "12345678"
},
"object": "topup",
"source": {
"ach_debit": {
"bank_name": "STRIPE TEST BANK",
"country": "US",
"fingerprint": "5Wh4KBcfDrz5IOnx",
"last4": "6789",
"routing_number": "110000000",
"type": "individual"
},
"amount": null,
"client_secret": "src_client_secret_9HxmifVKxP2LNNRRod7Q23HM",
"created": 1721954073,
"currency": "usd",
"flow": "code_verification",
"id": "src_1Pgc7BB7WZ01zgkWXWC57xAu",
"livemode": false,
"metadata": {},
"object": "source",
"owner": {
"address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"email": "[email protected]",
"name": "Jenny Rosen",
"phone": null,
"verified_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"verified_email": null,
"verified_name": null,
"verified_phone": null
},
"statement_descriptor": null,
"status": "pending",
"type": "ach_debit",
"usage": "reusable",
"allow_redisplay": null
},
"statement_descriptor": null,
"status": "pending",
"transfer_group": null,
"initiated_by": null
}List all top-ups
GET/v1/topups
Returns a list of top-ups.
Query parameters
amountobject | integerA positive integer representing how much to transfer.
Show 4 child parameters
gtintegergteintegerltintegerlteinteger
createdobject | integerA filter on the list, based on the object
createdfield. The value can be a string with an integer Unix timestamp, or it can be a dictionary with a number of different query options.Show 4 child parameters
gtintegergteintegerltintegerlteinteger
ending_beforestringA cursor for use in pagination.
ending_beforeis an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting withobj_bar, your subsequent call can includeending_before=obj_barin order to fetch the previous page of the list.expandarray of stringsSpecifies which fields in the response should be expanded.
limitintegerA limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
starting_afterstringA cursor for use in pagination.
starting_afteris an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending withobj_foo, your subsequent call can includestarting_after=obj_fooin order to fetch the next page of the list.statusstringOnly return top-ups that have the given status. One of
canceled,failed,pendingorsucceeded.Possible valuescanceledfailedpendingsucceeded
Returns
A list of topup objects.
curl -G https://api.knoxapi.com/v1/topups \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
--data-urlencode limit=3const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const page = await stripe.topups.list({
limit: 3,
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
page = client.v1.topups.list(params={
"limit": 3,
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
page = Stripe::Topup.list({
limit: 3,
}){
"object": "list",
"url": "/v1/topups",
"has_more": false,
"data": [
{
"amount": 1000,
"balance_transaction": null,
"created": 1234567890,
"currency": "usd",
"description": "Top-up description",
"expected_availability_date": 123456789,
"failure_code": null,
"failure_message": null,
"id": "tu_1Pgc7BB7WZ01zgkWwH7rkBgR",
"livemode": false,
"metadata": {
"order_id": "12345678"
},
"object": "topup",
"source": {
"ach_debit": {
"bank_name": "STRIPE TEST BANK",
"country": "US",
"fingerprint": "5Wh4KBcfDrz5IOnx",
"last4": "6789",
"routing_number": "110000000",
"type": "individual"
},
"amount": null,
"client_secret": "src_client_secret_9HxmifVKxP2LNNRRod7Q23HM",
"created": 1721954073,
"currency": "usd",
"flow": "code_verification",
"id": "src_1Pgc7BB7WZ01zgkWXWC57xAu",
"livemode": false,
"metadata": {},
"object": "source",
"owner": {
"address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"email": "[email protected]",
"name": "Jenny Rosen",
"phone": null,
"verified_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"verified_email": null,
"verified_name": null,
"verified_phone": null
},
"statement_descriptor": null,
"status": "pending",
"type": "ach_debit",
"usage": "reusable",
"allow_redisplay": null
},
"statement_descriptor": null,
"status": "pending",
"transfer_group": null,
"initiated_by": null
}
]
}Update a top-up
POST/v1/topups/{topup}
Updates the metadata of a top-up. Other top-up details are not editable by design.
Path parameters
topupstringRequired
Body parameters
descriptionstringAn arbitrary string attached to the object. Often useful for displaying to users.
expandarray of stringsSpecifies which fields in the response should be expanded.
metadataobjectSet 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 topup object.
curl https://api.knoxapi.com/v1/topups/tu_1Pgc7BB7WZ01zgkWwH7rkBgR \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d "metadata[order_id]=6735"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const topup = await stripe.topups.update('tu_1Pgc7BB7WZ01zgkWwH7rkBgR', {
metadata: {
order_id: '6735',
},
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
topup = client.v1.topups.update("tu_1Pgc7BB7WZ01zgkWwH7rkBgR", params={
"metadata": {
"order_id": "6735",
},
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
topup = Stripe::Topup.update('tu_1Pgc7BB7WZ01zgkWwH7rkBgR', {
metadata: {
order_id: '6735',
},
}){
"amount": 1000,
"balance_transaction": null,
"created": 1234567890,
"currency": "usd",
"description": "Top-up description",
"expected_availability_date": 123456789,
"failure_code": null,
"failure_message": null,
"id": "tu_1Pgc7BB7WZ01zgkWwH7rkBgR",
"livemode": false,
"metadata": {
"order_id": "12345678"
},
"object": "topup",
"source": {
"ach_debit": {
"bank_name": "STRIPE TEST BANK",
"country": "US",
"fingerprint": "5Wh4KBcfDrz5IOnx",
"last4": "6789",
"routing_number": "110000000",
"type": "individual"
},
"amount": null,
"client_secret": "src_client_secret_9HxmifVKxP2LNNRRod7Q23HM",
"created": 1721954073,
"currency": "usd",
"flow": "code_verification",
"id": "src_1Pgc7BB7WZ01zgkWXWC57xAu",
"livemode": false,
"metadata": {},
"object": "source",
"owner": {
"address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"email": "[email protected]",
"name": "Jenny Rosen",
"phone": null,
"verified_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"verified_email": null,
"verified_name": null,
"verified_phone": null
},
"statement_descriptor": null,
"status": "pending",
"type": "ach_debit",
"usage": "reusable",
"allow_redisplay": null
},
"statement_descriptor": null,
"status": "pending",
"transfer_group": null,
"initiated_by": null
}Retrieve a top-up
GET/v1/topups/{topup}
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.
Path parameters
topupstringRequired
Query parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The topup object.
curl https://api.knoxapi.com/v1/topups/tu_1Pgc7BB7WZ01zgkWwH7rkBgR \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const topup = await stripe.topups.retrieve('tu_1Pgc7BB7WZ01zgkWwH7rkBgR');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
topup = client.v1.topups.retrieve("tu_1Pgc7BB7WZ01zgkWwH7rkBgR")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
topup = Stripe::Topup.retrieve('tu_1Pgc7BB7WZ01zgkWwH7rkBgR'){
"amount": 1000,
"balance_transaction": null,
"created": 1234567890,
"currency": "usd",
"description": "Top-up description",
"expected_availability_date": 123456789,
"failure_code": null,
"failure_message": null,
"id": "tu_1Pgc7BB7WZ01zgkWwH7rkBgR",
"livemode": false,
"metadata": {
"order_id": "12345678"
},
"object": "topup",
"source": {
"ach_debit": {
"bank_name": "STRIPE TEST BANK",
"country": "US",
"fingerprint": "5Wh4KBcfDrz5IOnx",
"last4": "6789",
"routing_number": "110000000",
"type": "individual"
},
"amount": null,
"client_secret": "src_client_secret_9HxmifVKxP2LNNRRod7Q23HM",
"created": 1721954073,
"currency": "usd",
"flow": "code_verification",
"id": "src_1Pgc7BB7WZ01zgkWXWC57xAu",
"livemode": false,
"metadata": {},
"object": "source",
"owner": {
"address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"email": "[email protected]",
"name": "Jenny Rosen",
"phone": null,
"verified_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"verified_email": null,
"verified_name": null,
"verified_phone": null
},
"statement_descriptor": null,
"status": "pending",
"type": "ach_debit",
"usage": "reusable",
"allow_redisplay": null
},
"statement_descriptor": null,
"status": "pending",
"transfer_group": null,
"initiated_by": null
}Cancel a top-up
POST/v1/topups/{topup}/cancel
Cancels a top-up. Only pending top-ups can be canceled.
Path parameters
topupstringRequired
Body parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The topup object.
curl -X POST https://api.knoxapi.com/v1/topups/tu_1Pgc7BB7WZ01zgkWwH7rkBgR/cancel \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const topup = await stripe.topups.cancel('tu_1Pgc7BB7WZ01zgkWwH7rkBgR');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
topup = client.v1.topups.cancel("tu_1Pgc7BB7WZ01zgkWwH7rkBgR")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
topup = Stripe::Topup.cancel('tu_1Pgc7BB7WZ01zgkWwH7rkBgR'){
"amount": 1000,
"balance_transaction": null,
"created": 1234567890,
"currency": "usd",
"description": "Top-up description",
"expected_availability_date": 123456789,
"failure_code": null,
"failure_message": null,
"id": "tu_1Pgc7BB7WZ01zgkWwH7rkBgR",
"livemode": false,
"metadata": {
"order_id": "12345678"
},
"object": "topup",
"source": {
"ach_debit": {
"bank_name": "STRIPE TEST BANK",
"country": "US",
"fingerprint": "5Wh4KBcfDrz5IOnx",
"last4": "6789",
"routing_number": "110000000",
"type": "individual"
},
"amount": null,
"client_secret": "src_client_secret_9HxmifVKxP2LNNRRod7Q23HM",
"created": 1721954073,
"currency": "usd",
"flow": "code_verification",
"id": "src_1Pgc7BB7WZ01zgkWXWC57xAu",
"livemode": false,
"metadata": {},
"object": "source",
"owner": {
"address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"email": "[email protected]",
"name": "Jenny Rosen",
"phone": null,
"verified_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"verified_email": null,
"verified_name": null,
"verified_phone": null
},
"statement_descriptor": null,
"status": "pending",
"type": "ach_debit",
"usage": "reusable",
"allow_redisplay": null
},
"statement_descriptor": null,
"status": "pending",
"transfer_group": null,
"initiated_by": null
}Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.