Subscriptions

Creating a subscriber

To create a subscriber, you need to make a POST request to the /sub endpoint with your store API key and the desired parameters. Subscription are identified by a unique, random ID.

The API will return a unique URL for each call. You can redirect the user to that URL in order for him to proceed to the payment. The generated URL should remain personal to the subscriber as anyone in possession of it can cancel the subscription. The subscriber can use the URL to manage his subscription by adding funds, checking the remaning time and balance, or canceling it.

The generated URL looks like this:

https://pay.simplecash.co/sub/4447916040904206b3c26efb695559f4

Our system will automatically detect when the initial payment is done and will inform the user that the subscription has started by sending him an email. The subscriber will then get debited on a regular basis and will be responsible for refilling his wallet before the subscription ends.

If a debit succeeds, you will instantly receive the funds since Bitcoin Cash has 0-conf. This happens on a regular interval.

You can also check if a user subscription is active and stop a subscription by closing it.

Creating a subscription

You can create a subscription by sending a POST request to the /sub endpoint with the following arguments:

URL args:

  • api_key (required | string) – Your store API key.

JSON parameters:

  • amount (required | float)

    • The full amount you want to debit on each interval in USD.
    • Must be greater than 0.25 USD.
  • interval (required | string)

    • The time interval for debiting the subscriber.
    • Possible values: “day” - “week” - “month” - “year”
    • You can also use the “test” value to debit every 3 minutes (for testing).
  • name (required | string)

    • A name for the charge operation.
  • customer_email (required | string)

    • The subscriber email address for receiving a receipt on each debit.
  • description (optional | string)

    • A description for the subscription operation.

Check subscription status

You can verify if a subscription is active, canceled or pending by sending a GET request to the /sub/check endpoint with the following arguments:

URL args:

  • api_key (required | string) – Your store API key.

JSON parameters:

  • email (required | string)
    • The subscriber email address.

The request will return the following informations:

  • status: active, canceled or pending.
  • interval: day, week, month, year, test.
  • uid: Unique ID representing the subscription
  • funds_crypto: Remaining funds in BCH.
  • funds_fiat: Remaining funds in USD.
  • coverage: The remaining time for the subscription to expire.
  • data:
    • number_of_refills: Number of refills.
    • last_refill_date: Last refill date.
    • last_refill_amount: Last refill amount in BCH.

Delete a subscription

You can delete a subscription by sending a DELETE request to the /sub/:uid endpoint with the following arguments:

URL args:

  • api_key (required | string) – Your store API key.

URL parameters:

  • :uid (required | string) – The subscription unique ID.

Note

If you’re deleting an active subscription or a subscription with a positive balance, the remaining funds will be refunded to the subscriber on the address used to activate the subscription (usually the first used address).

Examples

cURL

Creating a subscription:

curl -X POST \
  https://api.simplecash.co/v1/sub?api_key=cc8d300559e7421d9d646c0bfb2f798a \
  -H "Content-Type: application/json"
  -d '{
	"amount": 1,
	"interval": "day",
	"name": "Ross Ulbright daily donation",
	"customer_email": "johndoe@gmail.com"
    }'

Check for a subscription status:

curl -X GET \
  https://api.simplecash.co/v1/sub/check?api_key=cc8d300559e7421d9d646c0bfb2f798a \
  -H "Content-Type: application/json"
  -d '{
	"email": "johndoe@gmail.com"
    }'

Delete a subscription:

curl -X DELETE \
  https://api.simplecash.co/v1/sub/328016c842e0442b9ad4b233e1475265?api_key=cc8d300559e7421d9d646c0bfb2f798a

Python (Requests)

Creating a subscription:

import requests

url = "https://api.simplecash.co/v1/sub?api_key=cc8d300559e7421d9d646c0bfb2f798a"

data = {
    "amount": 15.99,
    "interval": "month",
    "name": "Example service monthly subscription",
    "description": "This is just a test",
	"customer_email": "johndoe@gmail.com"
}

response = requests.post(url, json=data)

print(response.json())

Check for a subscription status:

import requests

url = "https://api.simplecash.co/v1/sub/check?api_key=cc8d300559e7421d9d646c0bfb2f798a"

data = {
	"email": "johndoe@gmail.com"
}

response = requests.get(url, json=data)

print(response.json())

Delete a subscription:

import requests

url = "https://api.simplecash.co/v1/sub/328016c842e0442b9ad4b233e1475265?api_key=cc8d300559e7421d9d646c0bfb2f798a"

response = requests.delete(url)

print(response.json())

Note

We will soon release language-specific libraries to easily interact with the API.