API reference

Setup Intents

A SetupIntent guides you through the process of setting up and saving a customer's payment credentials for future payments. For example, you can use a SetupIntent to set up and save your customer's card without immediately collecting a payment. Later, you can use PaymentIntents to drive the payment flow. Create a SetupIntent when you're ready to collect your customer's payment credentials. Don't maintain long-lived, unconfirmed SetupIntents because they might not be valid. The SetupIntent transitions through multiple statuses as it guides you through the setup process. Successful SetupIntents result in payment credentials that are optimized for future payments. For example, cardholders in certain regions might need to be run through Strong Customer Authentication during payment method collection to streamline later off-session payments. If you use the SetupIntent with a Customer, it automatically attaches the resulting payment method to that Customer after successful setup. We recommend using SetupIntents or setup_future_usage on PaymentIntents to save payment methods to prevent saving invalid or unoptimized payment methods. By using SetupIntents, you can reduce friction for your customers, even as regulations change over time. Related guide: Setup Intents API

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 SetupIntent

POST/v1/setup_intents

Creates a SetupIntent object. After you create the SetupIntent, attach a payment method and confirm it to collect any required permissions to charge the payment method later.

Body parameters

  • allowed_payment_method_typesarray of strings

    The list of payment method types to allow for this SetupIntent. Stripe will only use methods in this list when determining the payment methods to offer. A list of valid payment method types can be found here.

  • attach_to_selfboolean

    If present, the SetupIntent's payment method will be attached to the in-context Stripe Account. It can only be used for this Stripe Account’s own money movement flows like InboundTransfer and OutboundTransfers. It cannot be set to true when setting up a PaymentMethod for a Customer, and defaults to false when attaching a PaymentMethod to a Customer.

  • automatic_payment_methodsobject

    When you enable this parameter, this SetupIntent accepts payment methods that you enable in the Dashboard and that are compatible with its other parameters.

    Show 2 child parameters
    • enabledbooleanRequired
    • allow_redirectsstring
      Possible values
      • always
      • never
  • confirmboolean

    Set to true to attempt to confirm this SetupIntent immediately. This parameter defaults to false. If a card is the attached payment method, you can provide a return_url in case further authentication is necessary.

  • confirmation_tokenstring

    ID of the ConfirmationToken used to confirm this SetupIntent. If the provided ConfirmationToken contains properties that are also being provided in this request, such as payment_method, then the values in this request will take precedence.

  • customerstring

    ID of the Customer this SetupIntent belongs to, if one exists. If present, the SetupIntent's payment method will be attached to the Customer on successful setup. Payment methods attached to other Customers cannot be used with this SetupIntent.

  • customer_accountstring

    ID of the Account this SetupIntent belongs to, if one exists. If present, the SetupIntent's payment method will be attached to the Account on successful setup. Payment methods attached to other Accounts cannot be used with this SetupIntent.

  • descriptionstring

    An arbitrary string attached to the object. Often useful for displaying to users.

  • excluded_payment_method_typesarray of strings

    The list of payment method types to exclude from use with this SetupIntent.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • flow_directionsarray of strings

    Indicates the directions of money movement for which this payment method is intended to be used. Include inbound if you intend to use the payment method as the origin to pull funds from. Include outbound if you intend to use the payment method as the destination to send funds to. You can include both if you intend to use the payment method for both purposes.

  • mandate_dataobject

    This hash contains details about the mandate to create. This parameter can only be used with confirm=true.

    Show 1 child parameter
    • customer_acceptanceobjectRequired
      Show 4 child parameters
      • typestringRequired
        Possible values
        • offline
        • online
      • accepted_atinteger
      • offlineobject
      • onlineobject

        Child parameters are listed in the OpenAPI document.

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

  • on_behalf_ofstring

    The Stripe account ID created for this SetupIntent.

  • payment_methodstring

    ID of the payment method (a PaymentMethod, Card, or saved Source object) to attach to this SetupIntent.

  • payment_method_configurationstring

    The ID of the payment method configuration to use with this SetupIntent.

  • payment_method_dataobject

    When included, this hash creates a PaymentMethod that is set as the payment_method value in the SetupIntent.

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

    Show 14 child parameters
    • acss_debitobject
      Show 3 child parameters
      • currencystring
        Possible values
        • cad
        • usd
      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • verification_methodstring
        Possible values
        • automatic
        • instant
        • microdeposits
    • amazon_payobject
    • bacs_debitobject
      Show 1 child parameter
    • bizumobject
    • cardobject
      Show 4 child parameters
      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • networkstring
        Possible values
        • amex
        • cartes_bancaires
        • diners
        • discover
        • eftpos_au
        • girocard
        • interac
        • jcb
        • link
        • mastercard
        • unionpay
        • unknown
        • visa
      • request_three_d_securestring
        Possible values
        • any
        • automatic
        • challenge
      • three_d_secureobject

        Child parameters are listed in the OpenAPI document.

    • card_presentobject
    • klarnaobject
      Show 4 child parameters
      • currencystring
      • on_demandobject

        Child parameters are listed in the OpenAPI document.

      • preferred_localestring
        Possible values
        • cs-CZ
        • da-DK
        • de-AT
        • de-CH
        • de-DE
        • el-GR
        • en-AT
        • en-AU
        • en-BE
        • en-CA
        • en-CH
        • en-CZ
        • en-DE
        • en-DK
        • en-ES
        • en-FI
        • and 30 more
      • subscriptionsarray of objects

        Child parameters are listed in the OpenAPI document.

    • linkobject
    • paypalobject
      Show 1 child parameter
      • billing_agreement_idstring
    • paytoobject
      Show 1 child parameter
    • pixobject
      Show 1 child parameter
    • sepa_debitobject
      Show 1 child parameter
    • upiobject
      Show 2 child parameters
      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • setup_future_usagestring
        Possible values
        • none
        • off_session
        • on_session
    • us_bank_accountobject
      Show 4 child parameters
      • financial_connectionsobject

        Child parameters are listed in the OpenAPI document.

      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • networksobject

        Child parameters are listed in the OpenAPI document.

      • verification_methodstring
        Possible values
        • automatic
        • instant
        • microdeposits
  • payment_method_typesarray of strings

    The list of payment method types (for example, card) that this SetupIntent can use. If you don't provide this, Stripe will dynamically show relevant payment methods from your payment method settings. A list of valid payment method types can be found here.

  • return_urlstring

    The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method's app or site. To redirect to a mobile application, you can alternatively supply an application URI scheme. This parameter can only be used with confirm=true.

  • single_useobject

    If you populate this hash, this SetupIntent generates a single_use mandate after successful completion. Single-use mandates are only valid for the following payment methods: acss_debit, alipay, au_becs_debit, bacs_debit, bancontact, boleto, ideal, link, sepa_debit, and us_bank_account.

    Show 2 child parameters
    • amountintegerRequired
    • currencystringRequired
  • usagestring

    Indicates how the payment method is intended to be used in the future. If not provided, this value defaults to off_session.

    Possible values
    • off_session
    • on_session
  • use_stripe_sdkboolean

    Set to true when confirming server-side and using Stripe.js, iOS, or Android client-side SDKs to handle the next actions.

