API reference

Charges

The Charge object represents a single attempt to move money into your Stripe account. PaymentIntent confirmation is the most common way to create Charges, but Account Debits may also create Charges. Some legacy payment flows create Charges directly, which is not recommended for new integrations.

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 charge

POST/v1/charges

This method is no longer recommended—use the Payment Intents API to initiate a new payment instead. Confirmation of the PaymentIntent creates the Charge object used to request payment.

Body parameters

  • amountinteger

    Amount intended to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

  • application_feeinteger
  • application_fee_amountinteger

    A fee in cents (or local equivalent) that will be applied to the charge and transferred to the application owner's Stripe account. The request must be made with an OAuth key or the Stripe-Account header in order to take an application fee. For more information, see the application fees documentation.

  • captureboolean

    Whether to immediately capture the charge. Defaults to true. When false, the charge issues an authorization (or pre-authorization), and will need to be captured later. Uncaptured charges expire after a set number of days (7 by default). For more information, see the authorizing charges and settling later documentation.

  • cardobject | string

    A token, like the ones returned by Stripe.js.

    Show 16 child parameters
    • exp_monthintegerRequired
    • exp_yearintegerRequired
    • numberstringRequired
    • address_citystring
    • address_countrystring
    • address_line1string
    • address_line2string
    • address_statestring
    • address_zipstring
    • cvcstring
    • encryptedstring
    • metadataobject
    • namestring
    • network_tokenobject
      Show 1 child parameter
      • numberstring
    • objectstring
      Possible values
      • card
    • swipe_datastring
  • currencystring

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

  • customerstring

    The ID of an existing customer that will be charged in this request.

  • descriptionstring

    An arbitrary string which you can attach to a Charge object. It is displayed when in the web interface alongside the charge. Note that if you use Stripe to send automatic email receipts to your customers, your receipt emails will include the description of the charge(s) that they are describing.

  • destinationobject | string
    Show 2 child parameters
    • accountstringRequired
    • amountinteger
  • 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.

  • on_behalf_ofstring

    The Stripe account ID for which these funds are intended. You can specify the business of record as the connected account using the on_behalf_of attribute on the charge. For details, see Creating Separate Charges and Transfers.

  • radar_optionsobject

    Options to configure Radar. See Radar Session for more information.

    Show 1 child parameter
    • sessionstring
  • receipt_emailstring

    The email address to which this charge's receipt will be sent. The receipt will not be sent until the charge is paid, and no receipts will be sent for test mode charges. If this charge is for a Customer, the email address specified here will override the customer's email address. If receipt_email is specified for a charge in live mode, a receipt will be sent regardless of your email settings.

  • shippingobject

    Shipping information for the charge. Helps prevent fraud on charges for physical goods.

    Show 5 child parameters
    • addressobjectRequired
      Show 6 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
    • namestringRequired
    • carrierstring
    • phonestring
    • tracking_numberstring
  • sourcestring

    A payment source to be charged. This can be the ID of a card (i.e., credit or debit card), a bank account, a source, a token, or a connected account. For certain sources---namely, cards, bank accounts, and attached sources---you must also pass the ID of the associated customer.

  • statement_descriptorstring

    For a non-card charge, text that appears on the customer's statement as the statement descriptor. This value overrides the account's default statement descriptor. For information about requirements, including the 22-character limit, see the Statement Descriptor docs. For a card charge, this value is ignored unless you don't specify a statement_descriptor_suffix, in which case this value is used as the suffix.

  • statement_descriptor_suffixstring

    Provides information about a card charge. Concatenated to the account's statement descriptor prefix to form the complete statement descriptor that appears on the customer's statement. If the account has no prefix value, the suffix is concatenated to the account's statement descriptor.

  • transfer_dataobject

    An optional dictionary including the account to automatically transfer to as part of a destination charge. See the Connect documentation for details.

    Show 3 child parameters
    • destinationstringRequired
    • amountinteger
    • descriptionstring
  • transfer_groupstring

    A string that identifies this transaction as part of a group. For details, see Grouping transactions.

Returns

The charge object.

