API reference

Test Helpers

Knox answers these operations with the same requests and responses as Stripe's API. Authenticate with your secret key, Authorization: Bearer sk_test_..., from your server, and send form-encoded bodies. Test mode only: live processing is currently disabled.

Create a test Confirmation Token

POST/v1/test_helpers/confirmation_tokens

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

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • payment_methodstring

    ID of an existing PaymentMethod.

  • payment_method_dataobject

    If provided, this hash will be used to create a PaymentMethod.

    Show 59 child parameters
    • typestringRequired
      Possible values
      • acss_debit
      • affirm
      • afterpay_clearpay
      • alipay
      • alma
      • amazon_pay
      • au_becs_debit
      • bacs_debit
      • bancontact
      • billie
      • bizum
      • blik
      • boleto
      • cashapp
      • crypto
      • customer_balance
      • and 37 more
    • acss_debitobject
      Show 3 child parameters
      • account_numberstringRequired
      • institution_numberstringRequired
      • transit_numberstringRequired
    • affirmobject
    • afterpay_clearpayobject
    • alipayobject
    • allow_redisplaystring
      Possible values
      • always
      • limited
      • unspecified
    • almaobject
    • amazon_payobject
    • au_becs_debitobject
      Show 2 child parameters
      • account_numberstringRequired
      • bsb_numberstringRequired
    • bacs_debitobject
      Show 2 child parameters
      • account_numberstring
      • sort_codestring
    • bancontactobject
    • billieobject
    • billing_detailsobject
      Show 5 child parameters
      • addressobject

        Child parameters are listed in the OpenAPI document.

      • emailstring
      • namestring
      • phonestring
      • tax_idstring
    • bizumobject
    • blikobject
    • boletoobject
      Show 1 child parameter
      • tax_idstringRequired
    • cashappobject
    • cryptoobject
    • customer_balanceobject
    • epsobject
      Show 1 child parameter
      • bankstring
        Possible values
        • arzte_und_apotheker_bank
        • austrian_anadi_bank_ag
        • bank_austria
        • bankhaus_carl_spangler
        • bankhaus_schelhammer_und_schattera_ag
        • bawag_psk_ag
        • bks_bank_ag
        • brull_kallmus_bank_ag
        • btv_vier_lander_bank
        • capital_bank_grawe_gruppe_ag
        • deutsche_bank_ag
        • dolomitenbank
        • easybank_ag
        • erste_bank_und_sparkassen
        • hypo_alpeadriabank_international_ag
        • hypo_bank_burgenland_aktiengesellschaft
        • and 12 more
    • fpxobject
      Show 1 child parameter
      • bankstringRequired
        Possible values
        • affin_bank
        • agrobank
        • alliance_bank
        • ambank
        • bank_islam
        • bank_muamalat
        • bank_of_china
        • bank_rakyat
        • bnp_paribas
        • bsn
        • cimb
        • citibank
        • deutsche_bank
        • hong_leong_bank
        • hsbc
        • kfh
        • and 9 more
    • giropayobject
    • grabpayobject
    • idealobject
      Show 1 child parameter
      • bankstring
        Possible values
        • abn_amro
        • adyen
        • asn_bank
        • bunq
        • buut
        • finom
        • handelsbanken
        • ing
        • knab
        • mollie
        • moneyou
        • n26
        • nn
        • rabobank
        • regiobank
        • revolut
        • and 4 more
    • interac_presentobject
    • kakao_payobject
    • klarnaobject
      Show 1 child parameter
    • konbiniobject
    • kr_cardobject
    • linkobject
    • mb_wayobject
    • metadataobject
    • mobilepayobject
    • multibancoobject
    • naver_payobject
      Show 1 child parameter
      • fundingstring
        Possible values
        • card
        • points
    • nz_bank_accountobject
      Show 6 child parameters
      • account_numberstringRequired
      • bank_codestringRequired
      • branch_codestringRequired
      • suffixstringRequired
      • account_holder_namestring
      • referencestring
    • oxxoobject
    • p24object
      Show 1 child parameter
      • bankstring
        Possible values
        • alior_bank
        • bank_millennium
        • bank_nowy_bfg_sa
        • bank_pekao_sa
        • banki_spbdzielcze
        • blik
        • bnp_paribas
        • boz
        • citi_handlowy
        • credit_agricole
        • envelobank
        • etransfer_pocztowy24
        • getin_bank
        • ideabank
        • ing
        • inteligo
        • and 10 more
    • pay_by_bankobject
    • paycoobject
    • paynowobject
    • paypalobject
    • paytoobject
      Show 3 child parameters
      • account_numberstring
      • bsb_numberstring
      • pay_idstring
    • pixobject
    • promptpayobject
    • radar_optionsobject
      Show 1 child parameter
      • sessionstring
    • revolut_payobject
    • samsung_payobject
    • satispayobject
    • scalapayobject
    • sepa_debitobject
      Show 1 child parameter
      • ibanstringRequired
    • sofortobject
      Show 1 child parameter
      • countrystringRequired
        Possible values
        • AT
        • BE
        • DE
        • ES
        • IT
        • NL
    • sunbitobject
    • swishobject
    • twintobject
    • upiobject
      Show 1 child parameter
    • us_bank_accountobject
      Show 5 child parameters
      • account_holder_typestring
        Possible values
        • company
        • individual
      • account_numberstring
      • account_typestring
        Possible values
        • checking
        • savings
      • financial_connections_accountstring
      • routing_numberstring
    • wechat_payobject
    • zipobject
  • payment_method_optionsobject

    Payment-method-specific configuration for this ConfirmationToken.

    Show 1 child parameter
    • cardobject
      Show 1 child parameter
  • return_urlstring

    Return URL used to confirm the Intent.

  • setup_future_usagestring

    Indicates that you intend to make future payments with this ConfirmationToken's payment method. The presence of this property will attach the payment method to the PaymentIntent's Customer, if present, after the PaymentIntent is confirmed and any required actions from the user are complete.

    Possible values
    • off_session
    • on_session
  • shippingobject

    Shipping information for this ConfirmationToken.

    Show 3 child parameters
    • addressobjectRequired
      Show 6 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
    • namestringRequired
    • phonestring

