API reference

Test mode. Use your secret key on your server; live processing is currently disabled.

https://api.knoxapi.com

Send form-encoded requests with Authorization: Bearer sk_test_....

Complete OpenAPI specification · Integration guide

Operations and schemas are based on the pinned Stripe OpenAPI specification (MIT). Nested object definitions and enums are available in the complete specification.

POST /v1/test_helpers/confirmation_tokens

Create a test Confirmation Token

Creates a test mode Confirmation Token server side for your integration tests.

Request parameters

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.
`payment_method`	string	ID of an existing PaymentMethod.
`payment_method_data`	object	If provided, this hash will be used to create a PaymentMethod.
`payment_method_options`	object	Payment-method-specific configuration for this ConfirmationToken.
`return_url`	string	Return URL used to confirm the Intent.
`setup_future_usage`	string	Indicates that you intend to make future payments with this ConfirmationToken's payment method. The presence of this property will [attach the payment method](https://docs.stripe.com/payments/save-during-payment) to the PaymentIntent's Customer, if present, after the PaymentIntent is confirmed and any required actions from the user are complete.
`shipping`	object	Shipping information for this ConfirmationToken.

Responses

HTTP 200: Successful response.

Field	Type	Description
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`expires_at`	integer	Time at which this ConfirmationToken expires and can no longer be used to confirm a PaymentIntent or SetupIntent.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`mandate_data`	one of multiple schemas	Data used for generating a Mandate.
`metadata`	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.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`payment_intent`	string	ID of the PaymentIntent that this ConfirmationToken was used to confirm, or null if this ConfirmationToken has not yet been used.
`payment_method_options`	one of multiple schemas	Payment-method-specific configuration for this ConfirmationToken.
`payment_method_preview`	one of multiple schemas	Payment details collected by the Payment Element, used to create a PaymentMethod when a PaymentIntent or SetupIntent is confirmed with this ConfirmationToken.
`return_url`	string	Return URL used to confirm the Intent.
`setup_future_usage`	string	Indicates that you intend to make future payments with this ConfirmationToken's payment method. The presence of this property will [attach the payment method](https://docs.stripe.com/payments/save-during-payment) to the PaymentIntent's Customer, if present, after the PaymentIntent is confirmed and any required actions from the user are complete.
`setup_intent`	string	ID of the SetupIntent that this ConfirmationToken was used to confirm, or null if this ConfirmationToken has not yet been used.
`shipping`	one of multiple schemas	Shipping information collected on this ConfirmationToken.
`use_stripe_sdk` required	boolean	Indicates whether the Stripe SDK is used to handle confirmation flow. Defaults to `true` on ConfirmationToken.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/test_helpers/test_clocks

List all test clocks

Returns a list of your test clocks.

Request parameters

Parameter	Location	Type	Description
`ending_before`	query	string	A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of test_helpers.test_clock
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/test_helpers/test_clocks

Create a test clock

Creates a new test clock that can be attached to new customers and quotes.

Request parameters

Field	Type	Description
`customer`	string	Existing customer this test clock will be attached to. Once attached, customers can't be removed from a test clock.
`expand`	array of string	Specifies which fields in the response should be expanded.
`frozen_time` required	integer	The initial frozen time for this test clock.
`name`	string	The name for this test clock.

Responses

HTTP 200: Successful response.