POST /v1/charges
curl -X POST https://api.knoxapi.com/v1/charges \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": 100,
  "amount_captured": 0,
  "amount_refunded": 0,
  "application": null,
  "application_fee": null,
  "application_fee_amount": null,
  "balance_transaction": "txn_1PgaxNB7WZ01zgkWEV3TLf40",
  "billing_details": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": null,
    "name": "Jenny Rosen",
    "phone": null,
    "tax_id": null
  },
  "calculated_statement_descriptor": null,
  "captured": false,
  "created": 1234567890,
  "currency": "usd",
  "customer": null,
  "description": "My First Test Charge (created for API docs)",
  "disputed": false,
  "failure_balance_transaction": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {},
  "id": "ch_1PgafuB7WZ01zgkWXYmPNZs8",
  "livemode": false,
  "metadata": {},
  "object": "charge",
  "on_behalf_of": null,
  "outcome": {
    "advice_code": null,
    "network_advice_code": null,
    "network_decline_code": null,
    "network_status": null,
    "reason": null,
    "seller_message": null,
    "type": "type"
  },
  "paid": true,
  "payment_intent": null,
  "payment_method": "card_1PgaftB7WZ01zgkWm3waTcFp",
  "payment_method_details": {
    "card": {
      "amount_authorized": null,
      "brand": "visa",
      "checks": {
        "address_line1_check": null,
        "address_postal_code_check": null,
        "cvc_check": "pass"
      },
      "country": "US",
      "exp_month": 8,
      "exp_year": 2030,
      "extended_authorization": {
        "status": "disabled"
      },
      "fingerprint": "AOB934RVNwzk6xtn",
      "funding": "credit",
      "incremental_authorization": {
        "status": "unavailable"
      },
      "installments": {
        "plan": {
          "count": null,
          "interval": null,
          "type": "fixed_count"
        }
      },
      "last4": "4242",
      "mandate": null,
      "multicapture": {
        "status": "unavailable"
      },
      "network": "visa",
      "network_token": {
        "used": false
      },
      "overcapture": {
        "maximum_amount_capturable": 100,
        "status": "unavailable"
      },
      "three_d_secure": {
        "authentication_flow": null,
        "electronic_commerce_indicator": null,
        "exemption_indicator": null,
        "result": null,
        "result_reason": null,
        "transaction_id": null,
        "version": null
      },
      "wallet": {
        "dynamic_last4": null,
        "type": "link"
      },
      "authorization_code": null,
      "regulated_status": null,
      "network_transaction_id": null,
      "transaction_link_id": null
    },
    "type": "card"
  },
  "receipt_email": null,
  "receipt_number": null,
  "receipt_url": "https://sangeekp-15t6ai--manage-mydev.dev.stripe.me/receipts/payment/CAcaFwoVYWNjdF8xUGdhZlRCN1daMDF6Z2tXKI_ei7UGMgZv2S_KfiY6LCJrxC7awazgQA9I88krZKw5uuCkZ5Nup2tomEtAbSpdfzjVZHO3ZYP5KFZP",
  "refunded": false,
  "refunds": {
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8/refunds"
  },
  "review": null,
  "shipping": {},
  "source_transfer": null,
  "statement_descriptor": null,
  "statement_descriptor_suffix": null,
  "status": "succeeded",
  "transfer_data": {
    "amount": null,
    "destination": {
      "id": "obj_123",
      "object": "account"
    }
  },
  "transfer_group": null,
  "source": {
    "allow_redisplay": null,
    "amount": null,
    "client_secret": "client_secret",
    "created": 1028554472,
    "currency": null,
    "flow": "flow",
    "id": "obj_123",
    "livemode": true,
    "metadata": null,
    "object": "source",
    "owner": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "email": null,
      "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
    },
    "statement_descriptor": null,
    "status": "status",
    "type": "ach_credit_transfer",
    "usage": null
  }
}

List all charges

GET/v1/charges

Returns a list of charges you’ve previously created. The charges are returned in sorted order, with the most recent charges appearing first.

Query parameters

  • createdobject | integer

    Only return charges that were created during the given date interval.

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

    Only return charges for the customer 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_intentstring

    Only return charges that were created by the PaymentIntent specified by this PaymentIntent ID.

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

  • transfer_groupstring

    Only return charges for this transfer group, limited to 100.

Returns

A list of charge objects.

GET /v1/charges
curl -G https://api.knoxapi.com/v1/charges \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/charges",
  "has_more": false,
  "data": [
    {
      "amount": 100,
      "amount_captured": 0,
      "amount_refunded": 0,
      "application": null,
      "application_fee": null,
      "application_fee_amount": null,
      "balance_transaction": "txn_1PgaxNB7WZ01zgkWEV3TLf40",
      "billing_details": {
        "address": {
          "city": null,
          "country": null,
          "line1": null,
          "line2": null,
          "postal_code": null,
          "state": null
        },
        "email": null,
        "name": "Jenny Rosen",
        "phone": null,
        "tax_id": null
      },
      "calculated_statement_descriptor": null,
      "captured": false,
      "created": 1234567890,
      "currency": "usd",
      "customer": null,
      "description": "My First Test Charge (created for API docs)",
      "disputed": false,
      "failure_balance_transaction": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {},
      "id": "ch_1PgafuB7WZ01zgkWXYmPNZs8",
      "livemode": false,
      "metadata": {},
      "object": "charge",
      "on_behalf_of": null,
      "outcome": {
        "advice_code": null,
        "network_advice_code": null,
        "network_decline_code": null,
        "network_status": null,
        "reason": null,
        "seller_message": null,
        "type": "type"
      },
      "paid": true,
      "payment_intent": null,
      "payment_method": "card_1PgaftB7WZ01zgkWm3waTcFp",
      "payment_method_details": {
        "card": {
          "amount_authorized": null,
          "brand": "visa",
          "checks": {
            "address_line1_check": null,
            "address_postal_code_check": null,
            "cvc_check": "pass"
          },
          "country": "US",
          "exp_month": 8,
          "exp_year": 2030,
          "extended_authorization": {
            "status": "disabled"
          },
          "fingerprint": "AOB934RVNwzk6xtn",
          "funding": "credit",
          "incremental_authorization": {
            "status": "unavailable"
          },
          "installments": {
            "plan": {
              "count": null,
              "interval": null,
              "type": "fixed_count"
            }
          },
          "last4": "4242",
          "mandate": null,
          "multicapture": {
            "status": "unavailable"
          },
          "network": "visa",
          "network_token": {
            "used": false
          },
          "overcapture": {
            "maximum_amount_capturable": 100,
            "status": "unavailable"
          },
          "three_d_secure": {
            "authentication_flow": null,
            "electronic_commerce_indicator": null,
            "exemption_indicator": null,
            "result": null,
            "result_reason": null,
            "transaction_id": null,
            "version": null
          },
          "wallet": {
            "dynamic_last4": null,
            "type": "link"
          },
          "authorization_code": null,
          "regulated_status": null,
          "network_transaction_id": null,
          "transaction_link_id": null
        },
        "type": "card"
      },
      "receipt_email": null,
      "receipt_number": null,
      "receipt_url": "https://sangeekp-15t6ai--manage-mydev.dev.stripe.me/receipts/payment/CAcaFwoVYWNjdF8xUGdhZlRCN1daMDF6Z2tXKI_ei7UGMgZv2S_KfiY6LCJrxC7awazgQA9I88krZKw5uuCkZ5Nup2tomEtAbSpdfzjVZHO3ZYP5KFZP",
      "refunded": false,
      "refunds": {
        "data": [],
        "has_more": false,
        "object": "list",
        "url": "/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8/refunds"
      },
      "review": null,
      "shipping": {},
      "source_transfer": null,
      "statement_descriptor": null,
      "statement_descriptor_suffix": null,
      "status": "succeeded",
      "transfer_data": {
        "amount": null,
        "destination": {
          "id": "obj_123",
          "object": "account"
        }
      },
      "transfer_group": null,
      "source": {
        "allow_redisplay": null,
        "amount": null,
        "client_secret": "client_secret",
        "created": 1028554472,
        "currency": null,
        "flow": "flow",
        "id": "obj_123",
        "livemode": true,
        "metadata": null,
        "object": "source",
        "owner": {
          "address": {
            "city": null,
            "country": null,
            "line1": null,
            "line2": null,
            "postal_code": null,
            "state": null
          },
          "email": null,
          "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
        },
        "statement_descriptor": null,
        "status": "status",
        "type": "ach_credit_transfer",
        "usage": null
      }
    }
  ]
}

