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.

GET /v1/payment_records

List Payment Records

List all the Payment Records for a given merchant.

Request parameters

Parameter	Location	Type	Description
`created_after`	query	integer	Only return Payment Records that were created after this unix timestamp.
`created_before`	query	integer	Only return Payment Records that were created before this unix timestamp.
`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 payment_record
`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/payment_records/report_payment

Report a payment

Report a new Payment Record. You may report a Payment Record as it is initialized and later report updates through the other report_* methods, or report Payment Records in a terminal state directly, through this method.

Request parameters

Field	Type	Description
`amount_requested` required	object	The amount you initially requested for this payment.
`customer_details`	object	Customer information for this payment.
`customer_presence`	string	Indicates whether the customer was present in your checkout flow during this payment.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`expand`	array of string	Specifies which fields in the response should be expanded.
`failed`	object	Information about the payment attempt failure.
`guaranteed`	object	Information about the payment attempt guarantee.
`initiated_at` required	integer	When the reported payment was initiated. Measured in seconds since the Unix epoch.
`metadata`	one of multiple schemas	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`.
`outcome`	string	The outcome of the reported payment.
`payment_method_details` required	object	Information about the Payment Method debited for this payment.
`processor_details`	object	Processor information for this payment.
`shipping_details`	object	Shipping information for this payment.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	payments_primitives_payment_records_resource_amount
`amount_authorized` required	payments_primitives_payment_records_resource_amount
`amount_canceled` required	payments_primitives_payment_records_resource_amount
`amount_failed` required	payments_primitives_payment_records_resource_amount
`amount_guaranteed` required	payments_primitives_payment_records_resource_amount
`amount_refunded` required	payments_primitives_payment_records_resource_amount
`amount_requested` required	payments_primitives_payment_records_resource_amount
`application`	string	ID of the Connect application that created the PaymentRecord.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer_details`	one of multiple schemas	Customer information for this payment.
`customer_presence`	string	Indicates whether the customer was present in your checkout flow during this payment.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`id` required	string	Unique identifier for the object.
`latest_payment_attempt_record`	string	ID of the latest Payment Attempt Record attached to this Payment Record.
`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`.
`metadata` required	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.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`payment_method_details`	one of multiple schemas	Information about the Payment Method debited for this payment.
`processor_details` required	payments_primitives_payment_records_resource_processor_details
`reported_by` required	string	Indicates who reported the payment.
`shipping_details`	one of multiple schemas	Shipping information for this payment.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/payment_records/{id}

Retrieve a Payment Record

Retrieves a Payment Record with the given ID

Request parameters

