LiveChat Billing API

Introduction

The LiveChat Billing API allows you to charge for your apps in the LiveChat Marketplace. Therefore, you can offer paid applications to over 34,000 LiveChat customers.

The Billing API is a collective name for a subset of smaller APIs used for specific purposes (see the APIs section below for details).

Overview

Payment types

The Billing API supports the following payment types:

direct charges (one-time charges)
subscriptions
per-usage payments (coming soon)

Additional options

It also handles a set of features to facilitate the payment and accounting processes:

credit card processing
invoices - coming soon

Getting started

Example apps

Billing Demo app

A sample front-end app that implements Billing API to offer in-app payments.

It's available on GitHub: https://github.com/livechat/billing-demo

Agent App Widget

A sample LiveChat Agent App Widget that offers in-app payment using Billing API.

It's available on GitHub: https://github.com/livechat/billing-demo-agent-app-extension

User guide

1. Authorization

The Billing API is based on the LiveChat OAuth authorization flow. All endpoints require access tokens, and some endpoints are limited by scope or client ID.

2. APIs

2.1. Direct Charges

The Direct Charges API allows you to collect one-time fees.

Use cases:

Collecting a single charge for an application in the Marketplace
Collecting in-app micropayments
Charging for additional features in the apps

2.2. Ledger

The Ledger API lets you manage the financial activity and balance. In other words, it will show you the purchase history and your earnings.

Use cases:

Checking the balance
Checking the billing history

2.3. Recurrent Charges

The Recurrent Charges API handles periodic payments. For example, you can offer an app that costs \$10 per month.

Use cases:

Viewing the subscriptions
Updating the subscriptions

Direct charges

The Direct Charges API is a tool to collect one-time fees (also called "direct charges").

Statuses

There are six possible direct charge statuses:

Status	Description
`pending`	the charge has been created and is awaiting user interaction
`accepted`	the charge has been accepted by the user
`declined`	the charge has been declined by the user
`processed`	the charge is being processed by a payment gateway
`failed`	the charge could not be collected
`success`	the charge has been collected

Flows

There are three possible direct charge flows:

pending -> accepted -> processed -> failed
pending -> accepted -> processed -> success
pending -> declined

Usage

Create a charge for a user (POST /v1/direct_charge) and redirect them to the confirmation_url.
After the user confirms or declines the charge, they will be redirected to return_url with charge id passed as a URL param.
Based on id, you can check charge status (GET /v1/direct_charge/:ID). If it is accepted, you must activate the charge (PUT /v1/direct_charge/:ID/activate).
After a while, our payment gateway will try to charge the user and it will automatically change the charge status to success or failed.

Direct charge object

Here's the structure of a single direct charge object.

Parameters description:

price - an integer defined in cents. Example: to charge $99, set the price to 9900
commission_percent - a percentage fee deducted by LiveChat from the application price
per_account - the app is sold in the pay per account model; the app price is multiplied by the number of accounts within the organization (price x quantity)

Response

Copied!

{
  "id": "5deab95d-c0c9-4397-9593-436f533e83e5",
  "buyer_license_id": 100008664,
  "buyer_entity_id": "name@email.com",
  "order_client_id": "1e2cb91de0b15e99a7f4502b900e907e",
  "seller_client_id": "1e2cb91de0b15e99a7f4502b900e907e",
  "name": "Extension",
  "price": 100,
  "quantity": 2,
  "return_url": "https://application.com/path?id=5deab95d-c0c9-4397-9593-436f533e83e5&type=direct_charge",
  "test": false,
  "per_account":true,
  "status": "pending",
  "confirmation_url": "https://billing.livechatinc.com/?id=5deab95d-c0c9-4397-9593-436f533e83e5",
  "commission_percent": 20,
  "created_at": "2017-10-20T13:31:27Z",
  "updated_at": "2017-10-23T13:27:45Z"
}

Scopes

Direct Charges API requires billing_manage scope for all endpoints.

If you want to use this API, you must create an app in Developers Console and check "offer in-app payments" scope in the app settings. After successful authorization (by using Sign in with LiveChat), you will get an access token with billing_manage scope.

Endpoints

Base URL: https://billing.livechatinc.com

POST /v1/direct_charge - create a new charge. Required fields: name, price, quantity, return_url. Optional fields: per_account, test
GET /v1/direct_charge/:ID - get an existing charge.
GET /v1/direct_charge - create a paginated charges list (20 items per page) ordered by the creation date. Optional fields: page, status (for filtering by status. Returns: {"result:[OBJECT_1, ... , OBJECT_N]"}).
PUT /v1/direct_charge/:ID/activate - activate a charge (the payment gateway starts processing it).