Returns

The confirmation_token object.

POST /v1/test_helpers/confirmation_tokens
curl -X POST https://api.knoxapi.com/v1/test_helpers/confirmation_tokens \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "created": 1234567890,
  "expires_at": 1234567890,
  "id": "ctoken_1Pgc73B7WZ01zgkWgFXpfTtv",
  "livemode": true,
  "mandate_data": {
    "customer_acceptance": {
      "online": {
        "ip_address": null,
        "user_agent": null
      },
      "type": "type"
    }
  },
  "object": "confirmation_token",
  "payment_intent": null,
  "payment_method_options": {
    "card": {
      "cvc_token": null
    }
  },
  "payment_method_preview": {
    "allow_redisplay": "unspecified",
    "billing_details": {
      "address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "1234 Fake Street",
        "line2": null,
        "postal_code": "94102",
        "state": "CA"
      },
      "email": null,
      "name": "Jane Austen",
      "phone": null,
      "tax_id": null
    },
    "customer": null,
    "type": "us_bank_account",
    "us_bank_account": {
      "account_holder_type": "company",
      "account_type": "checking",
      "bank_name": "STRIPE TEST BANK",
      "financial_connections_account": null,
      "fingerprint": "AuoSJ18zsVWV9SPc",
      "last4": "6789",
      "networks": {
        "preferred": "ach",
        "supported": [
          "ach"
        ]
      },
      "routing_number": "110000000",
      "status_details": {}
    },
    "customer_account": null
  },
  "return_url": "https://example.com/return",
  "setup_future_usage": "off_session",
  "setup_intent": null,
  "shipping": {
    "address": {
      "city": "San Francisco",
      "country": "US",
      "line1": "1234 Fake Street",
      "line2": null,
      "postal_code": "94102",
      "state": "CA"
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "use_stripe_sdk": true,
  "metadata": null
}

Create a test clock

POST/v1/test_helpers/test_clocks

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

Body parameters

  • frozen_timeintegerRequired

    The initial frozen time for this test clock.

  • customerstring

    Existing customer this test clock will be attached to. Once attached, customers can't be removed from a test clock.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • namestring

    The name for this test clock.

Returns

The test_helpers.test_clock object.

POST /v1/test_helpers/test_clocks
curl https://api.knoxapi.com/v1/test_helpers/test_clocks \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d frozen_time=1234567890
Response
{
  "created": 1234567890,
  "deletes_after": 1234567890,
  "frozen_time": 1234567890,
  "id": "clock_1Pgc6yB7WZ01zgkWVlemIOED",
  "livemode": false,
  "name": null,
  "object": "test_helpers.test_clock",
  "status": "ready",
  "status_details": {}
}

List all test clocks

GET/v1/test_helpers/test_clocks

Returns a list of your test clocks.

Query parameters

  • ending_beforestring

    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.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • starting_afterstring

    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.

Returns

A list of test_helpers.test_clock objects.

GET /v1/test_helpers/test_clocks
curl -G https://api.knoxapi.com/v1/test_helpers/test_clocks \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/test_helpers/test_clocks",
  "has_more": false,
  "data": [
    {
      "created": 1234567890,
      "deletes_after": 1234567890,
      "frozen_time": 1234567890,
      "id": "clock_1Pgc6yB7WZ01zgkWVlemIOED",
      "livemode": false,
      "name": null,
      "object": "test_helpers.test_clock",
      "status": "ready",
      "status_details": {}
    }
  ]
}

