Text Billing API

Introduction

The Text Billing API allows you to charge for your apps in Text marketplaces. Therefore, you can offer paid applications to over 37,000 Text 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

Product support

The Billing API supports apps created for two of our products: LiveChat and HelpDesk. Support for more products is coming.

Payment types

The Billing API supports the following payment types:

Direct charges – one-time payments
Recurring charges – subscription payments
In-app purchases – also known as In-app Upgrades in Developer Console
- Direct charges – one-time payments
- Recurring charges – subscription payments

Additional options

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

credit card processing
invoices

Getting started

Example app

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 Text OAuth authorization flow. All endpoints require access tokens, and some endpoints are limited by scope or client ID.

2. APIs

The current version of the Billing API is v2. This version makes it possible to handle various products, with the support of two of them already available: LiveChat and HelpDesk. The product information is put explicitly in API endpoints - as the <product> element of each path.

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

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 /v2/direct_charge/<product>) 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 /v2/direct_charge/<product>/:ID). If it is accepted, you must activate the charge (PUT /v2/direct_charge/<product>/: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 Text 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_organization_id": "e0a0ba10-e94c-4db8-ab2c-397815762934",
  "buyer_license_id": 100008664,
  "buyer_account_id": "638aa94b-eafa-42c7-9a9f-f0ee9561f934",
  "buyer_entity_id": "name@email.com",
  "seller_client_id": "1e2cb91de0b15e99a7f4502b900e907e",
  "order_client_id": "1e2cb91de0b15e99a7f4502b900e907e",
  "order_organization_id": "b0a0ba1e-a94c-4aa8-ab2c-397815762931",
  "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 (for LiveChat) or billing--all:rw (for HelpDesk) scope for all endpoints.

If you want to use this API, you must create an app in Developer Console and check "billing_manage" or "billing--all:rw" scope (depending on the product) in the app settings. After successful authorization (by using Sign in with LiveChat), you will get an access token with the correct scope.

Endpoints

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

POST /v2/direct_charge/<product> - create a new charge. Required fields: name, price, quantity, return_url. Optional fields: per_account, test
GET /v2/direct_charge/<product>/:ID - get an existing charge.
GET /v2/direct_charge/<product> - create a paginated charges list (20 items per page) ordered by the creation date. Optional fields: page, status, recurrent_charge_id
PUT /v2/direct_charge/<product>/:ID/activate - activate a charge (the payment gateway starts processing it).

Ledger

The Ledger API handles the financial activity and balance. Only supports LiveChat product for now.

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 Developer Console and check "ledger_read" 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 /v2/ledger/livechat - 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 /v2/ledger/livechat/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 client id or order client id)
order_client_id - client id of the application that is paid for
order_entity_id - email address of the application author (associated with order_client_id)
external_id - additional identifier used to tell apps sharing the same order_client_id (e.g. main app and its in-app upgrades) apart. We use a Marketplace application ID here
commission_percent - a percentage fee deducted by Text 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_organization_id": "e0a0ba10-e94c-4db8-ab2c-397815762934",
  "buyer_license_id": 100006625,
  "buyer_account_id": "638aa94b-eafa-42c7-9a9f-f0ee9561f934",
  "buyer_entity_id": "name@email.com",
  "seller_client_id": "1e2cb91de0b15e99a7f4502b900e907e",
  "order_client_id": "e569d92213f62ec04cee2ee0f3b4f070",
  "order_organization_id": "b0a0ba1e-a94c-4aa8-ab2c-397815762931",
  "external_id": "zzh2F1cnc",
  "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 app based on LiveChat
billing--all:rw - for creating charges for your own app based on HelpDesk
billing_admin - for creating charges for other clients

Endpoints

All endpoints return a recurrent charge object.

POST /v2/recurrent_charge/<product> - create a new charge. Required fields: name, price, return_url. Optional fields: external_id, test, trial_days, months, per_account
GET /v2/recurrent_charge/<product>/:ID - get the existing charge
PUT /v2/recurrent_charge/<product>/:ID/accept - accept recurrent charge. The buyer must confirm the payment before the charge is collected
PUT /v2/recurrent_charge/<product>/:ID/decline - decline recurrent charge. The buyer can decline a pending charge
PUT /v2/recurrent_charge/<product>/:ID/activate - activate recurrent charge
PUT /v2/recurrent_charge/<product>/:ID/cancel - cancel recurrent charge.

Text Billing API.css-1g0dr3m{margin-top:8px;}.css-1g0dr3m > label{margin:0 0 5px 0;}.css-1g0dr3m label + div{-webkit-box-pack:end;-webkit-justify-content:flex-end;-ms-flex-pack:end;justify-content:flex-end;}

Overview

Product support

Payment types

Additional options

Getting started

Example app

Agent App Widget

User guide

1. Authorization

2. APIs

2.1. Direct Charges

Use cases

2.2. Ledger

Use cases

2.3. Recurrent Charges

Use cases

Direct charges

Statuses

Flows

Usage

Direct charge object

Scopes

Endpoints

Ledger

Entry object types

Ledger entry object

Scopes

Endpoints

Recurrent charges

Statuses

Flows

Recurrent charge object

Scope

Endpoints

Text Billing API