Returns

The setup_intent object.

POST /v1/setup_intents
curl -X POST https://api.knoxapi.com/v1/setup_intents \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "application": null,
  "automatic_payment_methods": {
    "enabled": null
  },
  "cancellation_reason": null,
  "client_secret": "seti_1Pgag7B7WZ01zgkWSgwGdb8Z_secret_QXg2AQLdBxJwtY51IkwvUaBVsnCqPSp",
  "created": 1234567890,
  "customer": null,
  "description": null,
  "flow_directions": null,
  "id": "seti_1Pgag7B7WZ01zgkWSgwGdb8Z",
  "last_setup_error": {
    "type": "idempotency_error"
  },
  "latest_attempt": null,
  "livemode": false,
  "mandate": null,
  "metadata": {},
  "next_action": {
    "type": "type"
  },
  "object": "setup_intent",
  "on_behalf_of": null,
  "payment_method": null,
  "payment_method_configuration_details": {
    "id": "obj_123",
    "parent": null
  },
  "payment_method_options": {},
  "payment_method_types": [
    "card"
  ],
  "single_use_mandate": null,
  "status": "requires_payment_method",
  "usage": "off_session",
  "excluded_payment_method_types": null,
  "allowed_payment_method_types": null
}

List all SetupIntents

GET/v1/setup_intents