Search charges

GET/v1/charges/search

Search for charges you’ve previously created using Stripe’s Search Query Language. Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.

Query parameters

  • querystringRequired

    The search query string. See search query language and the list of supported query fields for charges.

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

  • pagestring

    A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.

Returns

A search result of charge objects.

GET /v1/charges/search
curl -G https://api.knoxapi.com/v1/charges/search \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode "query=metadata['order_id']:'6735'"
Response
{
  "object": "search_result",
  "url": "/v1/charges/search",
  "has_more": false,
  "data": [
    {
      "amount": 100,
      "amount_captured": 0,
      "amount_refunded": 0,
      "application": null,
      "application_fee": null,
      "application_fee_amount": null,
      "balance_transaction": "txn_1PgaxNB7WZ01zgkWEV3TLf40",
      "billing_details": {
        "address": {
          "city": null,
          "country": null,
          "line1": null,
          "line2": null,
          "postal_code": null,
          "state": null
        },
        "email": null,
        "name": "Jenny Rosen",
        "phone": null,
        "tax_id": null
      },
      "calculated_statement_descriptor": null,
      "captured": false,
      "created": 1234567890,
      "currency": "usd",
      "customer": null,
      "description": "My First Test Charge (created for API docs)",
      "disputed": false,
      "failure_balance_transaction": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {},
      "id": "ch_1PgafuB7WZ01zgkWXYmPNZs8",
      "livemode": false,
      "metadata": {},
      "object": "charge",
      "on_behalf_of": null,
      "outcome": {
        "advice_code": null,
        "network_advice_code": null,
        "network_decline_code": null,
        "network_status": null,
        "reason": null,
        "seller_message": null,
        "type": "type"
      },
      "paid": true,
      "payment_intent": null,
      "payment_method": "card_1PgaftB7WZ01zgkWm3waTcFp",
      "payment_method_details": {
        "card": {
          "amount_authorized": null,
          "brand": "visa",
          "checks": {
            "address_line1_check": null,
            "address_postal_code_check": null,
            "cvc_check": "pass"
          },
          "country": "US",
          "exp_month": 8,
          "exp_year": 2030,
          "extended_authorization": {
            "status": "disabled"
          },
          "fingerprint": "AOB934RVNwzk6xtn",
          "funding": "credit",
          "incremental_authorization": {
            "status": "unavailable"
          },
          "installments": {
            "plan": {
              "count": null,
              "interval": null,
              "type": "fixed_count"
            }
          },
          "last4": "4242",
          "mandate": null,
          "multicapture": {
            "status": "unavailable"
          },
          "network": "visa",
          "network_token": {
            "used": false
          },
          "overcapture": {
            "maximum_amount_capturable": 100,
            "status": "unavailable"
          },
          "three_d_secure": {
            "authentication_flow": null,
            "electronic_commerce_indicator": null,
            "exemption_indicator": null,
            "result": null,
            "result_reason": null,
            "transaction_id": null,
            "version": null
          },
          "wallet": {
            "dynamic_last4": null,
            "type": "link"
          },
          "authorization_code": null,
          "regulated_status": null,
          "network_transaction_id": null,
          "transaction_link_id": null
        },
        "type": "card"
      },
      "receipt_email": null,
      "receipt_number": null,
      "receipt_url": "https://sangeekp-15t6ai--manage-mydev.dev.stripe.me/receipts/payment/CAcaFwoVYWNjdF8xUGdhZlRCN1daMDF6Z2tXKI_ei7UGMgZv2S_KfiY6LCJrxC7awazgQA9I88krZKw5uuCkZ5Nup2tomEtAbSpdfzjVZHO3ZYP5KFZP",
      "refunded": false,
      "refunds": {
        "data": [],
        "has_more": false,
        "object": "list",
        "url": "/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8/refunds"
      },
      "review": null,
      "shipping": {},
      "source_transfer": null,
      "statement_descriptor": null,
      "statement_descriptor_suffix": null,
      "status": "succeeded",
      "transfer_data": {
        "amount": null,
        "destination": {
          "id": "obj_123",
          "object": "account"
        }
      },
      "transfer_group": null,
      "source": {
        "allow_redisplay": null,
        "amount": null,
        "client_secret": "client_secret",
        "created": 1028554472,
        "currency": null,
        "flow": "flow",
        "id": "obj_123",
        "livemode": true,
        "metadata": null,
        "object": "source",
        "owner": {
          "address": {
            "city": null,
            "country": null,
            "line1": null,
            "line2": null,
            "postal_code": null,
            "state": null
          },
          "email": null,
          "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
        },
        "statement_descriptor": null,
        "status": "status",
        "type": "ach_credit_transfer",
        "usage": null
      }
    }
  ],
  "next_page": null
}

Update a charge

POST/v1/charges/{charge}

Updates the specified charge by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Path parameters

  • chargestringRequired

