API reference

Terminal

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 Configuration

POST/v1/terminal/configurations

Creates a new Configuration object.

Body parameters

  • bbpos_wisepad3object

    An object containing device type specific settings for BBPOS WisePad 3 readers.

    Show 1 child parameter
    • splashscreenstring
  • bbpos_wisepos_eobject

    An object containing device type specific settings for BBPOS WisePOS E readers.

    Show 1 child parameter
    • splashscreenstring
  • cellularobject

    Configuration for cellular connectivity.

    Show 1 child parameter
    • enabledbooleanRequired
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • namestring

    Name of the configuration

  • offlineobject

    Configurations for collecting transactions offline.

    Show 1 child parameter
    • enabledbooleanRequired
  • reboot_windowobject

    Reboot time settings for readers. that support customized reboot time configuration.

    Show 2 child parameters
    • end_hourintegerRequired
    • start_hourintegerRequired
  • stripe_s700object

    An object containing device type specific settings for Stripe S700 readers.

    Show 1 child parameter
    • splashscreenstring
  • stripe_s710object

    An object containing device type specific settings for Stripe S710 readers.

    Show 1 child parameter
    • splashscreenstring
  • tippingobject

    Tipping configurations for readers that support on-reader tips.

    Show 21 child parameters
    • aedobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • audobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • cadobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • chfobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • czkobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • dkkobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • eurobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • gbpobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • gipobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • hkdobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • hufobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • jpyobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • mxnobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • myrobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • nokobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • nzdobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • plnobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • ronobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • sekobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • sgdobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • usdobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
  • verifone_m425object

    An object containing device type specific settings for Verifone M425 readers.

    Show 1 child parameter
    • splashscreenstring
  • verifone_p400object

    An object containing device type specific settings for Verifone P400 readers.

    Show 1 child parameter
    • splashscreenstring
  • verifone_p630object

    An object containing device type specific settings for Verifone P630 readers.

    Show 1 child parameter
    • splashscreenstring
  • verifone_ux700object

    An object containing device type specific settings for Verifone UX700 readers.

    Show 1 child parameter
    • splashscreenstring
  • verifone_v660pobject

    An object containing device type specific settings for Verifone V660p readers.

    Show 1 child parameter
    • splashscreenstring
  • wifiobject

    Configurations for connecting to a WiFi network.

    Show 4 child parameters
    • typestringRequired
      Possible values
      • enterprise_eap_peap
      • enterprise_eap_tls
      • personal_psk
    • enterprise_eap_peapobject
      Show 4 child parameters
      • passwordstringRequired
      • ssidstringRequired
      • usernamestringRequired
      • ca_certificate_filestring
    • enterprise_eap_tlsobject
      Show 5 child parameters
      • client_certificate_filestringRequired
      • private_key_filestringRequired
      • ssidstringRequired
      • ca_certificate_filestring
      • private_key_file_passwordstring
    • personal_pskobject
      Show 2 child parameters
      • passwordstringRequired
      • ssidstringRequired

Returns

The terminal.configuration object.

POST /v1/terminal/configurations
curl -X POST https://api.knoxapi.com/v1/terminal/configurations \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "bbpos_wisepos_e": {
    "splashscreen": "file_1Pgc6yB7WZ01zgkWSsAMx1We"
  },
  "id": "tmc_ElVUAjF8xXG3hj",
  "is_account_default": false,
  "livemode": false,
  "name": null,
  "object": "terminal.configuration"
}

List all Configurations

GET/v1/terminal/configurations

Returns a list of Configuration objects.

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.

  • is_account_defaultboolean

    if present, only return the account default or non-default configurations.

  • 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 terminal.configuration objects.

GET /v1/terminal/configurations
curl -G https://api.knoxapi.com/v1/terminal/configurations \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/terminal/configurations",
  "has_more": false,
  "data": [
    {
      "bbpos_wisepos_e": {
        "splashscreen": "file_1Pgc6yB7WZ01zgkWSsAMx1We"
      },
      "id": "tmc_ElVUAjF8xXG3hj",
      "is_account_default": false,
      "livemode": false,
      "name": null,
      "object": "terminal.configuration"
    }
  ]
}

Create a Connection Token

POST/v1/terminal/connection_tokens