Returns a list of SetupIntents.

Query parameters

  • attach_to_selfboolean

    If present, the SetupIntent's payment method will be attached to the in-context Stripe Account. It can only be used for this Stripe Account’s own money movement flows like InboundTransfer and OutboundTransfers. It cannot be set to true when setting up a PaymentMethod for a Customer, and defaults to false when attaching a PaymentMethod to a Customer.

  • createdobject | integer

    A filter on the list, based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with a number of different query options.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • customerstring

    Only return SetupIntents for the customer specified by this customer ID.

  • customer_accountstring

    Only return SetupIntents for the account specified by this customer ID.

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

  • payment_methodstring

    Only return SetupIntents that associate with the specified payment method.

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

GET /v1/setup_intents
curl -G https://api.knoxapi.com/v1/setup_intents \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/setup_intents",
  "has_more": false,
  "data": [
    {
      "application": null,
      "automatic_payment_methods": {
        "enabled": null
      },
      "cancellation_reason": null,
      "client_secret": "seti_1Pgag7B7WZ01zgkWSgwGdb8Z_secret_QXg2AQLdBxJwtY51IkwvUaBVsnCqPSp",
      "created": 1234567890,
      "customer": null,
      "description": null,
      "flow_directions": null,
      "id": "seti_1Pgag7B7WZ01zgkWSgwGdb8Z",
      "last_setup_error": {
        "type": "idempotency_error"
      },
      "latest_attempt": null,
      "livemode": false,
      "mandate": null,
      "metadata": {},
      "next_action": {
        "type": "type"
      },
      "object": "setup_intent",
      "on_behalf_of": null,
      "payment_method": null,
      "payment_method_configuration_details": {
        "id": "obj_123",
        "parent": null
      },
      "payment_method_options": {},
      "payment_method_types": [
        "card"
      ],
      "single_use_mandate": null,
      "status": "requires_payment_method",
      "usage": "off_session",
      "excluded_payment_method_types": null,
      "allowed_payment_method_types": null
    }
  ]
}

Update a SetupIntent

POST/v1/setup_intents/{intent}

Updates a SetupIntent object.

Path parameters

  • intentstringRequired

