Platform
APIs & SDKs
Resources

...

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

Text Billing API demo

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:

StatusDescription
pendingthe charge has been created and is awaiting user interaction
acceptedthe charge has been accepted by the user
declinedthe charge has been declined by the user
processedthe charge is being processed by a payment gateway
failedthe charge could not be collected
successthe 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:

StatusDescription
pendingthe charge has been created and is awaiting merchant interaction
acceptedthe charge has been accepted by the merchant
declinedthe charge has been declined by the merchant
activethe charge is being processed by a payment gateway
frozenthe charge could not be collected
cancelledthe 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.

...

Join the community
Get in direct contact with us through Discord.
Follow us
Follow our insightful tweets and interact with our content.
Contribute
See something that's wrong or unclear? Submit a pull request.
Contact us
Want to share feedback? Reach us at: developers@text.com