To connect to a reader the Stripe Terminal SDK needs to retrieve a short-lived connection token from Stripe, proxied through your server. On your backend, add an endpoint that creates and returns a connection token.

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • locationstring

    The id of the location that this connection token is scoped to. If specified the connection token will only be usable with readers assigned to that location, otherwise the connection token will be usable with all readers. Note that location scoping only applies to internet-connected readers. For more details, see the docs on scoping connection tokens.

Returns

The terminal.connection_token object.

POST /v1/terminal/connection_tokens
curl -X POST https://api.knoxapi.com/v1/terminal/connection_tokens \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "object": "terminal.connection_token",
  "secret": "pst_test_iPPfmBn7kZ0gIJ4xpehqTnC"
}

Create a Location

POST/v1/terminal/locations

Creates a new Location object. For further details, including which address fields are required in each country, see the Manage locations guide.

Body parameters

  • addressobject

    The full address of the location.

    Show 6 child parameters
    • countrystringRequired
    • citystring
    • line1string
    • line2string
    • postal_codestring
    • statestring
  • address_kanaobject

    The Kana variation of the full address of the location (Japan only).

    Show 7 child parameters
    • citystring
    • countrystring
    • line1string
    • line2string
    • postal_codestring
    • statestring
    • townstring
  • address_kanjiobject

    The Kanji variation of the full address of the location (Japan only).

    Show 7 child parameters
    • citystring
    • countrystring
    • line1string
    • line2string
    • postal_codestring
    • statestring
    • townstring
  • configuration_overridesstring

    The ID of a configuration that will be used to customize all readers in this location.

  • display_namestring

    A name for the location. Maximum length is 1000 characters.

  • display_name_kanastring

    The Kana variation of the name for the location (Japan only). Maximum length is 1000 characters.

  • display_name_kanjistring

    The Kanji variation of the name for the location (Japan only). Maximum length is 1000 characters.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • metadataobject

    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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • phonestring

    The phone number for the location.

Returns

The terminal.location object.

POST /v1/terminal/locations
curl -X POST https://api.knoxapi.com/v1/terminal/locations \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1234 Fake Street",
    "line2": null,
    "postal_code": "94102",
    "state": "CA"
  },
  "display_name": "My First Store",
  "id": "tml_j3hPESSh1Tie4LPWyRy8VLVY",
  "livemode": false,
  "metadata": {},
  "object": "terminal.location"
}

List all Locations

GET/v1/terminal/locations

Returns a list of Location objects.

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 terminal.location objects.

GET /v1/terminal/locations
curl -G https://api.knoxapi.com/v1/terminal/locations \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/terminal/locations",
  "has_more": false,
  "data": [
    {
      "address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "1234 Fake Street",
        "line2": null,
        "postal_code": "94102",
        "state": "CA"
      },
      "display_name": "My First Store",
      "id": "tml_j3hPESSh1Tie4LPWyRy8VLVY",
      "livemode": false,
      "metadata": {},
      "object": "terminal.location"
    }
  ]
}

Create a Reader

POST/v1/terminal/readers

Creates a new Reader object.

Body parameters

  • registration_codestringRequired

    A code generated by the reader used for registering to an account.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • labelstring

    Custom label given to the reader for easier identification. If no label is specified, the registration code will be used.

  • locationstring

    The location to assign the reader to.

  • metadataobject

    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. 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 terminal.reader object.

POST /v1/terminal/readers
curl https://api.knoxapi.com/v1/terminal/readers \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d registration_code=example
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
}

List all Readers

GET/v1/terminal/readers

Returns a list of Reader objects.

Query parameters

  • device_typestring

    Filters readers by device type

    Possible values
    • bbpos_chipper2x
    • bbpos_wisepad3
    • bbpos_wisepos_e
    • mobile_phone_reader
    • simulated_stripe_s700
    • simulated_stripe_s710
    • simulated_verifone_m425
    • simulated_verifone_p630
    • simulated_verifone_ux700
    • simulated_verifone_v660p
    • simulated_wisepos_e
    • stripe_m2
    • stripe_s700
    • stripe_s710
    • verifone_P400
    • verifone_m425
    • and 3 more
  • 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.

  • locationstring

    A location ID to filter the response list to only readers at the specific location

  • serial_numberstring

    Filters readers by serial number

  • 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.

  • statusstring

    A status filter to filter readers to only offline or online readers

    Possible values
    • offline
    • online

Returns

A list of terminal.reader objects.

GET /v1/terminal/readers
curl -G https://api.knoxapi.com/v1/terminal/readers \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/terminal/readers",
  "has_more": false,
  "data": [
    {
      "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
    }
  ]
}