Body parameters

  • allowed_payment_method_typesarray of strings

    The list of payment method types to allow for this SetupIntent. Stripe will only use methods in this list when determining the payment methods to offer. A list of valid payment method types can be found here.

  • attach_to_selfboolean

    If present, the SetupIntent's payment method will be attached to the in-context Stripe Account. It can only be used for this Stripe Account’s own money movement flows like InboundTransfer and OutboundTransfers. It cannot be set to true when setting up a PaymentMethod for a Customer, and defaults to false when attaching a PaymentMethod to a Customer.

  • customerstring

    ID of the Customer this SetupIntent belongs to, if one exists. If present, the SetupIntent's payment method will be attached to the Customer on successful setup. Payment methods attached to other Customers cannot be used with this SetupIntent.

  • customer_accountstring

    ID of the Account this SetupIntent belongs to, if one exists. If present, the SetupIntent's payment method will be attached to the Account on successful setup. Payment methods attached to other Accounts cannot be used with this SetupIntent.

  • descriptionstring

    An arbitrary string attached to the object. Often useful for displaying to users.

  • excluded_payment_method_typesarray of strings

    The list of payment method types to exclude from use with this SetupIntent.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • flow_directionsarray of strings

    Indicates the directions of money movement for which this payment method is intended to be used. Include inbound if you intend to use the payment method as the origin to pull funds from. Include outbound if you intend to use the payment method as the destination to send funds to. You can include both if you intend to use the payment method for both purposes.

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

    ID of the payment method (a PaymentMethod, Card, or saved Source object) to attach to this SetupIntent. To unset this field to null, pass in an empty string.

  • payment_method_configurationstring

    The ID of the payment method configuration to use with this SetupIntent.

  • payment_method_dataobject

    When included, this hash creates a PaymentMethod that is set as the payment_method value in the SetupIntent.

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

    Show 14 child parameters
    • acss_debitobject
      Show 3 child parameters
      • currencystring
        Possible values
        • cad
        • usd
      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • verification_methodstring
        Possible values
        • automatic
        • instant
        • microdeposits
    • amazon_payobject
    • bacs_debitobject
      Show 1 child parameter
    • bizumobject
    • cardobject
      Show 4 child parameters
      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • networkstring
        Possible values
        • amex
        • cartes_bancaires
        • diners
        • discover
        • eftpos_au
        • girocard
        • interac
        • jcb
        • link
        • mastercard
        • unionpay
        • unknown
        • visa
      • request_three_d_securestring
        Possible values
        • any
        • automatic
        • challenge
      • three_d_secureobject

        Child parameters are listed in the OpenAPI document.

    • card_presentobject
    • klarnaobject
      Show 4 child parameters
      • currencystring
      • on_demandobject

        Child parameters are listed in the OpenAPI document.

      • preferred_localestring
        Possible values
        • cs-CZ
        • da-DK
        • de-AT
        • de-CH
        • de-DE
        • el-GR
        • en-AT
        • en-AU
        • en-BE
        • en-CA
        • en-CH
        • en-CZ
        • en-DE
        • en-DK
        • en-ES
        • en-FI
        • and 30 more
      • subscriptionsarray of objects

        Child parameters are listed in the OpenAPI document.

    • linkobject
    • paypalobject
      Show 1 child parameter
      • billing_agreement_idstring
    • paytoobject
      Show 1 child parameter
    • pixobject
      Show 1 child parameter
    • sepa_debitobject
      Show 1 child parameter
    • upiobject
      Show 2 child parameters
      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • setup_future_usagestring
        Possible values
        • none
        • off_session
        • on_session
    • us_bank_accountobject
      Show 4 child parameters
      • financial_connectionsobject

        Child parameters are listed in the OpenAPI document.

      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • networksobject

        Child parameters are listed in the OpenAPI document.

      • verification_methodstring
        Possible values
        • automatic
        • instant
        • microdeposits
  • payment_method_typesarray of strings

    The list of payment method types (for example, card) that this SetupIntent can set up. If you don't provide this, Stripe will dynamically show relevant payment methods from your payment method settings. A list of valid payment method types can be found here.

Returns

The setup_intent object.

POST /v1/setup_intents/{intent}
curl https://api.knoxapi.com/v1/setup_intents/seti_1Pgag7B7WZ01zgkWSgwGdb8Z \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "application": null,
  "automatic_payment_methods": {
    "enabled": null
  },
  "cancellation_reason": null,
  "client_secret": "seti_1Pgag7B7WZ01zgkWSgwGdb8Z_secret_QXg2AQLdBxJwtY51IkwvUaBVsnCqPSp",
  "created": 1234567890,
  "customer": null,
  "description": null,
  "flow_directions": null,
  "id": "seti_1Pgag7B7WZ01zgkWSgwGdb8Z",
  "last_setup_error": {
    "type": "idempotency_error"
  },
  "latest_attempt": null,
  "livemode": false,
  "mandate": null,
  "metadata": {},
  "next_action": {
    "type": "type"
  },
  "object": "setup_intent",
  "on_behalf_of": null,
  "payment_method": null,
  "payment_method_configuration_details": {
    "id": "obj_123",
    "parent": null
  },
  "payment_method_options": {},
  "payment_method_types": [
    "card"
  ],
  "single_use_mandate": null,
  "status": "requires_payment_method",
  "usage": "off_session",
  "excluded_payment_method_types": null,
  "allowed_payment_method_types": null
}

