API reference

Tokens

Tokenization is the process Stripe uses to collect sensitive card or bank account details, or personally identifiable information (PII), directly from your customers in a secure manner. A token representing this information is returned to your server to use. Use our recommended payments integrations to perform this process on the client-side. This guarantees that no sensitive card data touches your server, and allows your integration to operate in a PCI-compliant way. If you can't use client-side tokenization, you can also create tokens using the API with either your publishable or secret API key. If your integration uses this method, you're responsible for any PCI compliance that it might require, and you must keep your secret API key safe. Unlike with client-side tokenization, your customer's information isn't sent directly to Stripe, so we can't determine how it's handled or stored. You can't store or use tokens more than once. To store card or bank account information for later use, create Customer objects or External accounts. Radar, our integrated solution for automatic fraud protection, performs best with integrations that use client-side tokenization.

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.

Base URL
https://api.knoxapi.com

Create a bank account token

POST/v1/tokens

Creates a single-use token that represents a bank account’s details. You can use this token with any v1 API method in place of a bank account dictionary. You can only use this token once. To do so, attach it to a connected account where controller.requirement_collection is application, which includes Custom accounts.

Body parameters

  • accountobject

    Information for the account this token represents.

    Show 4 child parameters
    • business_typestring
      Possible values
      • company
      • government_entity
      • individual
      • non_profit
    • companyobject
      Show 26 child parameters
      • addressobject

        Child parameters are listed in the OpenAPI document.

      • address_kanaobject

        Child parameters are listed in the OpenAPI document.

      • address_kanjiobject

        Child parameters are listed in the OpenAPI document.

      • administrative_addressobject

        Child parameters are listed in the OpenAPI document.

      • directors_providedboolean
      • directorship_declarationobject

        Child parameters are listed in the OpenAPI document.

      • executives_providedboolean
      • export_license_idstring
      • export_purpose_codestring
      • namestring
      • name_kanastring
      • name_kanjistring
      • owners_providedboolean
      • ownership_declarationobject

        Child parameters are listed in the OpenAPI document.

      • ownership_declaration_shown_and_signedboolean
      • ownership_exemption_reasonstring
        Possible values
        • qualified_entity_exceeds_ownership_threshold
        • qualifies_as_financial_institution
      • phonestring
      • principal_place_of_businessobject

        Child parameters are listed in the OpenAPI document.

      • registration_dateobject

        Child parameters are listed in the OpenAPI document.

      • registration_numberstring
      • representative_declarationobject

        Child parameters are listed in the OpenAPI document.

      • structurestring
        Possible values
        • free_zone_establishment
        • free_zone_llc
        • government_instrumentality
        • governmental_unit
        • incorporated_non_profit
        • incorporated_partnership
        • limited_liability_partnership
        • llc
        • multi_member_llc
        • private_company
        • private_corporation
        • private_partnership
        • public_company
        • public_corporation
        • public_partnership
        • registered_charity
        • and 7 more
      • tax_idstring
      • tax_id_registrarstring
      • vat_idstring
      • verificationobject

        Child parameters are listed in the OpenAPI document.

    • individualobject
      Show 23 child parameters
      • addressobject

        Child parameters are listed in the OpenAPI document.

      • address_kanaobject

        Child parameters are listed in the OpenAPI document.

      • address_kanjiobject

        Child parameters are listed in the OpenAPI document.

      • dobobject

        Child parameters are listed in the OpenAPI document.

      • emailstring
      • first_namestring
      • first_name_kanastring
      • first_name_kanjistring
      • full_name_aliasesarray of strings
      • genderstring
      • id_numberstring
      • id_number_secondarystring
      • last_namestring
      • last_name_kanastring
      • last_name_kanjistring
      • maiden_namestring
      • metadataobject
      • phonestring
      • political_exposurestring
        Possible values
        • existing
        • none
      • registered_addressobject

        Child parameters are listed in the OpenAPI document.

      • relationshipobject

        Child parameters are listed in the OpenAPI document.

      • ssn_last_4string
      • verificationobject

        Child parameters are listed in the OpenAPI document.

    • tos_shown_and_acceptedboolean
  • bank_accountobject

    The bank account this token will represent.

    Show 8 child parameters
    • account_numberstringRequired
    • countrystringRequired
    • account_holder_namestring
    • account_holder_typestring
      Possible values
      • company
      • individual
    • account_typestring
      Possible values
      • checking
      • futsu
      • savings
      • toza
    • currencystring
    • payment_methodstring
    • routing_numberstring
  • cardobject | string

    The card this token will represent. If you also pass in a customer, the card must be the ID of a card belonging to the customer. Otherwise, if you do not pass in a customer, this is a dictionary containing a user's credit card details, with the options described below.

    Show 13 child parameters
    • exp_monthstringRequired
    • exp_yearstringRequired
    • numberstringRequired
    • address_citystring
    • address_countrystring
    • address_line1string
    • address_line2string
    • address_statestring
    • address_zipstring
    • currencystring
    • cvcstring
    • namestring
    • networksobject
      Show 1 child parameter
      • preferredstring
        Possible values
        • cartes_bancaires
        • mastercard
        • visa
  • customerstring

    Create a token for the customer, which is owned by the application's account. You can only use this with an OAuth access token or Stripe-Account header. Learn more about cloning saved payment methods.

  • cvc_updateobject

    The updated CVC value this token represents.

    Show 1 child parameter
    • cvcstringRequired
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • personobject

    Information for the person this token represents.

    Show 27 child parameters
    • additional_tos_acceptancesobject
      Show 1 child parameter
    • addressobject
      Show 6 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
    • address_kanaobject
      Show 7 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
      • townstring
    • address_kanjiobject
      Show 7 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
      • townstring
    • dobobject
      Show 3 child parameters
      • dayintegerRequired
      • monthintegerRequired
      • yearintegerRequired
    • documentsobject
      Show 3 child parameters
    • emailstring
    • first_namestring
    • first_name_kanastring
    • first_name_kanjistring
    • full_name_aliasesarray of strings
    • genderstring
    • id_numberstring
    • id_number_secondarystring
    • last_namestring
    • last_name_kanastring
    • last_name_kanjistring
    • maiden_namestring
    • metadataobject
    • nationalitystring
    • phonestring
    • political_exposurestring
      Possible values
      • existing
      • none
    • registered_addressobject
      Show 6 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
    • relationshipobject
      Show 8 child parameters
      • authorizerboolean
      • directorboolean
      • executiveboolean
      • legal_guardianboolean
      • ownerboolean
      • percent_ownershipnumber
      • representativeboolean
      • titlestring
    • ssn_last_4string
    • us_cfpb_dataobject
      Show 3 child parameters
      • ethnicity_detailsobject

        Child parameters are listed in the OpenAPI document.

      • race_detailsobject

        Child parameters are listed in the OpenAPI document.

      • self_identified_genderstring
    • verificationobject
      Show 2 child parameters
  • piiobject

    The PII this token represents.

    Show 1 child parameter
    • id_numberstring

