Add to Chrome
x
Add to Chrome
ChargeDesk supports integrating any payment platform using our API and custom webhooks. If you use a gateway which is not currently supported by ChargeDesk, or you would like to add custom logic to your billing support workflow, you can use these custom integration tools.
Integrating a custom payment platform with ChargeDesk requires some custom development. There's two key parts to the integration; Importing Data via the API and Processing Changes via Webhooks.
If you do not already have a custom integration added to your account, you will need to add this as a new gateway. You can do this from Setup > Gateways > Add Gateway > Choose "Custom Integration" from the top of the list;
If you would like to route agent actions for an existing gateway to your custom integration (for example to process Stripe cancellation via a custom endpoint), please contact support so we can enable this for your company.
Data can be imported to ChargeDesk using the ChargeDesk API. We recommend importing any data you would like made visible to support agents. At a minimum we recommend import data about any Charges, Customers and Subscriptions for the connected company.
The ChargeDesk API is authenticated using HTTP Basic Authentication. You can pass your secret key in the basic auth username. A password is not required.
Each company you create on ChargeDesk has their own secret key and must have API access enabled. You can turn on API access for your company and find your secret key at https://chargedesk.com/connect/api
Charges, Customers, Subscriptions and Products all have unique IDs (transaction_id for Charges, customer_id for Customers, subscription_id for Subscriptions and product_id for Products). When importing data from your system, you may not always know if the relevant resource has already been imported into ChargeDesk.
When this is the case, to save duplicating API calls, you can set duplicate=update on any of the creation endpoints for these resources. If existing data matching the unique ID for the resource already exists, the request will not fail and instead will update the relevant resource with the latest data.
In order to process changes made by agents via ChargeDesk, you will need to support receiving ChargeDesk webhooks. Custom webhooks can be configured from Setup > Gateways > Configure next to your Custom Integration.
You should set the "Base Path" to be a URL you control which can receive custom ChargeDesk webhooks. Adding "Headers" allows you to add additional information to these webhooks such as authentication headers. Both the Base Path and Headers support replacing any of the fields in the webhook object payload by wrapping the field ID in opening and closing brackets. For example setting a header to Charge: {charge_id} will add the charge ID as a header to any webhook which contains charge information.
Also on this page, you can find sections which allow you to enable individual custom webhook paths. Enabling a webhook path will enable that functionality on your ChargeDesk account.
Perform full or partial refunds of paid charges. The following parameters will be sent with a refund request;
| refund_amount | The amount to being refunded. |
|---|---|
| action_reason | The reason provided by the support agent for the refund (if any). |
| charge | The charge object being refunded. |
Example refund payload;
{
"refund_amount": 12.34,
"action_reason": "Customer received incorrect product",
"charge": {
"amount": "34.00",
"amount_refunded": "0.00",
"currency": "USD",
"payment_method": "Credit",
"payment_method_brand": "Visa",
"gateway_id": "",
"charge_id": "example-bCyQJz8TwmnIVau58ZZKgS1X",
"customer_id": "cus-example-FgT8Nr0dnl",
"product_id": "prod-example-lpHnttlN4i",
"subscription_id": "sub-example-Y4Y2Rzsfil",
"transaction_id": "transaction-example-pbFMC7lI7Q",
"customer_name": "Jane Customer",
"customer_email": "jane@example.com",
"customer_username": "janecustomer",
"customer_country": "US",
"description": "An example charge",
"last_4_digits": "1234",
"occurred": 1722048177,
"object": "charge",
"amount_with_commas": "34.00",
"amount_refunded_formatted": "$0.00 USD",
"amount_symbol": "$",
"amount_formatted": "$34.00 USD",
"is_paid": true,
"status": "paid",
"status_text": "paid",
"support_email": "company-example+example-bCyQJz8TwmnIVau58ZZKgS1X@chargedesk.com",
"support_url": "https:\/\/chargedesk.com\/company-example\/example-bCyQJz8TwmnIVau58ZZKgS1X",
"manage_url": "https:\/\/chargedesk.com\/manage\/company-example\/charges\/example-bCyQJz8TwmnIVau58ZZKgS1X",
"invoice_url": "https:\/\/chargedesk.com\/company-example\/example-bCyQJz8TwmnIVau58ZZKgS1X\/invoice",
"invoice_download_url": "https:\/\/chargedesk.com\/company-example\/example-bCyQJz8TwmnIVau58ZZKgS1X\/invoice\/download",
"customer_phone": null,
"methods_supported": [
"edit",
"remind",
"email"
],
"methods_active": [
"email"
],
"occurred_relative": "moments ago",
"occurred_formatted": "moments ago",
"payment_method_describe": "Visa credit card",
"added_tax": "0.00",
"invoice_company": null,
"company": "company-example",
"metadata": {
"example_key": "Example charge metadata"
},
"logs": [],
"gateway_url": "",
"sent_invoice": "",
"sent_invoice_reminder": "",
"refunded_at_formatted": "",
"product_desc": "",
"name_email": "receipt",
"email_last_sent": 0,
"name_send_email": "Send Receipt"
}
}Capture or void previously authorized charges. The following parameters will be sent with a capture/void request;
| charge | The charge object being captured. |
|---|
Example capture/void payload;
{
"charge": {
"amount": "34.00",
"amount_refunded": "0.00",
"currency": "USD",
"payment_method": "Credit",
"payment_method_brand": "Visa",
"gateway_id": "",
"charge_id": "example-tAsZm2UL7Bg1iVz5D5VzQlE5",
"customer_id": "cus-example-wFl4qGutHf",
"product_id": "prod-example-aCFAklHsgT",
"subscription_id": "sub-example-ObSC2ZVRRr",
"transaction_id": "transaction-example-NTEMVIfFjx",
"customer_name": "Jane Customer",
"customer_email": "jane@example.com",
"customer_username": "janecustomer",
"customer_country": "US",
"description": "An example charge",
"last_4_digits": "1234",
"occurred": 1722048177,
"object": "charge",
"amount_with_commas": "34.00",
"amount_refunded_formatted": "$0.00 USD",
"amount_symbol": "$",
"amount_formatted": "$34.00 USD",
"is_paid": true,
"status": "paid",
"status_text": "paid",
"support_email": "company-example+example-tAsZm2UL7Bg1iVz5D5VzQlE5@chargedesk.com",
"support_url": "https:\/\/chargedesk.com\/company-example\/example-tAsZm2UL7Bg1iVz5D5VzQlE5",
"manage_url": "https:\/\/chargedesk.com\/manage\/company-example\/charges\/example-tAsZm2UL7Bg1iVz5D5VzQlE5",
"invoice_url": "https:\/\/chargedesk.com\/company-example\/example-tAsZm2UL7Bg1iVz5D5VzQlE5\/invoice",
"invoice_download_url": "https:\/\/chargedesk.com\/company-example\/example-tAsZm2UL7Bg1iVz5D5VzQlE5\/invoice\/download",
"customer_phone": null,
"methods_supported": [
"edit",
"remind",
"email"
],
"methods_active": [
"email"
],
"occurred_relative": "moments ago",
"occurred_formatted": "moments ago",
"payment_method_describe": "Visa credit card",
"added_tax": "0.00",
"invoice_company": null,
"company": "company-example",
"metadata": {
"example_key": "Example charge metadata"
},
"logs": [],
"gateway_url": "",
"sent_invoice": "",
"sent_invoice_reminder": "",
"refunded_at_formatted": "",
"product_desc": "",
"name_email": "receipt",
"email_last_sent": 0,
"name_send_email": "Send Receipt"
}
}Cancel active subscriptions. The following parameters will be sent with a cancel request;
| action | Can be 'cancel', 'cancel-immediately', 'cancel-period-end' or 'suspend'. |
|---|---|
| refund | Available if 'action' is 'cancel-immediately'. Can be 'none', 'partial' (perform a pro-rated refund of last transaction), 'full' (perform a full refund of last transaction). |
| action_reason | The reason provided by the support agent for the cancellation (if any). |
| subscription | The subscription object being cancelled. |
| charge | Available if 'refund' is not 'none'. The charge object being refunded. |
Example cancel payload;
{
"action": "cancel-immediately",
"refund": "partial",
"action_reason": "Customer is planning on upgrading subscription",
"subscription": {
"subscription_id": "sub-example-oRmIN7yui8",
"customer_id": "cus-example-NiNK5KuhTC",
"product_id": "prod-example-UP0Qf59Ldj",
"amount": "34.00",
"currency": "USD",
"gateway_id": "",
"interval": "month",
"interval_count": 1,
"charges": 1,
"quantity": 2,
"current_period_start": 1722048177,
"current_period_end": 1724677920,
"trial_start": 0,
"trial_end": 1723257777,
"ended_at": 0,
"canceled_at": 0,
"has_items": 0,
"billing_cycles_total": 0,
"billing_cycles_current": 1,
"trial_period_days": 14,
"setup_amount": 10,
"object": "subscription",
"amount_formatted": "2x $34.00 USD",
"amount_symbol": "$",
"status": "active",
"status_text": "Active",
"first_seen": 1722048177,
"methods_supported": [
"edit"
],
"methods_active": [
"edit"
],
"readable_interval": "Monthly",
"product_desc": "",
"company": "company-example",
"logs": [],
"items": [],
"metadata": {
"example_key": "Example subscription metadata"
},
"manage_url": "https:\/\/chargedesk.com\/manage\/company-example\/subscriptions\/sub-example-oRmIN7yui8",
"gateway_url": ""
},
"charge": {
"amount": "34.00",
"amount_refunded": "0.00",
"currency": "USD",
"payment_method": "Credit",
"payment_method_brand": "Visa",
"gateway_id": "",
"charge_id": "example-5q9W4DZkOlzTUu1PzDhA9Zpd",
"customer_id": "cus-example-wK6M51lY42",
"product_id": "prod-example-4vjv00g8w2",
"subscription_id": "sub-example-3HUbJPHik4",
"transaction_id": "transaction-example-MKNDvNn0tT",
"customer_name": "Jane Customer",
"customer_email": "jane@example.com",
"customer_username": "janecustomer",
"customer_country": "US",
"description": "An example charge",
"last_4_digits": "1234",
"occurred": 1722048177,
"object": "charge",
"amount_with_commas": "34.00",
"amount_refunded_formatted": "$0.00 USD",
"amount_symbol": "$",
"amount_formatted": "$34.00 USD",
"is_paid": true,
"status": "paid",
"status_text": "paid",
"support_email": "company-example+example-5q9W4DZkOlzTUu1PzDhA9Zpd@chargedesk.com",
"support_url": "https:\/\/chargedesk.com\/company-example\/example-5q9W4DZkOlzTUu1PzDhA9Zpd",
"manage_url": "https:\/\/chargedesk.com\/manage\/company-example\/charges\/example-5q9W4DZkOlzTUu1PzDhA9Zpd",
"invoice_url": "https:\/\/chargedesk.com\/company-example\/example-5q9W4DZkOlzTUu1PzDhA9Zpd\/invoice",
"invoice_download_url": "https:\/\/chargedesk.com\/company-example\/example-5q9W4DZkOlzTUu1PzDhA9Zpd\/invoice\/download",
"customer_phone": null,
"methods_supported": [
"edit",
"remind",
"email"
],
"methods_active": [
"email"
],
"occurred_relative": "moments ago",
"occurred_formatted": "moments ago",
"payment_method_describe": "Visa credit card",
"added_tax": "0.00",
"invoice_company": null,
"company": "company-example",
"metadata": {
"example_key": "Example charge metadata"
},
"logs": [],
"gateway_url": "",
"sent_invoice": "",
"sent_invoice_reminder": "",
"refunded_at_formatted": "",
"product_desc": "",
"name_email": "receipt",
"email_last_sent": 0,
"name_send_email": "Send Receipt"
}
}Reactivate suspended or pending cancellation subscriptions. The following parameters will be sent with a reactivate request;
| subscription | The subscription object being reactivated. |
|---|
Example reactivate payload;
{
"subscription": {
"subscription_id": "sub-example-iWTFNHrlLL",
"customer_id": "cus-example-1k10oyUpc9",
"product_id": "prod-example-LQLw6ucjt5",
"amount": "34.00",
"currency": "USD",
"gateway_id": "",
"interval": "month",
"interval_count": 1,
"charges": 1,
"quantity": 2,
"current_period_start": 1722048177,
"current_period_end": 1724677920,
"trial_start": 0,
"trial_end": 1723257777,
"ended_at": 0,
"canceled_at": 0,
"has_items": 0,
"billing_cycles_total": 0,
"billing_cycles_current": 1,
"trial_period_days": 14,
"setup_amount": 10,
"object": "subscription",
"amount_formatted": "2x $34.00 USD",
"amount_symbol": "$",
"status": "active",
"status_text": "Active",
"first_seen": 1722048177,
"methods_supported": [
"edit"
],
"methods_active": [
"edit"
],
"readable_interval": "Monthly",
"product_desc": "",
"company": "company-example",
"logs": [],
"items": [],
"metadata": {
"example_key": "Example subscription metadata"
},
"manage_url": "https:\/\/chargedesk.com\/manage\/company-example\/subscriptions\/sub-example-iWTFNHrlLL",
"gateway_url": ""
}
}Edit subscription plans. The following parameters will be sent with a edit plans request;
| plans | A list of new plans and quantities to be applied on the subscription. Any existing plans should be replaced with this new list. |
|---|---|
| subscription | The subscription object being edited. |
Example edit plans payload;
{
"plans": [
{
"product_id": "prod-example-AyL17r5mIC",
"quantity": 2
}
],
"subscription": {
"subscription_id": "sub-example-daURnbA0qh",
"customer_id": "cus-example-Q6EgBqWQ2K",
"product_id": "prod-example-Dz3ETNP0aT",
"amount": "34.00",
"currency": "USD",
"gateway_id": "",
"interval": "month",
"interval_count": 1,
"charges": 1,
"quantity": 2,
"current_period_start": 1722048177,
"current_period_end": 1724677920,
"trial_start": 0,
"trial_end": 1723257777,
"ended_at": 0,
"canceled_at": 0,
"has_items": 0,
"billing_cycles_total": 0,
"billing_cycles_current": 1,
"trial_period_days": 14,
"setup_amount": 10,
"object": "subscription",
"amount_formatted": "2x $34.00 USD",
"amount_symbol": "$",
"status": "active",
"status_text": "Active",
"first_seen": 1722048177,
"methods_supported": [
"edit"
],
"methods_active": [
"edit"
],
"readable_interval": "Monthly",
"product_desc": "",
"company": "company-example",
"logs": [],
"items": [],
"metadata": {
"example_key": "Example subscription metadata"
},
"manage_url": "https:\/\/chargedesk.com\/manage\/company-example\/subscriptions\/sub-example-daURnbA0qh",
"gateway_url": ""
}
}Request a new payment from a customer. Endpoint must return a 'redirect_url' parameter to a payment page. The following parameters will be sent with a payment request;
| charge | The charge object for invoice. |
|---|
Example payment payload;
{
"charge": {
"amount": "34.00",
"amount_refunded": "0.00",
"currency": "USD",
"payment_method": "Credit",
"payment_method_brand": "Visa",
"gateway_id": "",
"charge_id": "example-uWTLAZfhBbhCZXyaxjNykgxQ",
"customer_id": "cus-example-0BSIyFW8Z7",
"product_id": "prod-example-UbtMMaiVMD",
"subscription_id": "sub-example-9zGGhECBbJ",
"transaction_id": "transaction-example-LSvLVRraNP",
"customer_name": "Jane Customer",
"customer_email": "jane@example.com",
"customer_username": "janecustomer",
"customer_country": "US",
"description": "An example charge",
"last_4_digits": "1234",
"occurred": 1722048177,
"object": "charge",
"amount_with_commas": "34.00",
"amount_refunded_formatted": "$0.00 USD",
"amount_symbol": "$",
"amount_formatted": "$34.00 USD",
"is_paid": true,
"status": "paid",
"status_text": "paid",
"support_email": "company-example+example-uWTLAZfhBbhCZXyaxjNykgxQ@chargedesk.com",
"support_url": "https:\/\/chargedesk.com\/company-example\/example-uWTLAZfhBbhCZXyaxjNykgxQ",
"manage_url": "https:\/\/chargedesk.com\/manage\/company-example\/charges\/example-uWTLAZfhBbhCZXyaxjNykgxQ",
"invoice_url": "https:\/\/chargedesk.com\/company-example\/example-uWTLAZfhBbhCZXyaxjNykgxQ\/invoice",
"invoice_download_url": "https:\/\/chargedesk.com\/company-example\/example-uWTLAZfhBbhCZXyaxjNykgxQ\/invoice\/download",
"customer_phone": null,
"methods_supported": [
"edit",
"remind",
"email"
],
"methods_active": [
"email"
],
"occurred_relative": "moments ago",
"occurred_formatted": "moments ago",
"payment_method_describe": "Visa credit card",
"added_tax": "0.00",
"invoice_company": null,
"company": "company-example",
"metadata": {
"example_key": "Example charge metadata"
},
"logs": [],
"gateway_url": "",
"sent_invoice": "",
"sent_invoice_reminder": "",
"refunded_at_formatted": "",
"product_desc": "",
"name_email": "receipt",
"email_last_sent": 0,
"name_send_email": "Send Receipt"
}
}To acknowledge successful processing of a custom integration webhook, your endpoint must return a 2xx HTTP status code (e.g. 200). If a 2xx status code is not returned, the agent will receive an error message that the action could not be performed. Additionally you can return a JSON payload with an error key which contains a message that can be displayed to the agent. This is an example of an error response;
{
"error": "Refund amount was greater than amount remaining on charge."
}As agents are immediately notified of a failure, custom integration webhooks are not retried.
Upon successful action, we recommend that the webhook response contains an object with a list of fields to update corresponding to the action. This allows agents to immediately see, if say a charge was refunded.
{
"subscription": {
"status": "cancelled",
},
"charge": {
"status": "partially refunded",
"amount_refunded" : 11.23
}
}You may also pass back an entire charge, customer, subscription or product object with fields matching those on the API documentation for updating their record.
However, response objects are optional. If not provided, ChargeDesk will automatically update corresponding objects with the appropriate data. For example, a charge will show as refunded or a subscription cancelled. However using response objects ensures data consistency between your system and ChargeDesk. As the update object state is shown to agents immediately after performing an action, having this data come directly from your system provides for manual review by the agent and a sanity check if any processing has been performed incorrectly.
ChargeDesk supports converting custom integrations into core integrations available to anyone using ChargeDesk. This allows payment gateways and storefronts to easily integrate with ChargeDesk to leverage our helpdesk integrations and other payment services.
Once you have built your custom integration, please contact support if you would like to publish your integration to all users.