Retrieve a SetupIntent

GET/v1/setup_intents/{intent}

Retrieves the details of a SetupIntent that has previously been created. Client-side retrieval using a publishable key is allowed when the client_secret is provided in the query string. When retrieved with a publishable key, only a subset of properties will be returned. Please refer to the SetupIntent object reference for more details.

Path parameters

  • intentstringRequired

Query parameters

  • client_secretstring

    The client secret of the SetupIntent. We require this string if you use a publishable key to retrieve the SetupIntent.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The setup_intent object.

GET /v1/setup_intents/{intent}
curl https://api.knoxapi.com/v1/setup_intents/seti_1Pgag7B7WZ01zgkWSgwGdb8Z \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "application": null,
  "automatic_payment_methods": {
    "enabled": null
  },
  "cancellation_reason": null,
  "client_secret": "seti_1Pgag7B7WZ01zgkWSgwGdb8Z_secret_QXg2AQLdBxJwtY51IkwvUaBVsnCqPSp",
  "created": 1234567890,
  "customer": null,
  "description": null,
  "flow_directions": null,
  "id": "seti_1Pgag7B7WZ01zgkWSgwGdb8Z",
  "last_setup_error": {
    "type": "idempotency_error"
  },
  "latest_attempt": null,
  "livemode": false,
  "mandate": null,
  "metadata": {},
  "next_action": {
    "type": "type"
  },
  "object": "setup_intent",
  "on_behalf_of": null,
  "payment_method": null,
  "payment_method_configuration_details": {
    "id": "obj_123",
    "parent": null
  },
  "payment_method_options": {},
  "payment_method_types": [
    "card"
  ],
  "single_use_mandate": null,
  "status": "requires_payment_method",
  "usage": "off_session",
  "excluded_payment_method_types": null,
  "allowed_payment_method_types": null
}

Cancel a SetupIntent

POST/v1/setup_intents/{intent}/cancel

You can cancel a SetupIntent object when it’s in one of these statuses: requires_payment_method, requires_confirmation, or requires_action. After you cancel it, setup is abandoned and any operations on the SetupIntent fail with an error. You can’t cancel the SetupIntent for a Checkout Session. Expire the Checkout Session instead.

Path parameters

  • intentstringRequired

Body parameters

  • cancellation_reasonstring

    Reason for canceling this SetupIntent. Possible values are: abandoned, requested_by_customer, or duplicate

    Possible values
    • abandoned
    • duplicate
    • requested_by_customer
  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The setup_intent object.

POST /v1/setup_intents/{intent}/cancel
curl -X POST https://api.knoxapi.com/v1/setup_intents/seti_1Pgag7B7WZ01zgkWSgwGdb8Z/cancel \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "application": null,
  "automatic_payment_methods": {
    "enabled": null
  },
  "cancellation_reason": null,
  "client_secret": "seti_1Pgag7B7WZ01zgkWSgwGdb8Z_secret_QXg2AQLdBxJwtY51IkwvUaBVsnCqPSp",
  "created": 1234567890,
  "customer": null,
  "description": null,
  "flow_directions": null,
  "id": "seti_1Pgag7B7WZ01zgkWSgwGdb8Z",
  "last_setup_error": {
    "type": "idempotency_error"
  },
  "latest_attempt": null,
  "livemode": false,
  "mandate": null,
  "metadata": {},
  "next_action": {
    "type": "type"
  },
  "object": "setup_intent",
  "on_behalf_of": null,
  "payment_method": null,
  "payment_method_configuration_details": {
    "id": "obj_123",
    "parent": null
  },
  "payment_method_options": {},
  "payment_method_types": [
    "card"
  ],
  "single_use_mandate": null,
  "status": "requires_payment_method",
  "usage": "off_session",
  "excluded_payment_method_types": null,
  "allowed_payment_method_types": null
}