Returns

The token object.

POST /v1/tokens
curl -X POST https://api.knoxapi.com/v1/tokens \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "card": {
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2030,
    "fingerprint": "AOB934RVNwzk6xtn",
    "funding": "credit",
    "id": "card_1Pgc7BB7WZ01zgkWeZoy4YdD",
    "last4": "4242",
    "metadata": {},
    "name": null,
    "networks": {
      "preferred": null
    },
    "object": "card",
    "tokenization_method": null,
    "regulated_status": null
  },
  "client_ip": null,
  "created": 1234567890,
  "id": "tok_1Pgc7BB7WZ01zgkWptnajzKJ",
  "livemode": false,
  "object": "token",
  "type": "card",
  "used": false
}

Retrieve a token

GET/v1/tokens/{token}

Retrieves the token with the given ID.

Path parameters

  • tokenstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The token object.

GET /v1/tokens/{token}
curl https://api.knoxapi.com/v1/tokens/tok_1Pgc7BB7WZ01zgkWptnajzKJ \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "card": {
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2030,
    "fingerprint": "AOB934RVNwzk6xtn",
    "funding": "credit",
    "id": "card_1Pgc7BB7WZ01zgkWeZoy4YdD",
    "last4": "4242",
    "metadata": {},
    "name": null,
    "networks": {
      "preferred": null
    },
    "object": "card",
    "tokenization_method": null,
    "regulated_status": null
  },
  "client_ip": null,
  "created": 1234567890,
  "id": "tok_1Pgc7BB7WZ01zgkWptnajzKJ",
  "livemode": false,
  "object": "token",
  "type": "card",
  "used": false
}

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.