Create a refund using a Terminal-supported device.

POST/v1/terminal/refunds

Internal endpoint for terminal use to create a refund for a card_present or card charge. You can optionally refund only part of a charge.

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The terminal.refund object.

POST /v1/terminal/refunds
curl -X POST https://api.knoxapi.com/v1/terminal/refunds \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "object": "terminal.refund"
}

Update a Configuration

POST/v1/terminal/configurations/{configuration}

Updates a new Configuration object.

Path parameters

  • configurationstringRequired

Body parameters

  • bbpos_wisepad3object

    An object containing device type specific settings for BBPOS WisePad 3 readers.

    Show 1 child parameter
    • splashscreenstring
  • bbpos_wisepos_eobject

    An object containing device type specific settings for BBPOS WisePOS E readers.

    Show 1 child parameter
    • splashscreenstring
  • cellularobject

    Configuration for cellular connectivity.

    Show 1 child parameter
    • enabledbooleanRequired
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • namestring

    Name of the configuration

  • offlineobject

    Configurations for collecting transactions offline.

    Show 1 child parameter
    • enabledbooleanRequired
  • reboot_windowobject

    Reboot time settings for readers. that support customized reboot time configuration.

    Show 2 child parameters
    • end_hourintegerRequired
    • start_hourintegerRequired
  • stripe_s700object

    An object containing device type specific settings for Stripe S700 readers.

    Show 1 child parameter
    • splashscreenstring
  • stripe_s710object

    An object containing device type specific settings for Stripe S710 readers.

    Show 1 child parameter
    • splashscreenstring
  • tippingobject

    Tipping configurations for readers that support on-reader tips.

    Show 21 child parameters
    • aedobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • audobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • cadobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • chfobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • czkobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • dkkobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • eurobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • gbpobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • gipobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • hkdobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • hufobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • jpyobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • mxnobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • myrobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • nokobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • nzdobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • plnobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • ronobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • sekobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • sgdobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
    • usdobject
      Show 3 child parameters
      • fixed_amountsarray of integers
      • percentagesarray of integers
      • smart_tip_thresholdinteger
  • verifone_m425object

    An object containing device type specific settings for Verifone M425 readers.

    Show 1 child parameter
    • splashscreenstring
  • verifone_p400object

    An object containing device type specific settings for Verifone P400 readers.

    Show 1 child parameter
    • splashscreenstring
  • verifone_p630object

    An object containing device type specific settings for Verifone P630 readers.

    Show 1 child parameter
    • splashscreenstring
  • verifone_ux700object

    An object containing device type specific settings for Verifone UX700 readers.

    Show 1 child parameter
    • splashscreenstring
  • verifone_v660pobject

    An object containing device type specific settings for Verifone V660p readers.

    Show 1 child parameter
    • splashscreenstring
  • wifiobject

    Configurations for connecting to a WiFi network.

    Show 4 child parameters
    • typestringRequired
      Possible values
      • enterprise_eap_peap
      • enterprise_eap_tls
      • personal_psk
    • enterprise_eap_peapobject
      Show 4 child parameters
      • passwordstringRequired
      • ssidstringRequired
      • usernamestringRequired
      • ca_certificate_filestring
    • enterprise_eap_tlsobject
      Show 5 child parameters
      • client_certificate_filestringRequired
      • private_key_filestringRequired
      • ssidstringRequired
      • ca_certificate_filestring
      • private_key_file_passwordstring
    • personal_pskobject
      Show 2 child parameters
      • passwordstringRequired
      • ssidstringRequired

Returns

The terminal.configuration object.

POST /v1/terminal/configurations/{configuration}
curl -X POST https://api.knoxapi.com/v1/terminal/configurations/tmc_ElVUAjF8xXG3hj \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "bbpos_wisepos_e": {
    "splashscreen": "file_1Pgc6yB7WZ01zgkWSsAMx1We"
  },
  "id": "tmc_ElVUAjF8xXG3hj",
  "is_account_default": false,
  "livemode": false,
  "name": null,
  "object": "terminal.configuration"
}

Retrieve a Configuration

GET/v1/terminal/configurations/{configuration}

Retrieves a Configuration object.

Path parameters

  • configurationstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The terminal.configuration object.