Ledger

The Ledger API handles the financial activity and balance.

Entry object types

collection - the amount has beed added
refund - the amount has been deducted
withdrawal - the amount has been paid off

Ledger entry object

This is the structure of a single Ledger entry object:

Response

Copied!

{
  "id": "50af517e-c5aa-4af3-93c2-e60d612c43eb",
  "name": "app1",
  "type": "collection",
  "value": 160,
  "created_at": "2017-11-20T15:48:13Z"
}

Scopes

Ledger API requires ledger_read scope for all endpoints.

If you want to use this API, you must create an app in Developers Console and check "read developer’s financial activity and balance" scope in the app settings. After successful authorization (by using Sign in with LiveChat), you will get an access token with ledger_read scope.

Endpoints

Base URL: https://billing.livechatinc.com

GET /v1/ledger - returns the current ledger. It lists up to 20 entries, use ?page=X for pagination. Required format: {result: [LEDGER ENTRY 1, LEDGER ENTRY 2, ...]},
GET /v1/ledger/balance - returns the current ledger balance in cents. Format: {"balance": 10}

Recurrent charges

The Recurrent Charges API handles periodic payments. Once the payment is set up, a customer will be charged every month.

Statuses

There are six possible recurrent charge statuses:

Status	Description
`pending`	the charge has been created and is awaiting merchant interaction
`accepted`	the charge has been accepted by the merchant
`declined`	the charge has been declined by the merchant
`active`	the charge is being processed by a payment gateway
`frozen`	the charge could not be collected
`cancelled`	the charge has been cancelled

Flows

There are three possible recurrent charge flows:

pending -> accepted -> processed -> active -> cancelled
pending -> accepted -> processed -> active -> frozen
pending -> declined

Recurrent charge object

Here's the structure of a recurrent charge object.

Parameters description:

price - an integer defined in cents. Example: to charge \$99, set the price to 9900
seller_client_id - client id which created a given charge (in most cases it's the Marketplace id or order client id)
order_client_id - client id of the application that is paid for
order_entity_id - client id author (the creator of an application)
commission_percent - a percentage fee deducted by LiveChat from the application price
current_charge_at - the date when the current settlement period started
next_charge_at - the date when the current settlement period ends
per_account - the app is sold in the pay per account model; the app price is multiplied by the number of accounts within the organization
months - charge frequency expressed in months, default 1

Response

Copied!

  "id": "1c286f7a-aab8-4384-8e09-dc6749c550cd",
  "buyer_license_id": 100006625,
  "buyer_entity_id": "g.wyszynski+labs@livechatinc.com",
  "seller_client_id": "1e2cb91de0b15e99a7f4502b900e907e",
  "order_client_id": "e569d92213f62ec04cee2ee0f3b4f070",
  "order_license_id": "12345",
  "order_entity_id": "name@example.com",
  "name": "sub1",
  "price": 1900,
  "trial_days": 0,
  "months": 1,
  "return_url": "http://localhost?id=1c286f7a-aab8-4384-8e09-dc6749c550cd",
  "test": false,
  "per_account": true,
  "status": "pending",
  "confirmation_url": "http://localhost:8000?id=1c286f7a-aab8-4384-8e09-dc6749c550cd&type=recurrent_charge",
  "commission_percent": 20,
  "trial_ends_at": null,
  "cancelled_at": null,
  "current_charge_at": null,
  "next_charge_at": null,
  "updated_at": "2017-11-29T10:57:26Z",
  "created_at": "2017-11-29T10:57:26Z"

Scope

billing_manage - for creating charges for your own client
billing_admin - for creating charges for other clients and for adjusting commission_percent

Endpoints

All endpoints return a recurrent charge object.

POST /v1/recurrent_charge - create a new charge. Required fields: name, price, return_url. Optional fields: test, trial_days, months, per_account
GET /v1/recurrent_charge/:ID - get the existing charge
PUT /v1/recurrent_charge/:ID/accept - accept recurrent charge. The buyer must confirm the payment before the charge is collected
PUT /v1/recurrent_charge/:ID/decline - decline recurrent charge. The buyer can decline charge
PUT /v1/recurrent_charge/:ID/activate - activate recurrent charge
PUT /v1/recurrent_charge/:ID/cancel - cancel recurrent charge. Proportional refund is created when cancelled during the settlement period

LiveChat Billing API.css-n33kgz{margin-top:8px;}.css-n33kgz > label{margin:6px 10px 5px 0;}

LiveChat Billing API