Body parameters

  • customerstring

    The ID of an existing customer that will be associated with this request. This field may only be updated if there is no existing associated customer with this charge.

  • descriptionstring

    An arbitrary string which you can attach to a charge object. It is displayed when in the web interface alongside the charge. Note that if you use Stripe to send automatic email receipts to your customers, your receipt emails will include the description of the charge(s) that they are describing.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • fraud_detailsobject

    A set of key-value pairs you can attach to a charge giving information about its riskiness. If you believe a charge is fraudulent, include a user_report key with a value of fraudulent. If you believe a charge is safe, include a user_report key with a value of safe. Stripe will use the information you send to improve our fraud detection algorithms.

    Show 1 child parameter
    • user_reportstringRequired
      Possible values
      • fraudulent
      • safe
  • 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.

  • receipt_emailstring

    This is the email address that the receipt for this charge will be sent to. If this field is updated, then a new email receipt will be sent to the updated address.

  • shippingobject

    Shipping information for the charge. Helps prevent fraud on charges for physical goods.

    Show 5 child parameters
    • addressobjectRequired
      Show 6 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
    • namestringRequired
    • carrierstring
    • phonestring
    • tracking_numberstring
  • transfer_groupstring

    A string that identifies this transaction as part of a group. transfer_group may only be provided if it has not been set. See the Connect documentation for details.

Returns

The charge object.

POST /v1/charges/{charge}
curl https://api.knoxapi.com/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "amount": 100,
  "amount_captured": 0,
  "amount_refunded": 0,
  "application": null,
  "application_fee": null,
  "application_fee_amount": null,
  "balance_transaction": "txn_1PgaxNB7WZ01zgkWEV3TLf40",
  "billing_details": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": null,
    "name": "Jenny Rosen",
    "phone": null,
    "tax_id": null
  },
  "calculated_statement_descriptor": null,
  "captured": false,
  "created": 1234567890,
  "currency": "usd",
  "customer": null,
  "description": "My First Test Charge (created for API docs)",
  "disputed": false,
  "failure_balance_transaction": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {},
  "id": "ch_1PgafuB7WZ01zgkWXYmPNZs8",
  "livemode": false,
  "metadata": {},
  "object": "charge",
  "on_behalf_of": null,
  "outcome": {
    "advice_code": null,
    "network_advice_code": null,
    "network_decline_code": null,
    "network_status": null,
    "reason": null,
    "seller_message": null,
    "type": "type"
  },
  "paid": true,
  "payment_intent": null,
  "payment_method": "card_1PgaftB7WZ01zgkWm3waTcFp",
  "payment_method_details": {
    "card": {
      "amount_authorized": null,
      "brand": "visa",
      "checks": {
        "address_line1_check": null,
        "address_postal_code_check": null,
        "cvc_check": "pass"
      },
      "country": "US",
      "exp_month": 8,
      "exp_year": 2030,
      "extended_authorization": {
        "status": "disabled"
      },
      "fingerprint": "AOB934RVNwzk6xtn",
      "funding": "credit",
      "incremental_authorization": {
        "status": "unavailable"
      },
      "installments": {
        "plan": {
          "count": null,
          "interval": null,
          "type": "fixed_count"
        }
      },
      "last4": "4242",
      "mandate": null,
      "multicapture": {
        "status": "unavailable"
      },
      "network": "visa",
      "network_token": {
        "used": false
      },
      "overcapture": {
        "maximum_amount_capturable": 100,
        "status": "unavailable"
      },
      "three_d_secure": {
        "authentication_flow": null,
        "electronic_commerce_indicator": null,
        "exemption_indicator": null,
        "result": null,
        "result_reason": null,
        "transaction_id": null,
        "version": null
      },
      "wallet": {
        "dynamic_last4": null,
        "type": "link"
      },
      "authorization_code": null,
      "regulated_status": null,
      "network_transaction_id": null,
      "transaction_link_id": null
    },
    "type": "card"
  },
  "receipt_email": null,
  "receipt_number": null,
  "receipt_url": "https://sangeekp-15t6ai--manage-mydev.dev.stripe.me/receipts/payment/CAcaFwoVYWNjdF8xUGdhZlRCN1daMDF6Z2tXKI_ei7UGMgZv2S_KfiY6LCJrxC7awazgQA9I88krZKw5uuCkZ5Nup2tomEtAbSpdfzjVZHO3ZYP5KFZP",
  "refunded": false,
  "refunds": {
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8/refunds"
  },
  "review": null,
  "shipping": {},
  "source_transfer": null,
  "statement_descriptor": null,
  "statement_descriptor_suffix": null,
  "status": "succeeded",
  "transfer_data": {
    "amount": null,
    "destination": {
      "id": "obj_123",
      "object": "account"
    }
  },
  "transfer_group": null,
  "source": {
    "allow_redisplay": null,
    "amount": null,
    "client_secret": "client_secret",
    "created": 1028554472,
    "currency": null,
    "flow": "flow",
    "id": "obj_123",
    "livemode": true,
    "metadata": null,
    "object": "source",
    "owner": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "email": null,
      "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
    },
    "statement_descriptor": null,
    "status": "status",
    "type": "ach_credit_transfer",
    "usage": null
  }
}

Retrieve a charge

GET/v1/charges/{charge}

Retrieves the details of a charge that has previously been created. Supply the unique charge ID that was returned from your previous request, and Stripe will return the corresponding charge information. The same information is returned when creating or refunding the charge.

Path parameters

  • chargestringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The charge object.