GET /v1/terminal/configurations/{configuration}
curl https://api.knoxapi.com/v1/terminal/configurations/tmc_ElVUAjF8xXG3hj \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "bbpos_wisepos_e": {
    "splashscreen": "file_1Pgc6yB7WZ01zgkWSsAMx1We"
  },
  "id": "tmc_ElVUAjF8xXG3hj",
  "is_account_default": false,
  "livemode": false,
  "name": null,
  "object": "terminal.configuration"
}

Delete a Configuration

DELETE/v1/terminal/configurations/{configuration}

Deletes a Configuration object.

Path parameters

  • configurationstringRequired

Returns

The deleted_terminal.configuration object.

DELETE /v1/terminal/configurations/{configuration}
curl -X DELETE https://api.knoxapi.com/v1/terminal/configurations/tmc_ElVUAjF8xXG3hj \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "deleted": true,
  "id": "tmc_ElVUAjF8xXG3hj",
  "object": "terminal.configuration"
}

Update a Location

POST/v1/terminal/locations/{location}

Updates a Location object by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Path parameters

  • locationstringRequired

Body parameters

  • addressobject

    The full address of the location. You can't change the location's country. If you need to modify the country field, create a new Location object and re-register any existing readers to that location.

    Show 6 child parameters
    • citystring
    • countrystring
    • line1string
    • line2string
    • postal_codestring
    • statestring
  • address_kanaobject

    The Kana variation of the full address of the location (Japan only).

    Show 7 child parameters
    • citystring
    • countrystring
    • line1string
    • line2string
    • postal_codestring
    • statestring
    • townstring
  • address_kanjiobject

    The Kanji variation of the full address of the location (Japan only).

    Show 7 child parameters
    • citystring
    • countrystring
    • line1string
    • line2string
    • postal_codestring
    • statestring
    • townstring
  • configuration_overridesstring

    The ID of a configuration that will be used to customize all readers in this location.

  • display_namestring

    A name for the location.

  • display_name_kanastring

    The Kana variation of the name for the location (Japan only).

  • display_name_kanjistring

    The Kanji variation of the name for the location (Japan only).

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • metadataobject

    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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • phonestring

    The phone number for the location.

Returns

The terminal.location object.

POST /v1/terminal/locations/{location}
curl https://api.knoxapi.com/v1/terminal/locations/tml_j3hPESSh1Tie4LPWyRy8VLVY \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1234 Fake Street",
    "line2": null,
    "postal_code": "94102",
    "state": "CA"
  },
  "display_name": "My First Store",
  "id": "tml_j3hPESSh1Tie4LPWyRy8VLVY",
  "livemode": false,
  "metadata": {},
  "object": "terminal.location"
}

Retrieve a Location

GET/v1/terminal/locations/{location}

Retrieves a Location object.

Path parameters

  • locationstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The terminal.location object.

GET /v1/terminal/locations/{location}
curl https://api.knoxapi.com/v1/terminal/locations/tml_j3hPESSh1Tie4LPWyRy8VLVY \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1234 Fake Street",
    "line2": null,
    "postal_code": "94102",
    "state": "CA"
  },
  "display_name": "My First Store",
  "id": "tml_j3hPESSh1Tie4LPWyRy8VLVY",
  "livemode": false,
  "metadata": {},
  "object": "terminal.location"
}

Delete a Location

DELETE/v1/terminal/locations/{location}

Deletes a Location object.

Path parameters

  • locationstringRequired

Returns

The deleted_terminal.location object.

DELETE /v1/terminal/locations/{location}
curl -X DELETE https://api.knoxapi.com/v1/terminal/locations/tml_j3hPESSh1Tie4LPWyRy8VLVY \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "deleted": true,
  "id": "tml_j3hPESSh1Tie4LPWyRy8VLVY",
  "object": "terminal.location"
}

Update a Reader

POST/v1/terminal/readers/{reader}

Updates a Reader object by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Path parameters

  • readerstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • labelstring

    The new label of the reader.

  • metadataobject

    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. 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 terminal.reader object.

POST /v1/terminal/readers/{reader}
curl https://api.knoxapi.com/v1/terminal/readers/tmr_iGOgDOlmFAot3zIp2JzEqXYs \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
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
}

Retrieve a Reader

GET/v1/terminal/readers/{reader}

Retrieves a Reader object.

Path parameters

  • readerstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The terminal.reader object.

GET /v1/terminal/readers/{reader}
curl https://api.knoxapi.com/v1/terminal/readers/tmr_iGOgDOlmFAot3zIp2JzEqXYs \
  -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
}

