The Chariz Pay API allows sellers to integrate their product with Chariz Pay, enabling easy payments from within the product, and the ability to confirm the validity of a purchase.

This is a draft of the API spec. The API is not yet publicly available. It may have breaking changes before being finalised. Please contact us if you have questions about using the API.

General details

The API follows REST convention. HTTP/1.1 and 2.0 are supported. Responses are available only in JSON format.

The API is versioned. The current version is 1.0. Features may be added at any time within the current version. If we ever make a breaking change, this version number will increment and the previous version of the API will remain available for a certain period of time.

The endpoint is:

https://api.chariz.io/1.0/

This endpoint is only available over an encrypted connection (https://). It will not redirect if accessed over cleartext (http://).

Authentication

For requests that are specific to users (e.g. getting the state of a purchase), you must provide authentication.

If the user is already logged in via a cookie, for instance in their web browser, the requests are automatically authenticated.

For use with iOS jailbreak packages, the unique device identifier (UDID) is accepted as authentication on some endpoints. This should be provided in the X-Unique-Id header, along with the device model (e.g. iPhone8,2) in the X-Machine header.

Rate limiting

To ensure the reliability of the API, rate limits are imposed.

  • Unauthenticated requests are currently limited to 100 per hour.
  • Authenticated requests are limited to 200 per hour.

If you reach the rate limit, the API will be disabled for your IP address and account (if applicable) until the next the hour (in the UTC 00:00 timezone). If these limits are too low, please contact us to request an exception. We regularly monitor API usage and may increase your limits if we believe it is fair to, however it is still preferred to get this set up before you start hitting the limits.

Bruteforcing methods marked as sensitive will be detected and may result in a permanent ban for accounts and IP addresses involved.

Private methods

Private API methods may exist within the Chariz platform. They are not to be used without contacting us and receiving prior permission. We reserve the right to block, rate limit, or return estimated or invalid data to unauthorised users of private API. This includes APIs exposed for the specific use of clients such as Sileo.

Objects

Common to all responses

  • error: enum. See Error.

Product

  • state: enum. See Product state.
  • id: string. Product SKU.
  • name: string. Product name displayed to users.
  • author: string. Author name displayed to users.
  • description: object. See Product description.
  • website: string. URL to seller’s website describing the product.
  • current_price: string. The selling price of the product, taking into account current discounts. This is the price the customer will pay.
  • normal_price: string. The selling price of the product, without discount. Also referred to as the full price.
  • purchase_url: string. URL that can be opened in the user’s web browser to begin a purchase. This URL is subject to change — use this value, do not hardcode the URL.

Product description

  • text: string. The product description with HTML stripped out. Best for displaying in UI where rich text is not possible. You should use HTML instead where possible.
  • html: string. The product description in HTML. This is preferred for displaying in UI where brevity is not a concern. Can include images. Display this in a web view (e.g. WKWebView) or rich text view (e.g. UITextView with NSAttributedString(html:documentAttributes:)).
  • tagline: string. The product’s tagline description. This is usually one short sentence describing the product. Best for displaying in UI where space is extremely limited.

Purchase

  • state: enum. See Purchase state.
  • purchase_date: date. The exact date and time of purchase.

Enumerations

Error

  • null: null. Success.
  • 404: number. Not found.
  • 500: number. Server error. Try again later.
  • 429: number. Client or user has been rate limited.

Product state

  • null: null. Product not found.
  • "active": string. Product is currently being sold.
  • "inactive": string. Product sales temporarily suspended.
  • "removed": string. Product sales permanently suspended.

Purchase state

  • null: null. Not purchased.
  • "completed": string. Purchased successfully. Allow the customer to use the product.
  • "refunded": string. Purchased, and later refunded. Use this to know when to retract the product from the customer (if desired).
  • "pending": string. The customer has authorized the purchase, but it is awaiting processing by the user’s bank. Do not provide the product to the customer yet.

GET /product/get/:product_sku

Get the metadata for a product.

Query parameters

product_sku The identifier (SKU) of the product. This can be found in the user-facing URLs for the product.

Response format

JSON object containing:

Example request

GET https://api.chariz.io/1.0/product/get/typestatus-plus.json

Example response

Success:

HTTP/1.1 200 OK
{
	"error": null,

	"product": {
		"state": "active",

		"id": "typestatus-plus",
		"name": "TypeStatus Plus",
		"author": "HASHBANG Productions",
		"description": {
			"plain": "The extension to the legendary tweak TypeStatus. TypeStatus Plus adds …",  // (snipped for brevity)
			"html": "<h1>The extension to the legendary tweak TypeStatus.</h1><p>TypeStatus Plus adds …",
			"tagline": "The extension to the legendary tweak TypeStatus."
		},
		"website": "https://typestatus.com/plus",

		"current_price": "2.99",
		"normal_price": "2.99",

		"purchase_url": "https://chariz.io/buy/typestatus-plus"
	}
}

Not found:

HTTP/1.1 404 Not Found
{
	"error": 404,
	"state": null
}

POST purchase/get/:purchase_id

Authentication required; Sensitive

Get the state of a purchase. This request uses POST as it is sensitive to being bruteforced.

Query parameters

purchase_id The 24-character hash representing a purchase. This may be returned by other API endpoints or provided by the user.

Response format

When requested as JSON:

When requested as TXT:

  • 200: Purchase is valid.
  • 202: Purchase is pending.
  • 404: Purchase does not exist.
  • 410: Purchase was refunded.

Example request

As JSON

POST https://api.chariz.io/1.0/purchase/get/57f0b92831b86a3ad0bc364e.json
X-Unique-Id: da39a3ee5e6b4b0d3255bfef95601890afd80709
X-Machine: iPhone8,2
Example response

Success:

HTTP/1.1 200 OK
{
	"error": null,
	"purchase": {
		"state": "completed",
		"purchase_date": "2016-10-02T07:37:10.021Z"
	}
}

Not found:

HTTP/1.1 404 Not Found
{
	"error": 404,
	"state": null
}

As TXT

POST https://api.chariz.io/1.0/purchase/get/57f0b92831b86a3ad0bc364e.txt
X-Unique-Id: da39a3ee5e6b4b0d3255bfef95601890afd80709
X-Machine: iPhone8,2
Example response

Success:

HTTP/1.1 200 OK
200

Not found:

HTTP/1.1 404 Not Found
404

POST purchase/check/:package_id

Authentication required; Sensitive

Get the state of a purchase. This request uses POST as it is sensitive to being bruteforced.

Query parameters

package_id The identifier (SKU) of the product. This can be found in the user-facing URLs for the product.

Response format

When requested as JSON:

When requested as TXT:

  • 200: Purchase is valid.
  • 202: Purchase is pending.
  • 404: Purchase does not exist.
  • 410: Purchase was refunded.

Example request

As JSON

POST https://api.chariz.io/1.0/purchase/check/typestatus-plus.json
X-Unique-Id: da39a3ee5e6b4b0d3255bfef95601890afd80709
X-Machine: iPhone8,2
Example response

Identical to POST purchase/get/:purchase_id.json.

As TXT

POST https://api.chariz.io/1.0/purchase/check/typestatus-plus.txt
X-Unique-Id: da39a3ee5e6b4b0d3255bfef95601890afd80709
X-Machine: iPhone8,2
Example response

Identical to POST purchase/get/:purchase_id.txt.