Parameter	Location	Type	Description
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`id`	path	string	The ID of the Payment Record.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	payments_primitives_payment_records_resource_amount
`amount_authorized` required	payments_primitives_payment_records_resource_amount
`amount_canceled` required	payments_primitives_payment_records_resource_amount
`amount_failed` required	payments_primitives_payment_records_resource_amount
`amount_guaranteed` required	payments_primitives_payment_records_resource_amount
`amount_refunded` required	payments_primitives_payment_records_resource_amount
`amount_requested` required	payments_primitives_payment_records_resource_amount
`application`	string	ID of the Connect application that created the PaymentRecord.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer_details`	one of multiple schemas	Customer information for this payment.
`customer_presence`	string	Indicates whether the customer was present in your checkout flow during this payment.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`id` required	string	Unique identifier for the object.
`latest_payment_attempt_record`	string	ID of the latest Payment Attempt Record attached to this Payment Record.
`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`.
`metadata` required	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.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`payment_method_details`	one of multiple schemas	Information about the Payment Method debited for this payment.
`processor_details` required	payments_primitives_payment_records_resource_processor_details
`reported_by` required	string	Indicates who reported the payment.
`shipping_details`	one of multiple schemas	Shipping information for this payment.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/payment_records/{id}/report_payment_attempt

Report a payment attempt

Report a new payment attempt on the specified Payment Record. A new payment attempt can only be specified if all other payment attempts are canceled or failed.

Request parameters

Parameter	Location	Type	Description
`id`	path	string	The ID of the Payment Record.

Field	Type	Description
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`expand`	array of string	Specifies which fields in the response should be expanded.
`failed`	object	Information about the payment attempt failure.
`guaranteed`	object	Information about the payment attempt guarantee.
`initiated_at` required	integer	When the reported payment was initiated. Measured in seconds since the Unix epoch.
`metadata`	one of multiple schemas	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`.
`outcome`	string	The outcome of the reported payment.
`payment_method_details`	object	Information about the Payment Method debited for this payment.
`shipping_details`	object	Shipping information for this payment.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	payments_primitives_payment_records_resource_amount
`amount_authorized` required	payments_primitives_payment_records_resource_amount
`amount_canceled` required	payments_primitives_payment_records_resource_amount
`amount_failed` required	payments_primitives_payment_records_resource_amount
`amount_guaranteed` required	payments_primitives_payment_records_resource_amount
`amount_refunded` required	payments_primitives_payment_records_resource_amount
`amount_requested` required	payments_primitives_payment_records_resource_amount
`application`	string	ID of the Connect application that created the PaymentRecord.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer_details`	one of multiple schemas	Customer information for this payment.
`customer_presence`	string	Indicates whether the customer was present in your checkout flow during this payment.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`id` required	string	Unique identifier for the object.
`latest_payment_attempt_record`	string	ID of the latest Payment Attempt Record attached to this Payment Record.
`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`.
`metadata` required	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.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`payment_method_details`	one of multiple schemas	Information about the Payment Method debited for this payment.
`processor_details` required	payments_primitives_payment_records_resource_processor_details
`reported_by` required	string	Indicates who reported the payment.
`shipping_details`	one of multiple schemas	Shipping information for this payment.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/payment_records/{id}/report_payment_attempt_canceled

Report payment attempt canceled

Report that the most recent payment attempt on the specified Payment Record was canceled.

Request parameters

Parameter	Location	Type	Description
`id`	path	string	The ID of the Payment Record.

Field	Type	Description
`canceled_at` required	integer	When the reported payment was canceled. Measured in seconds since the Unix epoch.
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	one of multiple schemas	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`.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	payments_primitives_payment_records_resource_amount
`amount_authorized` required	payments_primitives_payment_records_resource_amount
`amount_canceled` required	payments_primitives_payment_records_resource_amount
`amount_failed` required	payments_primitives_payment_records_resource_amount
`amount_guaranteed` required	payments_primitives_payment_records_resource_amount
`amount_refunded` required	payments_primitives_payment_records_resource_amount
`amount_requested` required	payments_primitives_payment_records_resource_amount
`application`	string	ID of the Connect application that created the PaymentRecord.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer_details`	one of multiple schemas	Customer information for this payment.
`customer_presence`	string	Indicates whether the customer was present in your checkout flow during this payment.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`id` required	string	Unique identifier for the object.
`latest_payment_attempt_record`	string	ID of the latest Payment Attempt Record attached to this Payment Record.
`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`.
`metadata` required	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.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`payment_method_details`	one of multiple schemas	Information about the Payment Method debited for this payment.
`processor_details` required	payments_primitives_payment_records_resource_processor_details
`reported_by` required	string	Indicates who reported the payment.
`shipping_details`	one of multiple schemas	Shipping information for this payment.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/payment_records/{id}/report_payment_attempt_failed

Report payment attempt failed

Report that the most recent payment attempt on the specified Payment Record failed or errored.

Request parameters

Parameter	Location	Type	Description
`id`	path	string	The ID of the Payment Record.

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.
`failed_at` required	integer	When the reported payment failed. Measured in seconds since the Unix epoch.
`metadata`	one of multiple schemas	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`.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	payments_primitives_payment_records_resource_amount
`amount_authorized` required	payments_primitives_payment_records_resource_amount
`amount_canceled` required	payments_primitives_payment_records_resource_amount
`amount_failed` required	payments_primitives_payment_records_resource_amount
`amount_guaranteed` required	payments_primitives_payment_records_resource_amount
`amount_refunded` required	payments_primitives_payment_records_resource_amount
`amount_requested` required	payments_primitives_payment_records_resource_amount
`application`	string	ID of the Connect application that created the PaymentRecord.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer_details`	one of multiple schemas	Customer information for this payment.
`customer_presence`	string	Indicates whether the customer was present in your checkout flow during this payment.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`id` required	string	Unique identifier for the object.
`latest_payment_attempt_record`	string	ID of the latest Payment Attempt Record attached to this Payment Record.
`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`.
`metadata` required	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.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`payment_method_details`	one of multiple schemas	Information about the Payment Method debited for this payment.
`processor_details` required	payments_primitives_payment_records_resource_processor_details
`reported_by` required	string	Indicates who reported the payment.
`shipping_details`	one of multiple schemas	Shipping information for this payment.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/payment_records/{id}/report_payment_attempt_guaranteed

Report payment attempt guaranteed

Report that the most recent payment attempt on the specified Payment Record was guaranteed.

Request parameters

Parameter	Location	Type	Description
`id`	path	string	The ID of the Payment Record.

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.
`guaranteed_at` required	integer	When the reported payment was guaranteed. Measured in seconds since the Unix epoch.
`metadata`	one of multiple schemas	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`.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	payments_primitives_payment_records_resource_amount
`amount_authorized` required	payments_primitives_payment_records_resource_amount
`amount_canceled` required	payments_primitives_payment_records_resource_amount
`amount_failed` required	payments_primitives_payment_records_resource_amount
`amount_guaranteed` required	payments_primitives_payment_records_resource_amount
`amount_refunded` required	payments_primitives_payment_records_resource_amount
`amount_requested` required	payments_primitives_payment_records_resource_amount
`application`	string	ID of the Connect application that created the PaymentRecord.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer_details`	one of multiple schemas	Customer information for this payment.
`customer_presence`	string	Indicates whether the customer was present in your checkout flow during this payment.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`id` required	string	Unique identifier for the object.
`latest_payment_attempt_record`	string	ID of the latest Payment Attempt Record attached to this Payment Record.
`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`.
`metadata` required	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.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`payment_method_details`	one of multiple schemas	Information about the Payment Method debited for this payment.
`processor_details` required	payments_primitives_payment_records_resource_processor_details
`reported_by` required	string	Indicates who reported the payment.
`shipping_details`	one of multiple schemas	Shipping information for this payment.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/payment_records/{id}/report_payment_attempt_informational

Report payment attempt informational

Report informational updates on the specified Payment Record.

Request parameters

Parameter	Location	Type	Description
`id`	path	string	The ID of the Payment Record.

Field	Type	Description
`customer_details`	object	Customer information for this payment.
`description`	one of multiple schemas	An arbitrary string attached to the object. Often useful for displaying to users.
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	one of multiple schemas	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`.
`shipping_details`	one of multiple schemas	Shipping information for this payment.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	payments_primitives_payment_records_resource_amount
`amount_authorized` required	payments_primitives_payment_records_resource_amount
`amount_canceled` required	payments_primitives_payment_records_resource_amount
`amount_failed` required	payments_primitives_payment_records_resource_amount
`amount_guaranteed` required	payments_primitives_payment_records_resource_amount
`amount_refunded` required	payments_primitives_payment_records_resource_amount
`amount_requested` required	payments_primitives_payment_records_resource_amount
`application`	string	ID of the Connect application that created the PaymentRecord.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer_details`	one of multiple schemas	Customer information for this payment.
`customer_presence`	string	Indicates whether the customer was present in your checkout flow during this payment.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`id` required	string	Unique identifier for the object.
`latest_payment_attempt_record`	string	ID of the latest Payment Attempt Record attached to this Payment Record.
`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`.
`metadata` required	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.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`payment_method_details`	one of multiple schemas	Information about the Payment Method debited for this payment.
`processor_details` required	payments_primitives_payment_records_resource_processor_details
`reported_by` required	string	Indicates who reported the payment.
`shipping_details`	one of multiple schemas	Shipping information for this payment.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/payment_records/{id}/report_refund

Report a refund

Report that the most recent payment attempt on the specified Payment Record was refunded.

Request parameters

Parameter	Location	Type	Description
`id`	path	string	The ID of the Payment Record.

Field	Type	Description
`amount`	object	A positive integer in the [smallest currency unit](https://docs.stripe.com/currencies#zero-decimal) representing how much of this payment to refund. Can refund only up to the remaining, unrefunded amount of the payment.
`expand`	array of string	Specifies which fields in the response should be expanded.
`initiated_at`	integer	When the reported refund was initiated. Measured in seconds since the Unix epoch.
`metadata`	one of multiple schemas	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`.
`outcome` required	string	The outcome of the reported refund.
`processor_details` required	object	Processor information for this refund.
`refunded`	object	Information about the payment attempt refund.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	payments_primitives_payment_records_resource_amount
`amount_authorized` required	payments_primitives_payment_records_resource_amount
`amount_canceled` required	payments_primitives_payment_records_resource_amount
`amount_failed` required	payments_primitives_payment_records_resource_amount
`amount_guaranteed` required	payments_primitives_payment_records_resource_amount
`amount_refunded` required	payments_primitives_payment_records_resource_amount
`amount_requested` required	payments_primitives_payment_records_resource_amount
`application`	string	ID of the Connect application that created the PaymentRecord.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer_details`	one of multiple schemas	Customer information for this payment.
`customer_presence`	string	Indicates whether the customer was present in your checkout flow during this payment.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`id` required	string	Unique identifier for the object.
`latest_payment_attempt_record`	string	ID of the latest Payment Attempt Record attached to this Payment Record.
`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`.
`metadata` required	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.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`payment_method_details`	one of multiple schemas	Information about the Payment Method debited for this payment.
`processor_details` required	payments_primitives_payment_records_resource_processor_details
`reported_by` required	string	Indicates who reported the payment.
`shipping_details`	one of multiple schemas	Shipping information for this payment.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors