API reference

Topups

To top up your Stripe balance, you create a top-up object. You can retrieve individual top-ups, as well as list all top-ups. Top-ups are identified by a unique, random ID. Related guide: Topping up your platform account

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 top-up

POST/v1/topups

Top up the balance of an account

Body parameters

  • amountintegerRequired

    A positive integer representing how much to transfer.

  • currencystringRequired

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

  • descriptionstring

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

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

    The ID of a PaymentMethod representing the payment method to be used for the top-up. A PaymentMethod of type us_bank_account can be used.

  • payment_method_optionsobject

    Payment method-specific configuration for this top-up.

    Show 1 child parameter
    • us_bank_accountobject
      Show 1 child parameter
      • networkstringRequired
        Possible values
        • ach
  • sourcestring

    The ID of a source to transfer funds from. For most users, this should be left unspecified which will use the bank account that was set up in the dashboard for the specified currency. In test mode, this can be a test bank token (see Testing Top-ups).

  • statement_descriptorstring

    Extra information about a top-up for the source's bank statement. Limited to 15 ASCII characters.

  • transfer_groupstring

    A string that identifies this top-up as part of a group.

Returns

The topup object.

POST /v1/topups
curl https://api.knoxapi.com/v1/topups \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d amount=1000 \
  -d currency=usd
Response
{
  "amount": 1000,
  "balance_transaction": null,
  "created": 1234567890,
  "currency": "usd",
  "description": "Top-up description",
  "expected_availability_date": 123456789,
  "failure_code": null,
  "failure_message": null,
  "id": "tu_1Pgc7BB7WZ01zgkWwH7rkBgR",
  "livemode": false,
  "metadata": {
    "order_id": "12345678"
  },
  "object": "topup",
  "source": {
    "ach_debit": {
      "bank_name": "STRIPE TEST BANK",
      "country": "US",
      "fingerprint": "5Wh4KBcfDrz5IOnx",
      "last4": "6789",
      "routing_number": "110000000",
      "type": "individual"
    },
    "amount": null,
    "client_secret": "src_client_secret_9HxmifVKxP2LNNRRod7Q23HM",
    "created": 1721954073,
    "currency": "usd",
    "flow": "code_verification",
    "id": "src_1Pgc7BB7WZ01zgkWXWC57xAu",
    "livemode": false,
    "metadata": {},
    "object": "source",
    "owner": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "email": "[email protected]",
      "name": "Jenny Rosen",
      "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
    },
    "statement_descriptor": null,
    "status": "pending",
    "type": "ach_debit",
    "usage": "reusable",
    "allow_redisplay": null
  },
  "statement_descriptor": null,
  "status": "pending",
  "transfer_group": null,
  "initiated_by": null
}

List all top-ups

GET/v1/topups

Returns a list of top-ups.

Query parameters

  • amountobject | integer

    A positive integer representing how much to transfer.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • 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
  • 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.

  • statusstring

    Only return top-ups that have the given status. One of canceled, failed, pending or succeeded.

    Possible values
    • canceled
    • failed
    • pending
    • succeeded

Returns

A list of topup objects.

GET /v1/topups
curl -G https://api.knoxapi.com/v1/topups \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/topups",
  "has_more": false,
  "data": [
    {
      "amount": 1000,
      "balance_transaction": null,
      "created": 1234567890,
      "currency": "usd",
      "description": "Top-up description",
      "expected_availability_date": 123456789,
      "failure_code": null,
      "failure_message": null,
      "id": "tu_1Pgc7BB7WZ01zgkWwH7rkBgR",
      "livemode": false,
      "metadata": {
        "order_id": "12345678"
      },
      "object": "topup",
      "source": {
        "ach_debit": {
          "bank_name": "STRIPE TEST BANK",
          "country": "US",
          "fingerprint": "5Wh4KBcfDrz5IOnx",
          "last4": "6789",
          "routing_number": "110000000",
          "type": "individual"
        },
        "amount": null,
        "client_secret": "src_client_secret_9HxmifVKxP2LNNRRod7Q23HM",
        "created": 1721954073,
        "currency": "usd",
        "flow": "code_verification",
        "id": "src_1Pgc7BB7WZ01zgkWXWC57xAu",
        "livemode": false,
        "metadata": {},
        "object": "source",
        "owner": {
          "address": {
            "city": null,
            "country": null,
            "line1": null,
            "line2": null,
            "postal_code": null,
            "state": null
          },
          "email": "[email protected]",
          "name": "Jenny Rosen",
          "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
        },
        "statement_descriptor": null,
        "status": "pending",
        "type": "ach_debit",
        "usage": "reusable",
        "allow_redisplay": null
      },
      "statement_descriptor": null,
      "status": "pending",
      "transfer_group": null,
      "initiated_by": null
    }
  ]
}

Update a top-up

POST/v1/topups/{topup}

Updates the metadata of a top-up. Other top-up details are not editable by design.

Path parameters

  • topupstringRequired

Body parameters

  • descriptionstring

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

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

