API reference

Sources

Source objects allow you to accept a variety of payment methods. They represent a customer's payment instrument, and can be used with the Stripe API just like a Card object: once chargeable, they can be charged, or can be attached to customers. Stripe doesn't recommend using the deprecated Sources API. We recommend that you adopt the PaymentMethods API. This newer API provides access to our latest features and payment method types. Related guides: Sources API and Sources & Customers.

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 source

POST/v1/sources

Creates a new source object.

Body parameters

  • amountinteger

    Amount associated with the source. This is the amount for which the source will be chargeable once ready. Required for single_use sources. Not supported for receiver type sources, where charge amount may not be specified until funds land.

  • currencystring

    Three-letter ISO code for the currency associated with the source. This is the currency for which the source will be chargeable once ready.

  • customerstring

    The Customer to whom the original source is attached to. Must be set when the original source is not a Source (e.g., Card).

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • flowstring

    The authentication flow of the source to create. flow is one of redirect, receiver, code_verification, none. It is generally inferred unless a type supports multiple flows.

    Possible values
    • code_verification
    • none
    • receiver
    • redirect
  • mandateobject

    Information about a mandate possibility attached to a source object (generally for bank debits) as well as its acceptance status.

    Show 5 child parameters
    • acceptanceobject
      Show 7 child parameters
      • statusstringRequired
        Possible values
        • accepted
        • pending
        • refused
        • revoked
      • dateinteger
      • ipstring
      • offlineobject

        Child parameters are listed in the OpenAPI document.

      • onlineobject

        Child parameters are listed in the OpenAPI document.

      • typestring
        Possible values
        • offline
        • online
      • user_agentstring
    • amountinteger
    • currencystring
    • intervalstring
      Possible values
      • one_time
      • scheduled
      • variable
    • notification_methodstring
      Possible values
      • deprecated_none
      • email
      • manual
      • none
      • stripe_email
  • metadataobject
  • original_sourcestring

    The source to share.

  • ownerobject

    Information about the owner of the payment instrument that may be used or required by particular source types.

    Show 4 child parameters
    • addressobject
      Show 6 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
    • emailstring
    • namestring
    • phonestring
  • receiverobject

    Optional parameters for the receiver flow. Can be set only if the source is a receiver (flow is receiver).

    Show 1 child parameter
    • refund_attributes_methodstring
      Possible values
      • email
      • manual
      • none
  • redirectobject

    Parameters required for the redirect flow. Required if the source is authenticated by a redirect (flow is redirect).

    Show 1 child parameter
    • return_urlstringRequired
  • source_orderobject

    Information about the items and shipping associated with the source. Required for transactional credit (for example Klarna) sources before you can charge it.

    Show 2 child parameters
    • itemsarray of objects
      Show 6 child parameters
      • amountinteger
      • currencystring
      • descriptionstring
      • parentstring
      • quantityinteger
      • typestring
        Possible values
        • discount
        • shipping
        • sku
        • tax
    • shippingobject
      Show 5 child parameters
      • addressobjectRequired

        Child parameters are listed in the OpenAPI document.

      • carrierstring
      • namestring
      • phonestring
      • tracking_numberstring
  • statement_descriptorstring

    An arbitrary string to be displayed on your customer's statement. As an example, if your website is RunClub and the item you're charging for is a race ticket, you may want to specify a statement_descriptor of RunClub 5K race ticket. While many payment types will display this information, some may not display it at all.

  • tokenstring

    An optional token used to create the source. When passed, token properties will override source parameters.

  • typestring

    The type of the source to create. Required unless customer and original_source are specified (see the Cloning card Sources guide)

  • usagestring
    Possible values
    • reusable
    • single_use

Returns

The source object.

POST /v1/sources
curl -X POST https://api.knoxapi.com/v1/sources \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "ach_credit_transfer": {
    "account_number": "test_52796e3294dc",
    "bank_name": "TEST BANK",
    "fingerprint": "ecpwEzmBOSMOqQTL",
    "routing_number": "110000000",
    "swift_code": "TSTEZ122"
  },
  "amount": null,
  "client_secret": "src_client_secret_XDGV5PcFpAfh4klG76nYn6gH",
  "created": 1234567890,
  "currency": "usd",
  "flow": "receiver",
  "id": "src_1Pgc75B7WZ01zgkWn9ogkWOr",
  "livemode": false,
  "metadata": {},
  "object": "source",
  "owner": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": "[email protected]",
    "name": null,
    "phone": null,
    "verified_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "verified_email": null,
    "verified_name": null,
    "verified_phone": null
  },
  "receiver": {
    "address": "121042882-38381234567890123",
    "amount_charged": 0,
    "amount_received": 0,
    "amount_returned": 0,
    "refund_attributes_method": "email",
    "refund_attributes_status": "missing"
  },
  "statement_descriptor": null,
  "status": "pending",
  "type": "ach_credit_transfer",
  "usage": "reusable",
  "allow_redisplay": null
}

Update a source

