It looks like you're using Google Chrome - try our powerful extension! Find out more. Add to Chrome
x
Help Center Getting StartedGateway ConnectionCustom Integration

Custom Payment Integration

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.

Add Custom Integration as a Gateway

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.

Importing Data via the API

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.

API Authentication

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

Importing Duplicate Data

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.

Processing Changes via Webhooks

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.



Webhook Requests

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-4xFM3FK9QMBHVw3pZZJg8erm",
        "customer_id": "cus-example-gQz1mTFWid",
        "product_id": "prod-example-eC0cyv6fvL",
        "subscription_id": "sub-example-VgoD2iTR73",
        "transaction_id": "trans-example-21zAWA3lIJ",
        "customer_name": "Jane Customer",
        "customer_email": "jane@example.com",
        "customer_username": "janecustomer",
        "customer_country": "US",
        "description": "An example charge",
        "last_4_digits": "1234",
        "occurred": 1596675396,
        "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-4xFM3FK9QMBHVw3pZZJg8erm@chargedesk.com",
        "support_url": "https:\/\/chargedesk.com\/company-example\/example-4xFM3FK9QMBHVw3pZZJg8erm",
        "manage_url": "https:\/\/chargedesk.com\/manage\/company-example\/charges\/example-4xFM3FK9QMBHVw3pZZJg8erm",
        "invoice_url": "https:\/\/chargedesk.com\/company-example\/example-4xFM3FK9QMBHVw3pZZJg8erm\/invoice",
        "invoice_download_url": "https:\/\/chargedesk.com\/company-example\/example-4xFM3FK9QMBHVw3pZZJg8erm\/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-7hEV3GKqOZaLWL4dhn2w5wMx",
        "customer_id": "cus-example-RnnN0V9hZV",
        "product_id": "prod-example-M83eHTqXxL",
        "subscription_id": "sub-example-gclvJPAKEX",
        "transaction_id": "trans-example-kLgrTAYJDe",
        "customer_name": "Jane Customer",
        "customer_email": "jane@example.com",
        "customer_username": "janecustomer",
        "customer_country": "US",
        "description": "An example charge",
        "last_4_digits": "1234",
        "occurred": 1596675396,
        "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-7hEV3GKqOZaLWL4dhn2w5wMx@chargedesk.com",
        "support_url": "https:\/\/chargedesk.com\/company-example\/example-7hEV3GKqOZaLWL4dhn2w5wMx",
        "manage_url": "https:\/\/chargedesk.com\/manage\/company-example\/charges\/example-7hEV3GKqOZaLWL4dhn2w5wMx",
        "invoice_url": "https:\/\/chargedesk.com\/company-example\/example-7hEV3GKqOZaLWL4dhn2w5wMx\/invoice",
        "invoice_download_url": "https:\/\/chargedesk.com\/company-example\/example-7hEV3GKqOZaLWL4dhn2w5wMx\/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-AMBjC3kK3V",
        "customer_id": "cus-example-ZbTRJRFs4t",
        "product_id": "prod-example-8V1HtC6xbm",
        "amount": "34.00",
        "currency": "USD",
        "gateway_id": "",
        "interval": "month",
        "interval_count": 1,
        "charges": 1,
        "quantity": 2,
        "current_period_start": 1596675396,
        "current_period_end": 1599305139,
        "trial_start": 0,
        "trial_end": 1597884996,
        "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": 1596675396,
        "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-AMBjC3kK3V",
        "gateway_url": ""
    },
    "charge": {
        "amount": "34.00",
        "amount_refunded": "0.00",
        "currency": "USD",
        "payment_method": "Credit",
        "payment_method_brand": "Visa",
        "gateway_id": "",
        "charge_id": "example-U6rz2eDkvjYhDKThxsFaXgU8",
        "customer_id": "cus-example-75ABtS5qXU",
        "product_id": "prod-example-kTQ6UaGU96",
        "subscription_id": "sub-example-q0lzHXnD8p",
        "transaction_id": "trans-example-uajs4CpmoW",
        "customer_name": "Jane Customer",
        "customer_email": "jane@example.com",
        "customer_username": "janecustomer",
        "customer_country": "US",
        "description": "An example charge",
        "last_4_digits": "1234",
        "occurred": 1596675396,
        "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-U6rz2eDkvjYhDKThxsFaXgU8@chargedesk.com",
        "support_url": "https:\/\/chargedesk.com\/company-example\/example-U6rz2eDkvjYhDKThxsFaXgU8",
        "manage_url": "https:\/\/chargedesk.com\/manage\/company-example\/charges\/example-U6rz2eDkvjYhDKThxsFaXgU8",
        "invoice_url": "https:\/\/chargedesk.com\/company-example\/example-U6rz2eDkvjYhDKThxsFaXgU8\/invoice",
        "invoice_download_url": "https:\/\/chargedesk.com\/company-example\/example-U6rz2eDkvjYhDKThxsFaXgU8\/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-vE87l19l4W",
        "customer_id": "cus-example-yBuDXgLNJM",
        "product_id": "prod-example-Rpchd2UlIM",
        "amount": "34.00",
        "currency": "USD",
        "gateway_id": "",
        "interval": "month",
        "interval_count": 1,
        "charges": 1,
        "quantity": 2,
        "current_period_start": 1596675396,
        "current_period_end": 1599305139,
        "trial_start": 0,
        "trial_end": 1597884996,
        "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": 1596675396,
        "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-vE87l19l4W",
        "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-lq0KJyORg7",
        "customer_id": "cus-example-XAZcISxUQ7",
        "product_id": "prod-example-aqyByY0Wr6",
        "amount": "34.00",
        "currency": "USD",
        "gateway_id": "",
        "interval": "month",
        "interval_count": 1,
        "charges": 1,
        "quantity": 2,
        "current_period_start": 1596675396,
        "current_period_end": 1599305139,
        "trial_start": 0,
        "trial_end": 1597884996,
        "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": 1596675396,
        "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-lq0KJyORg7",
        "gateway_url": ""
    }
}

Webhook Responses

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.

Publishing the Integration

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.