Field	Type	Description
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`deletes_after` required	integer	Time at which this clock is scheduled to auto delete.
`frozen_time` required	integer	Time at which all objects belonging to this clock are frozen.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`name`	string	The custom name supplied at creation.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status` required	string	The status of the Test Clock.
`status_details` required	billing_clocks_resource_status_details_status_details

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/test_helpers/customers/{customer}/fund_cash_balance

Fund a test mode cash balance

Create an incoming testmode bank transfer

Request parameters

Parameter	Location	Type	Description
`customer`	path	string

Field	Type	Description
`amount` required	integer	Amount to be used for this test cash balance transaction. A positive integer representing how much to fund in the [smallest currency unit](https://docs.stripe.com/currencies#zero-decimal) (e.g., 100 cents to fund $1.00 or 100 to fund ¥100, a zero-decimal currency).
`currency` required	string	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).
`expand`	array of string	Specifies which fields in the response should be expanded.
`reference`	string	A description of the test funding. This simulates free-text references supplied by customers when making bank transfers to their cash balance. You can use this to test how Stripe's [reconciliation algorithm](https://docs.stripe.com/payments/customer-balance/reconciliation) applies to different user inputs.

Responses

HTTP 200: Successful response.

Field	Type	Description
`adjusted_for_overdraft`	customer_balance_resource_cash_balance_transaction_resource_adjusted_for_overdraft
`applied_to_payment`	customer_balance_resource_cash_balance_transaction_resource_applied_to_payment_transaction
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	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).
`customer` required	one of multiple schemas	The customer whose available cash balance changed as a result of this transaction.
`customer_account`	string	The ID of an Account representing a customer whose available cash balance changed as a result of this transaction.
`ending_balance` required	integer	The total available cash balance for the specified currency after this transaction was applied. Represented in the [smallest currency unit](https://docs.stripe.com/currencies#zero-decimal).
`funded`	customer_balance_resource_cash_balance_transaction_resource_funded_transaction
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`net_amount` required	integer	The amount by which the cash balance changed, represented in the [smallest currency unit](https://docs.stripe.com/currencies#zero-decimal). A positive value represents funds being added to the cash balance, a negative value represents funds being removed from the cash balance.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`refunded_from_payment`	customer_balance_resource_cash_balance_transaction_resource_refunded_from_payment_transaction
`transferred_to_balance`	customer_balance_resource_cash_balance_transaction_resource_transferred_to_balance
`type` required	string	The type of the cash balance transaction. New types may be added in future. See [Customer Balance](https://docs.stripe.com/payments/customer-balance#types) to learn more about these types.
`unapplied_from_payment`	customer_balance_resource_cash_balance_transaction_resource_unapplied_from_payment_transaction

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/test_helpers/refunds/{refund}/expire

Expire a pending refund.

Expire a refund with a status of requires_action.

Request parameters

Parameter	Location	Type	Description
`refund`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	integer	Amount, in cents (or local equivalent).
`balance_transaction`	one of multiple schemas	Balance transaction that describes the impact on your account balance.
`charge`	one of multiple schemas	ID of the charge that's refunded.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	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).
`customer`	one of multiple schemas	ID of the customer of this refund.
`customer_account`	string	ID of the account of this refund.
`description`	string	An arbitrary string attached to the object. You can use this for displaying to users (available on non-card refunds only).
`destination_details`	refund_destination_details
`failure_balance_transaction`	one of multiple schemas	After the refund fails, this balance transaction describes the adjustment made on your account balance that reverses the initial balance transaction.
`failure_reason`	string	Provides the reason for the refund failure. Possible values are: `lost_or_stolen_card`, `expired_or_canceled_card`, `charge_for_pending_refund_disputed`, `insufficient_funds`, `declined`, `merchant_request`, or `unknown`.
`id` required	string	Unique identifier for the object.
`instructions_email`	string	For payment methods without native refund support (for example, Konbini, PromptPay), provide an email address for the customer to receive refund instructions.
`metadata`	object	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.
`next_action`	refund_next_action
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`payment_intent`	one of multiple schemas	ID of the PaymentIntent that's refunded.
`payment_method`	one of multiple schemas	ID of the payment method associated with this refund.
`pending_reason`	string	Provides the reason for why the refund is pending. Possible values are: `processing`, `insufficient_funds`, or `charge_pending`.
`presentment_details`	payment_flows_payment_intent_presentment_details
`reason`	string	Reason for the refund, which is either user-provided (`duplicate`, `fraudulent`, or `requested_by_customer`) or generated by Stripe internally (`expired_uncaptured_charge`).
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this refund.
`source_transfer_reversal`	one of multiple schemas	The transfer reversal that's associated with the refund. Only present if the charge came from another Stripe account.
`status`	string	Status of the refund. This can be `pending`, `requires_action`, `succeeded`, `failed`, or `canceled`. Learn more about [failed refunds](https://docs.stripe.com/refunds#failed-refunds).
`transfer_reversal`	one of multiple schemas	This refers to the transfer reversal object if the accompanying transfer reverses. This is only applicable if the charge was created using the destination parameter.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

DELETE /v1/test_helpers/test_clocks/{test_clock}

Delete a test clock

Deletes a test clock.

Request parameters

Parameter	Location	Type	Description
`test_clock`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`deleted` required	boolean	Always true for a deleted object
`id` required	string	Unique identifier for the object.
`object` required	string	String representing the object's type. Objects of the same type share the same value.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/test_helpers/test_clocks/{test_clock}

Retrieve a test clock

Retrieves a test clock.

Request parameters

Parameter	Location	Type	Description
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`test_clock`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`deletes_after` required	integer	Time at which this clock is scheduled to auto delete.
`frozen_time` required	integer	Time at which all objects belonging to this clock are frozen.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`name`	string	The custom name supplied at creation.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status` required	string	The status of the Test Clock.
`status_details` required	billing_clocks_resource_status_details_status_details

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/test_helpers/test_clocks/{test_clock}/advance

Advance a test clock

Starts advancing a test clock to a specified time in the future. Advancement is done when status changes to Ready.

Request parameters

Parameter	Location	Type	Description
`test_clock`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.
`frozen_time` required	integer	The time to advance the test clock. Must be after the test clock's current frozen time. Cannot be more than two intervals in the future from the shortest subscription in this test clock. If there are no subscriptions in this test clock, it cannot be more than two years in the future.

Responses

HTTP 200: Successful response.

Field	Type	Description
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`deletes_after` required	integer	Time at which this clock is scheduled to auto delete.
`frozen_time` required	integer	Time at which all objects belonging to this clock are frozen.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`name`	string	The custom name supplied at creation.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status` required	string	The status of the Test Clock.
`status_details` required	billing_clocks_resource_status_details_status_details

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors