Introduction

Welcome to the Prompt.Cash REST API docs.

For code examples how to integrate our gateway please visit our GitHub.

Authentication

# With shell, you can just pass the correct header with each request
curl "https://prompt.cash/api/v1/get-something" \
  -H "Authorization: Your-Secret-Account-Token"

All REST API calls are authorized by an additional HTTP header:

Authorization: Your-Secret-Account-Token

You must replace Your-Secret-Account-Token with your personal API key from your account settings..

Payments

Create a new payment

This API call is optional. The easiest way to create payments is to use our HTML form button (or Link) in your Account settings to send a new customer to our gateway. This will automatically create a new payment based on the unique id parameter you provide. Proceed only if you want to create payments programmatically from your backend

This API call is required if you have Enforce API Signatures enabled in your account (to prevent 3rd parties from creating payments into your account).

The below mentioned slp_token parameter is disabled as of May 15th 2023. It will later be replaced by a parameter called cashtoken working in the same manner.

curl "https://prompt.cash/api/v1/create-payment" \
  -H "Authorization: Your-Secret-Account-Token" \
  -d "token=Your-Public-Account-Tokenk&tx_id=Your-Unique-Order-ID&amount=0.01&currency=USD&desc+Your+Product&return=http://your-store.com/order-received-page.html" \
  -X POST

{
  "payment": {
    "id": 10,
    "tx_id": "Your-Unique-Order-ID",
    "amount_crypto": 0.000020576132,
    "amount_fiat": 0.01,
    "status": "PENDING",
    "paid_amount_crypto": 0,
    "fiat_currency": "USD",
    "crypto_currency": "BCH",
    "slp_token": "SPICE",
    "description": "",
    "callback_url": "",
    "return_url": "http://your-store.com/order-received-page.html",
    "referer": "",
    "email": "",
    "address": "bitcoincash:qptj65anjpvwcfdvvn5qgxjzauc9hkaxsv7fxadkzl",
    "confirmations": 0,
    "hash": "",
    "created_at": "2021-01-22T20:07:37.666707+07:00",
    "paid": "0001-01-01T00:00:00Z",
    "remaining_amount_crypto": 0.00002058,
    "payment_link": "bitcoincash:qptj65anjpvwcfdvvn5qgxjzauc9hkaxsv7fxadkzl?amount=0.00002058",
    "qr_url": "https://prompt.cash/pub/temp/qr/4cd1db6642a018c48ae41825e241b0d26813bbc7f80b68a41d2f3abefe5c40ec.png"
  },
  "existing": false
}

HTTP Request

POST https://prompt.cash/api/v1/create-payment

POST Parameters

Parameter	Required	Default	Description
token	yes	""	Your `Public Token` from your account settings.
tx_id	yes	""	A unique string as ID you must choose for each payment. A good candidate is a MySQL Primary Key for your order (or MongoDB `_id`).
amount	yes	0	The amount the customer has to pay.
currency	yes	""	The currency for the `amount` parameter in your request. Possible values: `BCH`, `USD`, `EUR`, `GBP`, `JPY`, `CNY`, ...
slp_token	no	""	SLP token identifier: `SPICE`, `USDT`, `USDH`, ...
desc	no	""	A description to identify this payment in your payment history.
callback	no	""	A URL to receive a HTTP POST callback when the payment status changes.
return	no	""	A URL to redirect the customer back to after a successful payment. This will usually be the "order confirmed" page of your store.
expiration	no	30	The time in minutes how long the customer has to pay (until the payment is expired).
confirm	no	0	The required confirmations (included blocks on chain) before the payment is considered `PAID`.
time	no	0	The current UNIX timestamp (in seconds). Required with `signature`.
signature	no	""	Required if `Enforce API Signatures` is enabled in your account. The SHA2 hash of all your parameters with `Secret-Token` as prefix: `SHA256(Secret + token=...&tx_id=...&time=123)` Ensure the parameters have the same order as listed here! `Secret` means `Your-Secret-Account-Token` and `+` means string concatenation of `UTF-8` strings.

Calling /create-payment with the same id parameter will always return the current status of the same payment. See the existing boolean in the response.

The URL specified in the callback parameter will receive a POST request as Content-Type: application/json containing the same JSON you received from /create-payment.

