Invoices

Sending an invoice

To send an invoice, you need to make a POST request to the /invoice endpoint with your store API key and the desired parameters. Invoices are identified by a unique, random ID.

The API will return a success message if everyone goes as expected.

Users have until the invoice timeout to pay the required amount. Our system will automatically detect when the payment is done and will send an email receipt to the payer after the timeout is reached, whether the payment failed or succeeded.

If the payment succeeds, you will receive the funds after the timeout. For example, if you specified a timeout of 3 days, you will receive the funds after 72 hours.

Warning

If the payer doesn’t send the full amount specified by the invoice, the payment will fail and the payer will be refunded.

Creating an invoice

You can create an invoice by sending a POST request to the /invoice 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 charge in USD.
    • Must be greater than 0.25 USD.
  • timeout (required | string)

    • The URL the payer will be redirected to after paying.
    • Possible values: “3 hours” - “12 hours” - “day” - “3 days” - “week”.
    • You can also use the “test” value to timeout after 3 minutes (for testing).
  • email (required | string)

    • The payer email address for receiving the invoice and a receipt.
  • name (required | string)

    • A name for the invoice operation.
  • description (optional | string)

    • A description for the invoice operation.

Get an invoice status

You can get an invoice status by sending a GET request to the /invoice/:uid endpoint with the following arguments:

URL args:

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

The :uid parameter represents the invoice unique ID. You will get an invoice UID as a response when creating an invoice.

When sending the request, the API should return the current invoice status as well as some useful informations about the invoice such as creation date, required amount and customer email.

Note

You can also get invoices and their status using the dashboard.

Getting all invoices

You can get all the invoices you sent with a specific store by sending a GET request to the /invoices endpoint with the following arguments:

URL args:

  • api_key (required | string)

    • Your store API key.
  • start (optional | integer)

    • Counting starter.
    • Default value: 1.
  • limit (optional | integer)

    • Pagination limiter.
    • Default value: 20.

This is usefull if you want to analyze or verify invoices by yourself.

Examples

cURL

Create an invoice:

curl -X POST \
  https://api.simplecash.co/v1/invoice?api_key=cc8d300559e7421d9d646c0bfb2f798a \
  -H "Content-Type: application/json"
  -d '{
	"amount": 299,
	"timeout": "3 days",
	"name": "Example invoice",
	"email": "johndoe@gmail.com"
    }'

Get an invoice status:

curl -X GET \
  https://api.simplecash.co/v1/invoice/e24822771b1d41eb869b8d38d0a7a6ac?api_key=cc8d300559e7421d9d646c0bfb2f798a \

Get all invoices:

curl -X GET \
  https://api.simplecash.co/v1/invoices?api_key=cc8d300559e7421d9d646c0bfb2f798a \

Python (Requests)

Create an invoice:

import requests

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

data = {
    "amount": 299,
	"timeout": "3 days",
	"name": "Example invoice",
	"email": "johndoe@gmail.com"
}

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

print(response.json())

Get an invoice status:

import requests

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

response = requests.get(url)

print(response.json())

Get all invoices:

import requests

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

response = requests.get(url)

print(response.json())

Note

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