GET /v1/charges/{charge}
curl https://api.knoxapi.com/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": 100,
  "amount_captured": 0,
  "amount_refunded": 0,
  "application": null,
  "application_fee": null,
  "application_fee_amount": null,
  "balance_transaction": "txn_1PgaxNB7WZ01zgkWEV3TLf40",
  "billing_details": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": null,
    "name": "Jenny Rosen",
    "phone": null,
    "tax_id": null
  },
  "calculated_statement_descriptor": null,
  "captured": false,
  "created": 1234567890,
  "currency": "usd",
  "customer": null,
  "description": "My First Test Charge (created for API docs)",
  "disputed": false,
  "failure_balance_transaction": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {},
  "id": "ch_1PgafuB7WZ01zgkWXYmPNZs8",
  "livemode": false,
  "metadata": {},
  "object": "charge",
  "on_behalf_of": null,
  "outcome": {
    "advice_code": null,
    "network_advice_code": null,
    "network_decline_code": null,
    "network_status": null,
    "reason": null,
    "seller_message": null,
    "type": "type"
  },
  "paid": true,
  "payment_intent": null,
  "payment_method": "card_1PgaftB7WZ01zgkWm3waTcFp",
  "payment_method_details": {
    "card": {
      "amount_authorized": null,
      "brand": "visa",
      "checks": {
        "address_line1_check": null,
        "address_postal_code_check": null,
        "cvc_check": "pass"
      },
      "country": "US",
      "exp_month": 8,
      "exp_year": 2030,
      "extended_authorization": {
        "status": "disabled"
      },
      "fingerprint": "AOB934RVNwzk6xtn",
      "funding": "credit",
      "incremental_authorization": {
        "status": "unavailable"
      },
      "installments": {
        "plan": {
          "count": null,
          "interval": null,
          "type": "fixed_count"
        }
      },
      "last4": "4242",
      "mandate": null,
      "multicapture": {
        "status": "unavailable"
      },
      "network": "visa",
      "network_token": {
        "used": false
      },
      "overcapture": {
        "maximum_amount_capturable": 100,
        "status": "unavailable"
      },
      "three_d_secure": {
        "authentication_flow": null,
        "electronic_commerce_indicator": null,
        "exemption_indicator": null,
        "result": null,
        "result_reason": null,
        "transaction_id": null,
        "version": null
      },
      "wallet": {
        "dynamic_last4": null,
        "type": "link"
      },
      "authorization_code": null,
      "regulated_status": null,
      "network_transaction_id": null,
      "transaction_link_id": null
    },
    "type": "card"
  },
  "receipt_email": null,
  "receipt_number": null,
  "receipt_url": "https://sangeekp-15t6ai--manage-mydev.dev.stripe.me/receipts/payment/CAcaFwoVYWNjdF8xUGdhZlRCN1daMDF6Z2tXKI_ei7UGMgZv2S_KfiY6LCJrxC7awazgQA9I88krZKw5uuCkZ5Nup2tomEtAbSpdfzjVZHO3ZYP5KFZP",
  "refunded": false,
  "refunds": {
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8/refunds"
  },
  "review": null,
  "shipping": {},
  "source_transfer": null,
  "statement_descriptor": null,
  "statement_descriptor_suffix": null,
  "status": "succeeded",
  "transfer_data": {
    "amount": null,
    "destination": {
      "id": "obj_123",
      "object": "account"
    }
  },
  "transfer_group": null,
  "source": {
    "allow_redisplay": null,
    "amount": null,
    "client_secret": "client_secret",
    "created": 1028554472,
    "currency": null,
    "flow": "flow",
    "id": "obj_123",
    "livemode": true,
    "metadata": null,
    "object": "source",
    "owner": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "email": null,
      "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
    },
    "statement_descriptor": null,
    "status": "status",
    "type": "ach_credit_transfer",
    "usage": null
  }
}

Capture a charge

POST/v1/charges/{charge}/capture

Capture the payment of an existing, uncaptured charge that was created with the capture option set to false. Uncaptured payments expire a set number of days after they are created (7 by default), after which they are marked as refunded and capture attempts will fail. Don’t use this method to capture a PaymentIntent-initiated charge. Use Capture a PaymentIntent.

Path parameters

  • chargestringRequired

Body parameters

  • amountinteger

    The amount to capture, which must be less than or equal to the original amount.

  • application_feeinteger

    An application fee to add on to this charge.

  • application_fee_amountinteger

    An application fee amount to add on to this charge, which must be less than or equal to the original amount.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • receipt_emailstring

    The email address to send this charge's receipt to. This will override the previously-specified email address for this charge, if one was set. Receipts will not be sent in test mode.

  • statement_descriptorstring

    For a non-card charge, text that appears on the customer's statement as the statement descriptor. This value overrides the account's default statement descriptor. For information about requirements, including the 22-character limit, see the Statement Descriptor docs. For a card charge, this value is ignored unless you don't specify a statement_descriptor_suffix, in which case this value is used as the suffix.

  • statement_descriptor_suffixstring

    Provides information about a card charge. Concatenated to the account's statement descriptor prefix to form the complete statement descriptor that appears on the customer's statement. If the account has no prefix value, the suffix is concatenated to the account's statement descriptor.

  • transfer_dataobject

    An optional dictionary including the account to automatically transfer to as part of a destination charge. See the Connect documentation for details.

    Show 1 child parameter
    • amountinteger
  • transfer_groupstring

    A string that identifies this transaction as part of a group. transfer_group may only be provided if it has not been set. See the Connect documentation for details.

Returns

The charge object.