Delete a Reader

DELETE/v1/terminal/readers/{reader}

Deletes a Reader object.

Path parameters

  • readerstringRequired

Returns

The deleted_terminal.reader object.

DELETE /v1/terminal/readers/{reader}
curl -X DELETE https://api.knoxapi.com/v1/terminal/readers/tmr_iGOgDOlmFAot3zIp2JzEqXYs \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "deleted": true,
  "id": "tmr_iGOgDOlmFAot3zIp2JzEqXYs",
  "object": "terminal.reader",
  "device_type": "verifone_P400",
  "serial_number": "serial_number"
}

Cancel the current reader action

POST/v1/terminal/readers/{reader}/cancel_action

Cancels the current reader action. See Programmatic Cancellation for more details.

Path parameters

  • readerstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The terminal.reader object.

POST /v1/terminal/readers/{reader}/cancel_action
curl -X POST https://api.knoxapi.com/v1/terminal/readers/tmr_iGOgDOlmFAot3zIp2JzEqXYs/cancel_action \
  -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
}

Collect inputs using a Reader

POST/v1/terminal/readers/{reader}/collect_inputs

Initiates an input collection flow on a Reader to display input forms and collect information from your customers.

Path parameters

  • readerstringRequired

Body parameters

  • inputsarray of objectsRequired

    List of inputs to be collected from the customer using the Reader. Maximum 5 inputs.

    Show 5 child parameters
    • custom_textobjectRequired
      Show 4 child parameters
      • titlestringRequired
      • descriptionstring
      • skip_buttonstring
      • submit_buttonstring
    • typestringRequired
      Possible values
      • email
      • numeric
      • phone
      • selection
      • signature
      • text
    • requiredboolean
    • selectionobject
      Show 1 child parameter
      • choicesarray of objectsRequired

        Child parameters are listed in the OpenAPI document.

    • togglesarray of objects
      Show 3 child parameters
      • default_valuestring
        Possible values
        • disabled
        • enabled
      • descriptionstring
      • titlestring
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • metadataobject

    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. 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 terminal.reader object.

POST /v1/terminal/readers/{reader}/collect_inputs
curl https://api.knoxapi.com/v1/terminal/readers/tmr_iGOgDOlmFAot3zIp2JzEqXYs/collect_inputs \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "inputs[0][custom_text]=" \
  -d "inputs[0][type]=email"
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
}

Hand off a PaymentIntent to a Reader and collect card details

POST/v1/terminal/readers/{reader}/collect_payment_method

Initiates a payment flow on a Reader and updates the PaymentIntent with card details before manual confirmation. See Collecting a Payment method for more details.

Path parameters

  • readerstringRequired

Body parameters

  • payment_intentstringRequired

    The ID of the PaymentIntent to collect a payment method for.

  • collect_configobject

    Configuration overrides for this collection, such as tipping, surcharging, and customer cancellation settings.

    Show 4 child parameters
    • allow_redisplaystring
      Possible values
      • always
      • limited
      • unspecified
    • enable_customer_cancellationboolean
    • skip_tippingboolean
    • tippingobject
      Show 1 child parameter
      • amount_eligibleinteger
  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The terminal.reader object.

POST /v1/terminal/readers/{reader}/collect_payment_method
curl https://api.knoxapi.com/v1/terminal/readers/tmr_iGOgDOlmFAot3zIp2JzEqXYs/collect_payment_method \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d payment_intent=pi_1PgafyB7WZ01zgkWSjxsAJo3
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
}

Confirm a PaymentIntent on the Reader

POST/v1/terminal/readers/{reader}/confirm_payment_intent

Finalizes a payment on a Reader. See Confirming a Payment for more details.

Path parameters

  • readerstringRequired

Body parameters

  • payment_intentstringRequired

    The ID of the PaymentIntent to confirm.

  • confirm_configobject

    Configuration overrides for this confirmation, such as surcharge settings and return URL.

    Show 1 child parameter
    • return_urlstring
  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The terminal.reader object.

POST /v1/terminal/readers/{reader}/confirm_payment_intent
curl https://api.knoxapi.com/v1/terminal/readers/tmr_iGOgDOlmFAot3zIp2JzEqXYs/confirm_payment_intent \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d payment_intent=pi_1PgafyB7WZ01zgkWSjxsAJo3
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
}

Hand-off a PaymentIntent to a Reader

POST/v1/terminal/readers/{reader}/process_payment_intent

