It looks like you're using Google Chrome - try our powerful extension! Find out more. Add to Chrome
x

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; 1. Importing Data via the API and 2. Processing Changes via Webhooks.

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

2. Processing Changes via Webhooks

In order to process changes made by agents via ChargeDesk, you will need to support receiving ChargeDesk webhooks. These webhooks can be enabled from Setup > Gateways > Configure next to your Custom Integration. 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-lc1VkTjGppnPL9WYXTolfQeo",
        "customer_id": "cus-example-RCqsUdtp8x",
        "product_id": "prod-example-RsbkrRpY14",
        "subscription_id": "sub-example-k8FuWUkxkW",
        "transaction_id": "trans-example-oCHpvfGMO6",
        "customer_name": "Jane Customer",
        "customer_email": "jane@example.com",
        "customer_username": "janecustomer",
        "customer_country": "US",
        "description": "An example charge",
        "last_4_digits": "1234",
        "occurred": 1585619531,
        "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-lc1VkTjGppnPL9WYXTolfQeo@chargedesk.com",
        "support_url": "https:\/\/chargedesk.com\/company-example\/example-lc1VkTjGppnPL9WYXTolfQeo",
        "manage_url": "https:\/\/chargedesk.com\/manage\/company-example\/charges\/example-lc1VkTjGppnPL9WYXTolfQeo",
        "invoice_url": "https:\/\/chargedesk.com\/company-example\/example-lc1VkTjGppnPL9WYXTolfQeo\/invoice",
        "invoice_download_url": "https:\/\/chargedesk.com\/company-example\/example-lc1VkTjGppnPL9WYXTolfQeo\/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-6zkfuZnQgamZFJEK1bSB0grG",
        "customer_id": "cus-example-W0D9HF10jV",
        "product_id": "prod-example-8PkFbmkmeF",
        "subscription_id": "sub-example-P8rsdzJmGD",
        "transaction_id": "trans-example-b5t5VGrgil",
        "customer_name": "Jane Customer",
        "customer_email": "jane@example.com",
        "customer_username": "janecustomer",
        "customer_country": "US",
        "description": "An example charge",
        "last_4_digits": "1234",
        "occurred": 1585619531,
        "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-6zkfuZnQgamZFJEK1bSB0grG@chargedesk.com",
        "support_url": "https:\/\/chargedesk.com\/company-example\/example-6zkfuZnQgamZFJEK1bSB0grG",
        "manage_url": "https:\/\/chargedesk.com\/manage\/company-example\/charges\/example-6zkfuZnQgamZFJEK1bSB0grG",
        "invoice_url": "https:\/\/chargedesk.com\/company-example\/example-6zkfuZnQgamZFJEK1bSB0grG\/invoice",
        "invoice_download_url": "https:\/\/chargedesk.com\/company-example\/example-6zkfuZnQgamZFJEK1bSB0grG\/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-SGINTTzkKQ",
        "customer_id": "cus-example-kYiD0Q5g4b",
        "product_id": "prod-example-3TiCUBVkio",
        "amount": "34.00",
        "currency": "USD",
        "gateway_id": "",
        "interval": "month",
        "interval_count": 1,
        "charges": 1,
        "quantity": 2,
        "current_period_start": 1585619531,
        "current_period_end": 1588249274,
        "trial_start": 0,
        "trial_end": 1586829131,
        "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": 1585619531,
        "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-SGINTTzkKQ",
        "gateway_url": ""
    },
    "charge": {
        "amount": "34.00",
        "amount_refunded": "0.00",
        "currency": "USD",
        "payment_method": "Credit",
        "payment_method_brand": "Visa",
        "gateway_id": "",
        "charge_id": "example-nxq1eFRiT841MiBB3aZ0WQQQ",
        "customer_id": "cus-example-tNYvUT8tfy",
        "product_id": "prod-example-fi0RQRXEx6",
        "subscription_id": "sub-example-VbkMyhV2sq",
        "transaction_id": "trans-example-9AgsKZpm90",
        "customer_name": "Jane Customer",
        "customer_email": "jane@example.com",
        "customer_username": "janecustomer",
        "customer_country": "US",
        "description": "An example charge",
        "last_4_digits": "1234",
        "occurred": 1585619531,
        "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-nxq1eFRiT841MiBB3aZ0WQQQ@chargedesk.com",
        "support_url": "https:\/\/chargedesk.com\/company-example\/example-nxq1eFRiT841MiBB3aZ0WQQQ",
        "manage_url": "https:\/\/chargedesk.com\/manage\/company-example\/charges\/example-nxq1eFRiT841MiBB3aZ0WQQQ",
        "invoice_url": "https:\/\/chargedesk.com\/company-example\/example-nxq1eFRiT841MiBB3aZ0WQQQ\/invoice",
        "invoice_download_url": "https:\/\/chargedesk.com\/company-example\/example-nxq1eFRiT841MiBB3aZ0WQQQ\/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-UHZLXJtnRE",
        "customer_id": "cus-example-QNgY6Oxehy",
        "product_id": "prod-example-XhGUcy2wPE",
        "amount": "34.00",
        "currency": "USD",
        "gateway_id": "",
        "interval": "month",
        "interval_count": 1,
        "charges": 1,
        "quantity": 2,
        "current_period_start": 1585619531,
        "current_period_end": 1588249274,
        "trial_start": 0,
        "trial_end": 1586829131,
        "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": 1585619531,
        "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-UHZLXJtnRE",
        "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.