POST /v1/charges/{charge}/capture
curl -X POST https://api.knoxapi.com/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8/capture \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": 100,
  "amount_captured": 0,
  "amount_refunded": 0,
  "application": null,
  "application_fee": null,
  "application_fee_amount": null,
  "balance_transaction": "txn_1PgaxNB7WZ01zgkWEV3TLf40",
  "billing_details": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": null,
    "name": "Jenny Rosen",
    "phone": null,
    "tax_id": null
  },
  "calculated_statement_descriptor": null,
  "captured": false,
  "created": 1234567890,
  "currency": "usd",
  "customer": null,
  "description": "My First Test Charge (created for API docs)",
  "disputed": false,
  "failure_balance_transaction": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {},
  "id": "ch_1PgafuB7WZ01zgkWXYmPNZs8",
  "livemode": false,
  "metadata": {},
  "object": "charge",
  "on_behalf_of": null,
  "outcome": {
    "advice_code": null,
    "network_advice_code": null,
    "network_decline_code": null,
    "network_status": null,
    "reason": null,
    "seller_message": null,
    "type": "type"
  },
  "paid": true,
  "payment_intent": null,
  "payment_method": "card_1PgaftB7WZ01zgkWm3waTcFp",
  "payment_method_details": {
    "card": {
      "amount_authorized": null,
      "brand": "visa",
      "checks": {
        "address_line1_check": null,
        "address_postal_code_check": null,
        "cvc_check": "pass"
      },
      "country": "US",
      "exp_month": 8,
      "exp_year": 2030,
      "extended_authorization": {
        "status": "disabled"
      },
      "fingerprint": "AOB934RVNwzk6xtn",
      "funding": "credit",
      "incremental_authorization": {
        "status": "unavailable"
      },
      "installments": {
        "plan": {
          "count": null,
          "interval": null,
          "type": "fixed_count"
        }
      },
      "last4": "4242",
      "mandate": null,
      "multicapture": {
        "status": "unavailable"
      },
      "network": "visa",
      "network_token": {
        "used": false
      },
      "overcapture": {
        "maximum_amount_capturable": 100,
        "status": "unavailable"
      },
      "three_d_secure": {
        "authentication_flow": null,
        "electronic_commerce_indicator": null,
        "exemption_indicator": null,
        "result": null,
        "result_reason": null,
        "transaction_id": null,
        "version": null
      },
      "wallet": {
        "dynamic_last4": null,
        "type": "link"
      },
      "authorization_code": null,
      "regulated_status": null,
      "network_transaction_id": null,
      "transaction_link_id": null
    },
    "type": "card"
  },
  "receipt_email": null,
  "receipt_number": null,
  "receipt_url": "https://sangeekp-15t6ai--manage-mydev.dev.stripe.me/receipts/payment/CAcaFwoVYWNjdF8xUGdhZlRCN1daMDF6Z2tXKI_ei7UGMgZv2S_KfiY6LCJrxC7awazgQA9I88krZKw5uuCkZ5Nup2tomEtAbSpdfzjVZHO3ZYP5KFZP",
  "refunded": false,
  "refunds": {
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8/refunds"
  },
  "review": null,
  "shipping": {},
  "source_transfer": null,
  "statement_descriptor": null,
  "statement_descriptor_suffix": null,
  "status": "succeeded",
  "transfer_data": {
    "amount": null,
    "destination": {
      "id": "obj_123",
      "object": "account"
    }
  },
  "transfer_group": null,
  "source": {
    "allow_redisplay": null,
    "amount": null,
    "client_secret": "client_secret",
    "created": 1028554472,
    "currency": null,
    "flow": "flow",
    "id": "obj_123",
    "livemode": true,
    "metadata": null,
    "object": "source",
    "owner": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "email": null,
      "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
    },
    "statement_descriptor": null,
    "status": "status",
    "type": "ach_credit_transfer",
    "usage": null
  }
}

POST /v1/charges/{charge}/dispute

POST/v1/charges/{charge}/dispute

Path parameters

  • chargestringRequired

Body parameters

  • evidenceobject

    Evidence to upload, to respond to a dispute. Updating any field in the hash will submit all fields in the hash for review. The combined character count of all fields is limited to 150,000.

    Show 28 child parameters
    • access_activity_logstring
    • billing_addressstring
    • cancellation_policystring
    • cancellation_policy_disclosurestring
    • cancellation_rebuttalstring
    • customer_communicationstring
    • customer_email_addressstring
    • customer_namestring
    • customer_purchase_ipstring
    • customer_signaturestring
    • duplicate_charge_documentationstring
    • duplicate_charge_explanationstring
    • duplicate_charge_idstring
    • enhanced_evidenceobject
      Show 3 child parameters
    • product_descriptionstring
    • receiptstring
    • refund_policystring
    • refund_policy_disclosurestring
    • refund_refusal_explanationstring
    • service_datestring
    • service_documentationstring
    • shipping_addressstring
    • shipping_carrierstring
    • shipping_datestring
    • shipping_documentationstring
    • shipping_tracking_numberstring
    • uncategorized_filestring
    • uncategorized_textstring
  • 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.

  • submitboolean

    Whether to immediately submit evidence to the bank. If false, evidence is staged on the dispute. Staged evidence is visible in the API and Dashboard, and can be submitted to the bank by making another request with this attribute set to true (the default).

Returns

The dispute object.

POST /v1/charges/{charge}/dispute
curl -X POST https://api.knoxapi.com/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8/dispute \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": 1000,
  "balance_transactions": [],
  "charge": "ch_1PgafuB7WZ01zgkWXYmPNZs8",
  "created": 1234567890,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null,
    "enhanced_evidence": {}
  },
  "evidence_details": {
    "due_by": 1723679999,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0,
    "enhanced_eligibility": {}
  },
  "id": "dp_1Pgc71B7WZ01zgkWMevJiAUx",
  "is_charge_refundable": true,
  "livemode": false,
  "metadata": {},
  "object": "dispute",
  "payment_intent": null,
  "payment_method_details": {
    "card": {
      "brand": "visa",
      "case_type": "inquiry",
      "network_reason_code": "10.4",
      "network": "visa"
    },
    "type": "card"
  },
  "reason": "general",
  "status": "warning_needs_response",
  "enhanced_eligibility_types": [
    "visa_compelling_evidence_3"
  ]
}

GET /v1/charges/{charge}/dispute

GET/v1/charges/{charge}/dispute

Retrieve a dispute for a specified charge.

Path parameters

  • chargestringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The dispute object.

GET /v1/charges/{charge}/dispute
curl https://api.knoxapi.com/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8/dispute \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": 1000,
  "balance_transactions": [],
  "charge": "ch_1PgafuB7WZ01zgkWXYmPNZs8",
  "created": 1234567890,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null,
    "enhanced_evidence": {}
  },
  "evidence_details": {
    "due_by": 1723679999,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0,
    "enhanced_eligibility": {}
  },
  "id": "dp_1Pgc71B7WZ01zgkWMevJiAUx",
  "is_charge_refundable": true,
  "livemode": false,
  "metadata": {},
  "object": "dispute",
  "payment_intent": null,
  "payment_method_details": {
    "card": {
      "brand": "visa",
      "case_type": "inquiry",
      "network_reason_code": "10.4",
      "network": "visa"
    },
    "type": "card"
  },
  "reason": "general",
  "status": "warning_needs_response",
  "enhanced_eligibility_types": [
    "visa_compelling_evidence_3"
  ]
}