The amount in qr_url and payment_link always shows the remaining amount to be paid. This means when receiving the POST request to callback for a a payment with status PAID they will show amount 0.

You must check if the callback request includes Your-Secret-Account-Token under the JSON root key token to prevent spoofing.

Get a single payment

curl "https://prompt.cash/api/v1/get-payment" \
  -H "Authorization: Your-Secret-Account-Token"

{
  "data": {
    "id": 2,
    "tx_id": "Your-Unique-Order-ID",
    "amount_crypto": 5.0299997,
    "amount_fiat": 2416,
    "status": "PAID",
    "paid_amount_crypto": 1,
    "fiat_currency": "USD",
    "crypto_currency": "BCH",
    "slp_token": "",
    "description": "Your Product",
    "callback_url": "",
    "return_url": "http://your-store.com/order-received-page.html",
    "referer": "",
    "email": "",
    "address": "bitcoincash:qzh7zxv6t6vlh3djl5jeyllqymcnucs56cy06gmp04",
    "confirmations": 0,
    "hash": "",
    "created_at": "2021-01-20T11:07:21.589+07:00",
    "paid": "0001-01-01T00:00:00Z"
  }
}

This endpoint retrieves a specific payment.

HTTP Request

GET https://prompt.cash/api/v1/get-payment/<tx_id>

URL Parameters

Parameter	Description
tx_id	The `tx_id` of the payment to retrieve. You created this `tx_id` when sending the customer to our gateway. Usually this will be your internal order ID.

Query Parameters

Parameter	Required	Default	Description
force	no	false	Check the blockchain immediately for payments. Otherwise it might take 1-2 minutes for your new payments to show up via API.

Get a list of payments

curl "https://prompt.cash/api/v1/get-payments" \
  -H "Authorization: Your-Secret-Account-Token"

{
  "data": [
    {
      "id": 2,
      "tx_id": "foo2",
      "amount_crypto": 5.0299997,
      "amount_fiat": 2416,
      "status": "PAID",
      "paid_amount_crypto": 1,
      "fiat_currency": "USD",
      "crypto_currency": "BCH",
      "slp_token": "",
      "description": "Your Product",
      "callback_url": "",
      "return_url": "http://your-store.com/order-received-page.html",
      "referer": "",
      "email": "",
      "address": "bitcoincash:qzh7zxv6t6vlh3djl5jeyllqymcnucs56cy06gmp04",
      "confirmations": 0,
      "hash": "",
      "created_at": "2021-01-20T11:07:21.589+07:00",
      "paid": "0001-01-01T00:00:00Z"
    },
    {
      "id": 3,
      "tx_id": "next-payment",
      "amount_crypto": 5.0299997,
      "amount_fiat": 2416,
      "status": "PAID",
      "paid_amount_crypto": 1,
      "fiat_currency": "USD",
      "crypto_currency": "BCH",
      "slp_token": "",
      "description": "Your Product",
      "callback_url": "",
      "return_url": "http://your-store.com/order-received-page.html",
      "referer": "",
      "email": "",
      "address": "bitcoincash:qzh7zxv6t6vlh3djl5jeyllqymcnucs56cy06gmp04",
      "confirmations": 0,
      "hash": "",
      "created_at": "2021-01-20T11:07:22.549+07:00",
      "paid": "0001-01-01T00:00:00Z"
    }
  ]
}

This endpoint retrieves all payments matching your query in the order they have been created.

HTTP Request

GET https://prompt.cash/api/v1/get-payments

Query Parameters

Parameter	Default	Description
currency	""	Only return the payments in the specified currency. Otherweise return all. For example: `USD` or `EUR`
status	""	Only return payments with the specified status (empty value returns all). Values: `PENDING` `PAID` `CANCELLED` `EXPIRED` `REFUNDED`
from	0	Only return payments created after this UNIX timestamp in seconds (compared as `>=`).
to	0	Only return payments created before this UNIX timestamp in seconds (compared as `<`).
limit	100	Limit the max number of returned payments (max `500`).
offset	0	Skip the specified amount of payments from the beginning of results (to retrieve batches of `limit` payments per request).

URL Shortener

Create URL

This command adds a new shortened URL entry.