POST /v1/topups/{topup}
curl https://api.knoxapi.com/v1/topups/tu_1Pgc7BB7WZ01zgkWwH7rkBgR \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "amount": 1000,
  "balance_transaction": null,
  "created": 1234567890,
  "currency": "usd",
  "description": "Top-up description",
  "expected_availability_date": 123456789,
  "failure_code": null,
  "failure_message": null,
  "id": "tu_1Pgc7BB7WZ01zgkWwH7rkBgR",
  "livemode": false,
  "metadata": {
    "order_id": "12345678"
  },
  "object": "topup",
  "source": {
    "ach_debit": {
      "bank_name": "STRIPE TEST BANK",
      "country": "US",
      "fingerprint": "5Wh4KBcfDrz5IOnx",
      "last4": "6789",
      "routing_number": "110000000",
      "type": "individual"
    },
    "amount": null,
    "client_secret": "src_client_secret_9HxmifVKxP2LNNRRod7Q23HM",
    "created": 1721954073,
    "currency": "usd",
    "flow": "code_verification",
    "id": "src_1Pgc7BB7WZ01zgkWXWC57xAu",
    "livemode": false,
    "metadata": {},
    "object": "source",
    "owner": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "email": "[email protected]",
      "name": "Jenny Rosen",
      "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
    },
    "statement_descriptor": null,
    "status": "pending",
    "type": "ach_debit",
    "usage": "reusable",
    "allow_redisplay": null
  },
  "statement_descriptor": null,
  "status": "pending",
  "transfer_group": null,
  "initiated_by": null
}

Retrieve a top-up

GET/v1/topups/{topup}

Retrieves the details of a top-up that has previously been created. Supply the unique top-up ID that was returned from your previous request, and Stripe will return the corresponding top-up information.

Path parameters

  • topupstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The topup object.

GET /v1/topups/{topup}
curl https://api.knoxapi.com/v1/topups/tu_1Pgc7BB7WZ01zgkWwH7rkBgR \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": 1000,
  "balance_transaction": null,
  "created": 1234567890,
  "currency": "usd",
  "description": "Top-up description",
  "expected_availability_date": 123456789,
  "failure_code": null,
  "failure_message": null,
  "id": "tu_1Pgc7BB7WZ01zgkWwH7rkBgR",
  "livemode": false,
  "metadata": {
    "order_id": "12345678"
  },
  "object": "topup",
  "source": {
    "ach_debit": {
      "bank_name": "STRIPE TEST BANK",
      "country": "US",
      "fingerprint": "5Wh4KBcfDrz5IOnx",
      "last4": "6789",
      "routing_number": "110000000",
      "type": "individual"
    },
    "amount": null,
    "client_secret": "src_client_secret_9HxmifVKxP2LNNRRod7Q23HM",
    "created": 1721954073,
    "currency": "usd",
    "flow": "code_verification",
    "id": "src_1Pgc7BB7WZ01zgkWXWC57xAu",
    "livemode": false,
    "metadata": {},
    "object": "source",
    "owner": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "email": "[email protected]",
      "name": "Jenny Rosen",
      "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
    },
    "statement_descriptor": null,
    "status": "pending",
    "type": "ach_debit",
    "usage": "reusable",
    "allow_redisplay": null
  },
  "statement_descriptor": null,
  "status": "pending",
  "transfer_group": null,
  "initiated_by": null
}

Cancel a top-up

POST/v1/topups/{topup}/cancel

Cancels a top-up. Only pending top-ups can be canceled.

Path parameters

  • topupstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The topup object.

POST /v1/topups/{topup}/cancel
curl -X POST https://api.knoxapi.com/v1/topups/tu_1Pgc7BB7WZ01zgkWwH7rkBgR/cancel \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": 1000,
  "balance_transaction": null,
  "created": 1234567890,
  "currency": "usd",
  "description": "Top-up description",
  "expected_availability_date": 123456789,
  "failure_code": null,
  "failure_message": null,
  "id": "tu_1Pgc7BB7WZ01zgkWwH7rkBgR",
  "livemode": false,
  "metadata": {
    "order_id": "12345678"
  },
  "object": "topup",
  "source": {
    "ach_debit": {
      "bank_name": "STRIPE TEST BANK",
      "country": "US",
      "fingerprint": "5Wh4KBcfDrz5IOnx",
      "last4": "6789",
      "routing_number": "110000000",
      "type": "individual"
    },
    "amount": null,
    "client_secret": "src_client_secret_9HxmifVKxP2LNNRRod7Q23HM",
    "created": 1721954073,
    "currency": "usd",
    "flow": "code_verification",
    "id": "src_1Pgc7BB7WZ01zgkWXWC57xAu",
    "livemode": false,
    "metadata": {},
    "object": "source",
    "owner": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "email": "[email protected]",
      "name": "Jenny Rosen",
      "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
    },
    "statement_descriptor": null,
    "status": "pending",
    "type": "ach_debit",
    "usage": "reusable",
    "allow_redisplay": null
  },
  "statement_descriptor": null,
  "status": "pending",
  "transfer_group": null,
  "initiated_by": 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.