Confirm a SetupIntent

POST/v1/setup_intents/{intent}/confirm

Confirm that your customer intends to set up the current or provided payment method. For example, you would confirm a SetupIntent when a customer hits the “Save” button on a payment method management page on your website. If the selected payment method does not require any additional steps from the customer, the SetupIntent will transition to the succeeded status. Otherwise, it will transition to the requires_action status and suggest additional actions via next_action. If setup fails, the SetupIntent will transition to the requires_payment_method status or the canceled status if the confirmation limit is reached.

Path parameters

  • intentstringRequired

Body parameters

  • allowed_payment_method_typesarray of strings

    The list of payment method types to allow for this SetupIntent. Stripe will only use methods in this list when determining the payment methods to offer. A list of valid payment method types can be found here.

  • client_secretstring

    The client secret of the SetupIntent.

  • confirmation_tokenstring

    ID of the ConfirmationToken used to confirm this SetupIntent. If the provided ConfirmationToken contains properties that are also being provided in this request, such as payment_method, then the values in this request will take precedence.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • mandate_dataobject
    Show 1 child parameter
    • customer_acceptanceobjectRequired
      Show 4 child parameters
      • typestringRequired
        Possible values
        • offline
        • online
      • accepted_atinteger
      • offlineobject
      • onlineobject

        Child parameters are listed in the OpenAPI document.

  • payment_methodstring

    ID of the payment method (a PaymentMethod, Card, or saved Source object) to attach to this SetupIntent.

  • payment_method_dataobject

    When included, this hash creates a PaymentMethod that is set as the payment_method value in the SetupIntent.

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

    Show 14 child parameters
    • acss_debitobject
      Show 3 child parameters
      • currencystring
        Possible values
        • cad
        • usd
      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • verification_methodstring
        Possible values
        • automatic
        • instant
        • microdeposits
    • amazon_payobject
    • bacs_debitobject
      Show 1 child parameter
    • bizumobject
    • cardobject
      Show 4 child parameters
      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • networkstring
        Possible values
        • amex
        • cartes_bancaires
        • diners
        • discover
        • eftpos_au
        • girocard
        • interac
        • jcb
        • link
        • mastercard
        • unionpay
        • unknown
        • visa
      • request_three_d_securestring
        Possible values
        • any
        • automatic
        • challenge
      • three_d_secureobject

        Child parameters are listed in the OpenAPI document.

    • card_presentobject
    • klarnaobject
      Show 4 child parameters
      • currencystring
      • on_demandobject

        Child parameters are listed in the OpenAPI document.

      • preferred_localestring
        Possible values
        • cs-CZ
        • da-DK
        • de-AT
        • de-CH
        • de-DE
        • el-GR
        • en-AT
        • en-AU
        • en-BE
        • en-CA
        • en-CH
        • en-CZ
        • en-DE
        • en-DK
        • en-ES
        • en-FI
        • and 30 more
      • subscriptionsarray of objects

        Child parameters are listed in the OpenAPI document.

    • linkobject
    • paypalobject
      Show 1 child parameter
      • billing_agreement_idstring
    • paytoobject
      Show 1 child parameter
    • pixobject
      Show 1 child parameter
    • sepa_debitobject
      Show 1 child parameter
    • upiobject
      Show 2 child parameters
      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • setup_future_usagestring
        Possible values
        • none
        • off_session
        • on_session
    • us_bank_accountobject
      Show 4 child parameters
      • financial_connectionsobject

        Child parameters are listed in the OpenAPI document.

      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • networksobject

        Child parameters are listed in the OpenAPI document.

      • verification_methodstring
        Possible values
        • automatic
        • instant
        • microdeposits
  • return_urlstring

    The URL to redirect your customer back to after they authenticate on the payment method's app or site. If you'd prefer to redirect to a mobile application, you can alternatively supply an application URI scheme. This parameter is only used for cards and other redirect-based payment methods.

  • use_stripe_sdkboolean

    Set to true when confirming server-side and using Stripe.js, iOS, or Android client-side SDKs to handle the next actions.