Retrieve a test clock

GET/v1/test_helpers/test_clocks/{test_clock}

Retrieves a test clock.

Path parameters

  • test_clockstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The test_helpers.test_clock object.

GET /v1/test_helpers/test_clocks/{test_clock}
curl https://api.knoxapi.com/v1/test_helpers/test_clocks/clock_1Pgc6yB7WZ01zgkWVlemIOED \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "created": 1234567890,
  "deletes_after": 1234567890,
  "frozen_time": 1234567890,
  "id": "clock_1Pgc6yB7WZ01zgkWVlemIOED",
  "livemode": false,
  "name": null,
  "object": "test_helpers.test_clock",
  "status": "ready",
  "status_details": {}
}

Delete a test clock

DELETE/v1/test_helpers/test_clocks/{test_clock}

Deletes a test clock.

Path parameters

  • test_clockstringRequired

Returns

The deleted_test_helpers.test_clock object.

DELETE /v1/test_helpers/test_clocks/{test_clock}
curl -X DELETE https://api.knoxapi.com/v1/test_helpers/test_clocks/clock_1Pgc6yB7WZ01zgkWVlemIOED \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "deleted": true,
  "id": "clock_1Pgc6yB7WZ01zgkWVlemIOED",
  "object": "test_helpers.test_clock"
}

Fund a test mode cash balance

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

Create an incoming testmode bank transfer

Path parameters

  • customerstringRequired

Body parameters

  • amountintegerRequired

    Amount to be used for this test cash balance transaction. A positive integer representing how much to fund in the smallest currency unit (e.g., 100 cents to fund $1.00 or 100 to fund ¥100, a zero-decimal currency).

  • currencystringRequired

    Three-letter ISO currency code, in lowercase. Must be a supported currency.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • referencestring

    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 applies to different user inputs.

Returns

The customer_cash_balance_transaction object.

POST /v1/test_helpers/customers/{customer}/fund_cash_balance
curl https://api.knoxapi.com/v1/test_helpers/customers/cus_QXg1o8vcGmoR32/fund_cash_balance \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d amount=1000 \
  -d currency=eur
Response
{
  "created": 1234567890,
  "currency": "eur",
  "customer": "cus_QXg1o8vcGmoR32",
  "ending_balance": 10000,
  "funded": {
    "bank_transfer": {
      "eu_bank_transfer": {
        "bic": "BANKDEAAXXX",
        "iban_last4": "7089",
        "sender_name": "Sample Business GmbH"
      },
      "reference": "Payment for Invoice 7FE1103-155",
      "type": "eu_bank_transfer"
    }
  },
  "id": "ccsbtxn_1Pgc75B7WZ01zgkWzdJj4ufI",
  "livemode": false,
  "net_amount": 5000,
  "object": "customer_cash_balance_transaction",
  "type": "funded",
  "customer_account": null
}

Expire a pending refund.

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

Expire a refund with a status of requires_action.

Path parameters

  • refundstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The refund object.

POST /v1/test_helpers/refunds/{refund}/expire
curl -X POST https://api.knoxapi.com/v1/test_helpers/refunds/re_1Pgc72B7WZ01zgkWqPvrRrPE/expire \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_1PgafuB7WZ01zgkWXYmPNZs8",
  "created": 1234567890,
  "currency": "usd",
  "destination_details": {
    "card": {
      "type": "reversal"
    },
    "type": "card"
  },
  "id": "re_1Pgc72B7WZ01zgkWqPvrRrPE",
  "metadata": {},
  "object": "refund",
  "payment_intent": null,
  "reason": null,
  "receipt_number": null,
  "source_transfer_reversal": null,
  "status": "succeeded",
  "transfer_reversal": null,
  "customer": null,
  "customer_account": null,
  "payment_method": null
}

Advance a test clock

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

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

Path parameters

  • test_clockstringRequired

Body parameters

  • frozen_timeintegerRequired

    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.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The test_helpers.test_clock object.