POST/v1/sources/{source}

Updates the specified source by setting the values of the parameters passed. Any parameters not provided will be left unchanged. This request accepts the metadata and owner as arguments. It is also possible to update type specific information for selected payment methods. Please refer to our payment method guides for more detail.

Path parameters

  • sourcestringRequired

Body parameters

  • amountinteger

    Amount associated with the source.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • mandateobject

    Information about a mandate possibility attached to a source object (generally for bank debits) as well as its acceptance status.

    Show 5 child parameters
    • acceptanceobject
      Show 7 child parameters
      • statusstringRequired
        Possible values
        • accepted
        • pending
        • refused
        • revoked
      • dateinteger
      • ipstring
      • offlineobject

        Child parameters are listed in the OpenAPI document.

      • onlineobject

        Child parameters are listed in the OpenAPI document.

      • typestring
        Possible values
        • offline
        • online
      • user_agentstring
    • amountinteger
    • currencystring
    • intervalstring
      Possible values
      • one_time
      • scheduled
      • variable
    • notification_methodstring
      Possible values
      • deprecated_none
      • email
      • manual
      • none
      • stripe_email
  • 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.

  • ownerobject

    Information about the owner of the payment instrument that may be used or required by particular source types.

    Show 4 child parameters
    • addressobject
      Show 6 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
    • emailstring
    • namestring
    • phonestring
  • source_orderobject

    Information about the items and shipping associated with the source. Required for transactional credit (for example Klarna) sources before you can charge it.

    Show 2 child parameters
    • itemsarray of objects
      Show 6 child parameters
      • amountinteger
      • currencystring
      • descriptionstring
      • parentstring
      • quantityinteger
      • typestring
        Possible values
        • discount
        • shipping
        • sku
        • tax
    • shippingobject
      Show 5 child parameters
      • addressobjectRequired

        Child parameters are listed in the OpenAPI document.

      • carrierstring
      • namestring
      • phonestring
      • tracking_numberstring

Returns

The source object.

POST /v1/sources/{source}
curl https://api.knoxapi.com/v1/sources/src_1Pgc75B7WZ01zgkWn9ogkWOr \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "ach_credit_transfer": {
    "account_number": "test_52796e3294dc",
    "bank_name": "TEST BANK",
    "fingerprint": "ecpwEzmBOSMOqQTL",
    "routing_number": "110000000",
    "swift_code": "TSTEZ122"
  },
  "amount": null,
  "client_secret": "src_client_secret_XDGV5PcFpAfh4klG76nYn6gH",
  "created": 1234567890,
  "currency": "usd",
  "flow": "receiver",
  "id": "src_1Pgc75B7WZ01zgkWn9ogkWOr",
  "livemode": false,
  "metadata": {},
  "object": "source",
  "owner": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": "[email protected]",
    "name": null,
    "phone": null,
    "verified_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "verified_email": null,
    "verified_name": null,
    "verified_phone": null
  },
  "receiver": {
    "address": "121042882-38381234567890123",
    "amount_charged": 0,
    "amount_received": 0,
    "amount_returned": 0,
    "refund_attributes_method": "email",
    "refund_attributes_status": "missing"
  },
  "statement_descriptor": null,
  "status": "pending",
  "type": "ach_credit_transfer",
  "usage": "reusable",
  "allow_redisplay": null
}

Retrieve a source

GET/v1/sources/{source}

Retrieves an existing source object. Supply the unique source ID from a source creation request and Stripe will return the corresponding up-to-date source object information.

Path parameters

  • sourcestringRequired

Query parameters

  • client_secretstring

    The client secret of the source. Required if a publishable key is used to retrieve the source.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The source object.

GET /v1/sources/{source}
curl https://api.knoxapi.com/v1/sources/src_1Pgc75B7WZ01zgkWn9ogkWOr \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "ach_credit_transfer": {
    "account_number": "test_52796e3294dc",
    "bank_name": "TEST BANK",
    "fingerprint": "ecpwEzmBOSMOqQTL",
    "routing_number": "110000000",
    "swift_code": "TSTEZ122"
  },
  "amount": null,
  "client_secret": "src_client_secret_XDGV5PcFpAfh4klG76nYn6gH",
  "created": 1234567890,
  "currency": "usd",
  "flow": "receiver",
  "id": "src_1Pgc75B7WZ01zgkWn9ogkWOr",
  "livemode": false,
  "metadata": {},
  "object": "source",
  "owner": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": "[email protected]",
    "name": null,
    "phone": null,
    "verified_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "verified_email": null,
    "verified_name": null,
    "verified_phone": null
  },
  "receiver": {
    "address": "121042882-38381234567890123",
    "amount_charged": 0,
    "amount_received": 0,
    "amount_returned": 0,
    "refund_attributes_method": "email",
    "refund_attributes_status": "missing"
  },
  "statement_descriptor": null,
  "status": "pending",
  "type": "ach_credit_transfer",
  "usage": "reusable",
  "allow_redisplay": 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.