curl "https://prompt.cash/api/v1/surl/create" \
  -H "Authorization: Your-Secret-Account-Token" \
  -d "url=url-to-be-shortened&title=user-title&description=user-description&amount=paywall-price&currency=used-currency&mode=paywall-mode" \
  -X POST

{
  "status": "SUCCESS",
  "token": "abcdef"
}

HTTP Request

POST https://prompt.cash/api/v1/surl/create

POST Parameters

Parameter	Required	Default	Description
url	yes	""	Url that is to be added.
title	no	""	User provided title for the entry.
description	no	""	User provided description of the entry.
amount	yes	0.00	Paywall amount asked.
currency	yes	BCH	Used currency.
mode	yes	PASS	Redirection mode.

Possible returned status values in the returned JSON are: SUCCESS|FAILED The token contains the token (URL param) for tne new entry on success.

Update Url

This command updates an existing shortened URL entry.

curl "https://prompt.cash/api/v1/surl/update" \
  -H "Authorization: Your-Secret-Account-Token" \
  -d "token=existing-token-if&title=user-title&description=user-description&amount=paywall-price&currency=used-currency&mode=paywall-mode" \
  -X POST

{
  "status": "SUCCESS"
}

HTTP Request

POST https://prompt.cash/api/v1/surl/update

POST Parameters

Parameter	Required	Default	Description
token	yes	""	Existing token to be updated.
title	no	""	User provided title for the entry.
description	no	""	User provided description of the entry.
amount	yes	0.00	Paywall amount asked.
currency	yes	BCH	Used currency.
mode	yes	PASS	Redirection mode.

Possible returned status values in the returned JSON are: SUCCESS|FAILED

Get Url

This command gets an existing shortened URL entry.

curl "https://prompt.cash/api/v1/surl/get?token=existing-token-if" \
  -H "Authorization: Your-Secret-Account-Token" \

{
  "url": {
    "token": "abcdef",
    "url": "https://example.com",
    "title": "Example site",
    "description": "bla bla bla",
    "amount": 0.0,
    "currency": "BCH",
    "mode": "PASS"
  },
  "status": "SUCCESS"
}

HTTP Request

GET https://prompt.cash/api/v1/surl/get

POST Parameters

Parameter	Required	Default	Description
token	yes	""	Existing token to retrieve the short URL data for.

Possible returned status values in the returned JSON are: SUCCESS|FAILED

Delete Url

This command deletes an existing shortened URL entry.

curl "https://prompt.cash/api/v1/surl/delete?token=existing-token-if" \
  -H "Authorization: Your-Secret-Account-Token" \
  -X POST

{
  "status": "SUCCESS"
}

HTTP Request

POST https://prompt.cash/api/v1/surl/delete

POST Parameters

Parameter	Required	Default	Description
token	yes	""	Existing token to be updated.

Possible returned status values in the returned JSON are: SUCCESS|FAILED

List Urls

This command lists existing shortened URL entries for the authenticated user.

curl "https://prompt.cash/api/v1/surl/list?limit=entry-limit&offset=entry-offset" \
  -H "Authorization: Your-Secret-Account-Token" \

{
  "data": [{
    "token": "abcdef",
    "url": "https://example.com",
    "title": "Example site",
    "description": "bla bla bla",
    "amount": 0.0,
    "currency": "BCH",
    "mode": "PASS"
  },{
    "token": "ghijkl",
    "url": "https://an-otner-example.com",
    "title": "Example site",
    "description": "bla bla bla",
    "amount": 0.0,
    "currency": "BCH",
    "mode": "PASS"
  }],
  "status": "SUCCESS"
}

HTTP Request

GET https://prompt.cash/api/v1/surl/list

POST Parameters

Parameter	Required	Default	Description
limit	no	100	Limit the max number of returned entries (max `500`).
offset	no	0	Skip the specified amount of entries from the beginning of results (to retrieve batches of `limit` payments per request).

Possible returned status values in the returned JSON are: SUCCESS|FAILED

Errors

Our API uses the following error codes:

HTTP Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key (Secret token) is wrong.
404	Not Found -- The requested data could not be found.
500	Internal Server Error -- We had a problem with our server. Try again later.

To get a detailed explanation of the error please look at the "error" property in the response JSON.

See the example on the right.

{
  "error": "this is what went wrong..."
}