Create a refund

POST/v1/charges/{charge}/refund

When you create a new refund, you must specify either a Charge or a PaymentIntent object. This action refunds a previously created charge that’s not refunded yet. Funds are refunded to the credit or debit card that’s originally charged. You can optionally refund only part of a charge. You can repeat this until the entire charge is refunded. After you entirely refund a charge, you can’t refund it again. This method raises an error when it’s called on an already-refunded charge, or when you attempt to refund more money than is left on a charge.

Path parameters

  • chargestringRequired

    The identifier of the charge to refund.

Body parameters

  • amountinteger

    A positive integer in the smallest currency unit representing how much of this charge to refund. Can refund only up to the remaining, unrefunded amount of the charge.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • instructions_emailstring

    For payment methods without native refund support (e.g., Konbini, PromptPay), use this email from the customer to receive refund instructions.

  • 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

    The identifier of the PaymentIntent to refund.

  • reasonstring

    String indicating the reason for the refund. If set, possible values are duplicate, fraudulent, and requested_by_customer. If you believe the charge to be fraudulent, specifying fraudulent as the reason will add the associated card and email to your block lists, and will also help us improve our fraud detection algorithms.

    Possible values
    • duplicate
    • fraudulent
    • requested_by_customer
  • 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.

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

POST /v1/charges/{charge}/refund
curl -X POST https://api.knoxapi.com/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8/refund \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": 100,
  "amount_captured": 0,
  "amount_refunded": 0,
  "application": null,
  "application_fee": null,
  "application_fee_amount": null,
  "balance_transaction": "txn_1PgaxNB7WZ01zgkWEV3TLf40",
  "billing_details": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": null,
    "name": "Jenny Rosen",
    "phone": null,
    "tax_id": null
  },
  "calculated_statement_descriptor": null,
  "captured": false,
  "created": 1234567890,
  "currency": "usd",
  "customer": null,
  "description": "My First Test Charge (created for API docs)",
  "disputed": false,
  "failure_balance_transaction": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {},
  "id": "ch_1PgafuB7WZ01zgkWXYmPNZs8",
  "livemode": false,
  "metadata": {},
  "object": "charge",
  "on_behalf_of": null,
  "outcome": {
    "advice_code": null,
    "network_advice_code": null,
    "network_decline_code": null,
    "network_status": null,
    "reason": null,
    "seller_message": null,
    "type": "type"
  },
  "paid": true,
  "payment_intent": null,
  "payment_method": "card_1PgaftB7WZ01zgkWm3waTcFp",
  "payment_method_details": {
    "card": {
      "amount_authorized": null,
      "brand": "visa",
      "checks": {
        "address_line1_check": null,
        "address_postal_code_check": null,
        "cvc_check": "pass"
      },
      "country": "US",
      "exp_month": 8,
      "exp_year": 2030,
      "extended_authorization": {
        "status": "disabled"
      },
      "fingerprint": "AOB934RVNwzk6xtn",
      "funding": "credit",
      "incremental_authorization": {
        "status": "unavailable"
      },
      "installments": {
        "plan": {
          "count": null,
          "interval": null,
          "type": "fixed_count"
        }
      },
      "last4": "4242",
      "mandate": null,
      "multicapture": {
        "status": "unavailable"
      },
      "network": "visa",
      "network_token": {
        "used": false
      },
      "overcapture": {
        "maximum_amount_capturable": 100,
        "status": "unavailable"
      },
      "three_d_secure": {
        "authentication_flow": null,
        "electronic_commerce_indicator": null,
        "exemption_indicator": null,
        "result": null,
        "result_reason": null,
        "transaction_id": null,
        "version": null
      },
      "wallet": {
        "dynamic_last4": null,
        "type": "link"
      },
      "authorization_code": null,
      "regulated_status": null,
      "network_transaction_id": null,
      "transaction_link_id": null
    },
    "type": "card"
  },
  "receipt_email": null,
  "receipt_number": null,
  "receipt_url": "https://sangeekp-15t6ai--manage-mydev.dev.stripe.me/receipts/payment/CAcaFwoVYWNjdF8xUGdhZlRCN1daMDF6Z2tXKI_ei7UGMgZv2S_KfiY6LCJrxC7awazgQA9I88krZKw5uuCkZ5Nup2tomEtAbSpdfzjVZHO3ZYP5KFZP",
  "refunded": false,
  "refunds": {
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8/refunds"
  },
  "review": null,
  "shipping": {},
  "source_transfer": null,
  "statement_descriptor": null,
  "statement_descriptor_suffix": null,
  "status": "succeeded",
  "transfer_data": {
    "amount": null,
    "destination": {
      "id": "obj_123",
      "object": "account"
    }
  },
  "transfer_group": null,
  "source": {
    "allow_redisplay": null,
    "amount": null,
    "client_secret": "client_secret",
    "created": 1028554472,
    "currency": null,
    "flow": "flow",
    "id": "obj_123",
    "livemode": true,
    "metadata": null,
    "object": "source",
    "owner": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "email": null,
      "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
    },
    "statement_descriptor": null,
    "status": "status",
    "type": "ach_credit_transfer",
    "usage": null
  }
}

Create a refund

POST/v1/charges/{charge}/refunds

When you create a new refund, you must specify a Charge or a PaymentIntent object on which to create it. Creating a new refund will refund a charge that has previously been created but not yet refunded. Funds will be refunded to the credit or debit card that was originally charged. You can optionally refund only part of a charge. You can do so multiple times, until the entire charge has been refunded. Once entirely refunded, a charge can’t be refunded again. This method will raise an error when called on an already-refunded charge, or when trying to refund more money than is left on a charge.