Returns

The setup_intent object.

POST /v1/setup_intents/{intent}/confirm
curl -X POST https://api.knoxapi.com/v1/setup_intents/seti_1Pgag7B7WZ01zgkWSgwGdb8Z/confirm \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "application": null,
  "automatic_payment_methods": {
    "enabled": null
  },
  "cancellation_reason": null,
  "client_secret": "seti_1Pgag7B7WZ01zgkWSgwGdb8Z_secret_QXg2AQLdBxJwtY51IkwvUaBVsnCqPSp",
  "created": 1234567890,
  "customer": null,
  "description": null,
  "flow_directions": null,
  "id": "seti_1Pgag7B7WZ01zgkWSgwGdb8Z",
  "last_setup_error": {
    "type": "idempotency_error"
  },
  "latest_attempt": null,
  "livemode": false,
  "mandate": null,
  "metadata": {},
  "next_action": {
    "type": "type"
  },
  "object": "setup_intent",
  "on_behalf_of": null,
  "payment_method": null,
  "payment_method_configuration_details": {
    "id": "obj_123",
    "parent": null
  },
  "payment_method_options": {},
  "payment_method_types": [
    "card"
  ],
  "single_use_mandate": null,
  "status": "requires_payment_method",
  "usage": "off_session",
  "excluded_payment_method_types": null,
  "allowed_payment_method_types": null
}

Verify microdeposits on a SetupIntent

POST/v1/setup_intents/{intent}/verify_microdeposits

Verifies microdeposits on a SetupIntent object.

Path parameters

  • intentstringRequired

Body parameters

  • amountsarray of integers

    Two positive integers, in *cents*, equal to the values of the microdeposits sent to the bank account.

  • client_secretstring

    The client secret of the SetupIntent.

  • descriptor_codestring

    A six-character code starting with SM present in the microdeposit sent to the bank account.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The setup_intent object.

POST /v1/setup_intents/{intent}/verify_microdeposits
curl -X POST https://api.knoxapi.com/v1/setup_intents/seti_1Pgag7B7WZ01zgkWSgwGdb8Z/verify_microdeposits \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "application": null,
  "automatic_payment_methods": {
    "enabled": null
  },
  "cancellation_reason": null,
  "client_secret": "seti_1Pgag7B7WZ01zgkWSgwGdb8Z_secret_QXg2AQLdBxJwtY51IkwvUaBVsnCqPSp",
  "created": 1234567890,
  "customer": null,
  "description": null,
  "flow_directions": null,
  "id": "seti_1Pgag7B7WZ01zgkWSgwGdb8Z",
  "last_setup_error": {
    "type": "idempotency_error"
  },
  "latest_attempt": null,
  "livemode": false,
  "mandate": null,
  "metadata": {},
  "next_action": {
    "type": "type"
  },
  "object": "setup_intent",
  "on_behalf_of": null,
  "payment_method": null,
  "payment_method_configuration_details": {
    "id": "obj_123",
    "parent": null
  },
  "payment_method_options": {},
  "payment_method_types": [
    "card"
  ],
  "single_use_mandate": null,
  "status": "requires_payment_method",
  "usage": "off_session",
  "excluded_payment_method_types": null,
  "allowed_payment_method_types": 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.