POST /v1/test_helpers/test_clocks/{test_clock}/advance
curl https://api.knoxapi.com/v1/test_helpers/test_clocks/clock_1Pgc6yB7WZ01zgkWVlemIOED/advance \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d frozen_time=1234567890
Response
{
  "created": 1234567890,
  "deletes_after": 1234567890,
  "frozen_time": 1234567890,
  "id": "clock_1Pgc6yB7WZ01zgkWVlemIOED",
  "livemode": false,
  "name": null,
  "object": "test_helpers.test_clock",
  "status": "ready",
  "status_details": {}
}

Simulate presenting a payment method

POST/v1/test_helpers/terminal/readers/{reader}/present_payment_method

Presents a payment method on a simulated reader. Can be used to simulate accepting a payment, saving a card or refunding a transaction.

Path parameters

  • readerstringRequired

Body parameters

  • amount_tipinteger

    Simulated on-reader tip amount.

  • cardobject

    Simulated data for the card payment method.

    Show 4 child parameters
    • exp_monthintegerRequired
    • exp_yearintegerRequired
    • numberstringRequired
    • cvcstring
  • card_presentobject

    Simulated data for the card_present payment method.

    Show 1 child parameter
    • numberstring
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • interac_presentobject

    Simulated data for the interac_present payment method.

    Show 1 child parameter
    • numberstring
  • typestring

    Simulated payment type.

    Possible values
    • card
    • card_present
    • interac_present

Returns

The terminal.reader object.

POST /v1/test_helpers/terminal/readers/{reader}/present_payment_method
curl -X POST https://api.knoxapi.com/v1/test_helpers/terminal/readers/tmr_iGOgDOlmFAot3zIp2JzEqXYs/present_payment_method \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "action": {
    "failure_code": null,
    "failure_message": null,
    "status": "failed",
    "type": "refund_payment",
    "api_error": {
      "type": "idempotency_error"
    }
  },
  "device_sw_version": null,
  "device_type": "bbpos_wisepos_e",
  "id": "tmr_iGOgDOlmFAot3zIp2JzEqXYs",
  "ip_address": "192.168.2.2",
  "label": "Blue Rabbit",
  "livemode": false,
  "location": null,
  "metadata": {},
  "object": "terminal.reader",
  "serial_number": "123-456-789",
  "status": "online",
  "last_seen_at": null
}

Simulate a successful input collection

POST/v1/test_helpers/terminal/readers/{reader}/succeed_input_collection

Use this endpoint to trigger a successful input collection on a simulated reader.

Path parameters

  • readerstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • skip_non_required_inputsstring

    This parameter defines the skip behavior for input collection.

    Possible values
    • all
    • none

Returns

The terminal.reader object.

POST /v1/test_helpers/terminal/readers/{reader}/succeed_input_collection
curl -X POST https://api.knoxapi.com/v1/test_helpers/terminal/readers/tmr_iGOgDOlmFAot3zIp2JzEqXYs/succeed_input_collection \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "action": {
    "failure_code": null,
    "failure_message": null,
    "status": "failed",
    "type": "refund_payment",
    "api_error": {
      "type": "idempotency_error"
    }
  },
  "device_sw_version": null,
  "device_type": "bbpos_wisepos_e",
  "id": "tmr_iGOgDOlmFAot3zIp2JzEqXYs",
  "ip_address": "192.168.2.2",
  "label": "Blue Rabbit",
  "livemode": false,
  "location": null,
  "metadata": {},
  "object": "terminal.reader",
  "serial_number": "123-456-789",
  "status": "online",
  "last_seen_at": null
}

Simulate an input collection timeout

POST/v1/test_helpers/terminal/readers/{reader}/timeout_input_collection

Use this endpoint to complete an input collection with a timeout error on a simulated reader.

Path parameters

  • readerstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The terminal.reader object.

POST /v1/test_helpers/terminal/readers/{reader}/timeout_input_collection
curl -X POST https://api.knoxapi.com/v1/test_helpers/terminal/readers/tmr_iGOgDOlmFAot3zIp2JzEqXYs/timeout_input_collection \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "action": {
    "failure_code": null,
    "failure_message": null,
    "status": "failed",
    "type": "refund_payment",
    "api_error": {
      "type": "idempotency_error"
    }
  },
  "device_sw_version": null,
  "device_type": "bbpos_wisepos_e",
  "id": "tmr_iGOgDOlmFAot3zIp2JzEqXYs",
  "ip_address": "192.168.2.2",
  "label": "Blue Rabbit",
  "livemode": false,
  "location": null,
  "metadata": {},
  "object": "terminal.reader",
  "serial_number": "123-456-789",
  "status": "online",
  "last_seen_at": 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.