Path parameters

  • chargestringRequired

    The identifier of the charge to refund.

Body parameters

  • amountinteger
  • currencystring

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

  • customerstring

    Customer whose customer balance to refund from.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • instructions_emailstring

    For payment methods without native refund support (e.g., Konbini, PromptPay), use this email from the customer to receive refund instructions.

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

  • originstring

    Origin of the refund

    Possible values
    • customer_balance
  • payment_intentstring

    The identifier of the PaymentIntent to refund.

  • reasonstring

    String indicating the reason for the refund. If set, possible values are duplicate, fraudulent, and requested_by_customer. If you believe the charge to be fraudulent, specifying fraudulent as the reason will add the associated card and email to your block lists, and will also help us improve our fraud detection algorithms.

    Possible values
    • duplicate
    • fraudulent
    • requested_by_customer
  • 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.

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

POST /v1/charges/{charge}/refunds
curl -X POST https://api.knoxapi.com/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8/refunds \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_1PgafuB7WZ01zgkWXYmPNZs8",
  "created": 1234567890,
  "currency": "usd",
  "destination_details": {
    "card": {
      "type": "reversal"
    },
    "type": "card"
  },
  "id": "re_1Pgc72B7WZ01zgkWqPvrRrPE",
  "metadata": {},
  "object": "refund",
  "payment_intent": null,
  "reason": null,
  "receipt_number": null,
  "source_transfer_reversal": null,
  "status": "succeeded",
  "transfer_reversal": null,
  "customer": null,
  "customer_account": null,
  "payment_method": null
}

List all refunds

GET/v1/charges/{charge}/refunds

You can see a list of the refunds belonging to a specific charge. Note that the 10 most recent refunds are always available by default on the charge object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional refunds.

Path parameters

  • chargestringRequired

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 refund objects.

GET /v1/charges/{charge}/refunds
curl -G https://api.knoxapi.com/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8/refunds \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/charges",
  "has_more": false,
  "data": [
    {
      "amount": 100,
      "balance_transaction": null,
      "charge": "ch_1PgafuB7WZ01zgkWXYmPNZs8",
      "created": 1234567890,
      "currency": "usd",
      "destination_details": {
        "card": {
          "type": "reversal"
        },
        "type": "card"
      },
      "id": "re_1Pgc72B7WZ01zgkWqPvrRrPE",
      "metadata": {},
      "object": "refund",
      "payment_intent": null,
      "reason": null,
      "receipt_number": null,
      "source_transfer_reversal": null,
      "status": "succeeded",
      "transfer_reversal": null,
      "customer": null,
      "customer_account": null,
      "payment_method": null
    }
  ]
}

POST /v1/charges/{charge}/dispute/close

POST/v1/charges/{charge}/dispute/close

Path parameters

  • chargestringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The dispute object.

POST /v1/charges/{charge}/dispute/close
curl -X POST https://api.knoxapi.com/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8/dispute/close \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": 1000,
  "balance_transactions": [],
  "charge": "ch_1PgafuB7WZ01zgkWXYmPNZs8",
  "created": 1234567890,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null,
    "enhanced_evidence": {}
  },
  "evidence_details": {
    "due_by": 1723679999,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0,
    "enhanced_eligibility": {}
  },
  "id": "dp_1Pgc71B7WZ01zgkWMevJiAUx",
  "is_charge_refundable": true,
  "livemode": false,
  "metadata": {},
  "object": "dispute",
  "payment_intent": null,
  "payment_method_details": {
    "card": {
      "brand": "visa",
      "case_type": "inquiry",
      "network_reason_code": "10.4",
      "network": "visa"
    },
    "type": "card"
  },
  "reason": "general",
  "status": "warning_needs_response",
  "enhanced_eligibility_types": [
    "visa_compelling_evidence_3"
  ]
}

POST /v1/charges/{charge}/refunds/{refund}

POST/v1/charges/{charge}/refunds/{refund}

Update a specified refund.

Path parameters

  • chargestringRequired
  • refundstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • metadataobject

Returns

The refund object.

POST /v1/charges/{charge}/refunds/{refund}
curl https://api.knoxapi.com/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8/refunds/re_1Pgc72B7WZ01zgkWqPvrRrPE \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_1PgafuB7WZ01zgkWXYmPNZs8",
  "created": 1234567890,
  "currency": "usd",
  "destination_details": {
    "card": {
      "type": "reversal"
    },
    "type": "card"
  },
  "id": "re_1Pgc72B7WZ01zgkWqPvrRrPE",
  "metadata": {},
  "object": "refund",
  "payment_intent": null,
  "reason": null,
  "receipt_number": null,
  "source_transfer_reversal": null,
  "status": "succeeded",
  "transfer_reversal": null,
  "customer": null,
  "customer_account": null,
  "payment_method": null
}

GET /v1/charges/{charge}/refunds/{refund}

GET/v1/charges/{charge}/refunds/{refund}

Retrieves the details of an existing refund.

Path parameters

  • chargestringRequired
  • refundstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The refund object.

GET /v1/charges/{charge}/refunds/{refund}
curl https://api.knoxapi.com/v1/charges/ch_1PgafuB7WZ01zgkWXYmPNZs8/refunds/re_1Pgc72B7WZ01zgkWqPvrRrPE \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_1PgafuB7WZ01zgkWXYmPNZs8",
  "created": 1234567890,
  "currency": "usd",
  "destination_details": {
    "card": {
      "type": "reversal"
    },
    "type": "card"
  },
  "id": "re_1Pgc72B7WZ01zgkWqPvrRrPE",
  "metadata": {},
  "object": "refund",
  "payment_intent": null,
  "reason": null,
  "receipt_number": null,
  "source_transfer_reversal": null,
  "status": "succeeded",
  "transfer_reversal": null,
  "customer": null,
  "customer_account": null,
  "payment_method": 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.