Initiates a payment flow on a Reader. See process the payment for more details.

Path parameters

  • readerstringRequired

Body parameters

  • payment_intentstringRequired

    The ID of the PaymentIntent to process on the reader.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • process_configobject

    Configuration overrides for this transaction, such as tipping and customer cancellation settings.

    Show 5 child parameters
    • allow_redisplaystring
      Possible values
      • always
      • limited
      • unspecified
    • enable_customer_cancellationboolean
    • return_urlstring
    • skip_tippingboolean
    • tippingobject
      Show 1 child parameter
      • amount_eligibleinteger

Returns

The terminal.reader object.

POST /v1/terminal/readers/{reader}/process_payment_intent
curl https://api.knoxapi.com/v1/terminal/readers/tmr_iGOgDOlmFAot3zIp2JzEqXYs/process_payment_intent \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d payment_intent=pi_1PgafyB7WZ01zgkWSjxsAJo3
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
}

Hand-off a SetupIntent to a Reader

POST/v1/terminal/readers/{reader}/process_setup_intent

Initiates a SetupIntent flow on a Reader. See Save directly without charging for more details.

Path parameters

  • readerstringRequired

Body parameters

  • allow_redisplaystringRequired

    This field indicates whether this payment method can be shown again to its customer in a checkout flow. Stripe products such as Checkout and Elements use this field to determine whether a payment method can be shown as a saved payment method in a checkout flow.

    Possible values
    • always
    • limited
    • unspecified
  • setup_intentstringRequired

    The ID of the SetupIntent to process on the reader.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • process_configobject

    Configuration overrides for this setup, such as MOTO and customer cancellation settings.

    Show 1 child parameter
    • enable_customer_cancellationboolean

Returns

The terminal.reader object.

POST /v1/terminal/readers/{reader}/process_setup_intent
curl https://api.knoxapi.com/v1/terminal/readers/tmr_iGOgDOlmFAot3zIp2JzEqXYs/process_setup_intent \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d allow_redisplay=always \
  -d setup_intent=seti_1Pgag7B7WZ01zgkWSgwGdb8Z
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
}

Refund a Charge or a PaymentIntent in-person

POST/v1/terminal/readers/{reader}/refund_payment

Initiates an in-person refund on a Reader. See Refund an Interac Payment for more details.

Path parameters

  • readerstringRequired

Body parameters

  • amountinteger

    A positive integer in __cents__ representing how much of this charge to refund.

  • chargestring

    ID of the Charge to refund.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • metadataobject

    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. 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_intentstring

    ID of the PaymentIntent to refund.

  • refund_application_feeboolean

    Boolean indicating whether the application fee should be refunded when refunding this charge. If a full charge refund is given, the full application fee will be refunded. Otherwise, the application fee will be refunded in an amount proportional to the amount of the charge refunded. An application fee can be refunded only by the application that created the charge.

  • refund_payment_configobject

    Configuration overrides for this refund, such as customer cancellation settings.

    Show 1 child parameter
    • enable_customer_cancellationboolean
  • reverse_transferboolean

    Boolean indicating whether the transfer should be reversed when refunding this charge. The transfer will be reversed proportionally to the amount being refunded (either the entire or partial amount). A transfer can be reversed only by the application that created the charge.

Returns

The terminal.reader object.

POST /v1/terminal/readers/{reader}/refund_payment
curl -X POST https://api.knoxapi.com/v1/terminal/readers/tmr_iGOgDOlmFAot3zIp2JzEqXYs/refund_payment \
  -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
}

Set reader display

POST/v1/terminal/readers/{reader}/set_reader_display

Sets the reader display to show cart details.

Path parameters

  • readerstringRequired

Body parameters

  • typestringRequired

    Type of information to display. Only cart is currently supported.

    Possible values
    • cart
  • cartobject

    Cart details to display on the reader screen, including line items, amounts, and currency.

    Show 4 child parameters
    • currencystringRequired
    • line_itemsarray of objectsRequired
      Show 3 child parameters
      • amountintegerRequired
      • descriptionstringRequired
      • quantityintegerRequired
    • totalintegerRequired
    • taxinteger
  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The terminal.reader object.

POST /v1/terminal/readers/{reader}/set_reader_display
curl https://api.knoxapi.com/v1/terminal/readers/tmr_iGOgDOlmFAot3zIp2JzEqXYs/set_reader_display \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d type=cart
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.