NAV
shell

Introduction

Welcome to the Prompt.Cash REST API docs.

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

Authentication

To authorize, use this code:

# 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"

Make sure to replace Your-Secret-Account-Token

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

Authorization: Your-Secret-Account-Token

Payments

Create a new payment

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

The above command returns JSON structured like this:

{
  "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 0 A URL to receive a HTTP POST callback when the payment status changes.
return no 0 A URL to redirect the customer back to after a successful payment. This will usually be the "order confirmed" page of your store.
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.

Possible payment status values in the returned JSON are: PENDING|PAID|CANCELLED|EXPIRED|HOLD|REFUNDED

Get a single payment

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

The above command returns JSON structured like this:

{
  "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"

The above command returns JSON structured like this:

{
  "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

The above command returns JSON structured like this:

{
  "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

The above command returns JSON structured like this:

{
  "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" \

The above command returns JSON structured like this:

{
  "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

The above command returns JSON structured like this:

{
  "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" \

The above command returns JSON structured like this:

{
  "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..."
}