NAV
php shell

Token Markets API

Token Markets is a powerful e-commerce platform that allows the sale of goods & services, downloadable content/media, as well as blockchain token sales + rentals.

Payments can be accepted in Credit Cards (via Stripe) as well as Cryptocurrencies such as Bitcoin and other tokens.

See the documentation below to learn how to use both the public and private merchant API methods.

To start, head to https://tokenmarkets.com, sign up and obtain a pair of API keys from the Markets Settings page.

Pay with Token Markets™

<!-- simple install -->
<script src="https://pay.tokenmarkets.com/pay.min.js"
        class="js-pay-with-token-markets"
        data-key="<MARKETS_API_KEY>" 
        data-company="<YOUR_COMPANY>"
        data-product="<YOUR_PRODUCT>"
        data-type="token"
        data-currency="tokenly"
        data-amount="10">
</script>

<!-- advanced install -->
<button id="pay-now-button">Pay Now</button>

<script type="text/javascript" src="https://pay.tokenmarkets.com/pay.min.js"></script>
<script type="text/javascript">
  var handler = PayWithTokenMarkets.configure({
    key: "<MARKETS_API_KEY>",
    company: "<YOUR_COMPANY>",
    product: "<YOUR_PRODUCT>",
    type: "token",
    currency: "SOUP",
    amount: "1",
    email: "john@example.com",
    meta: {
      invoiceId: "1000051"
    }
    completeMessage: 'Thank you for buying our product!'
  });

  document.getElementById('pay-now-button').addEventListener('click', function(e) {
    handler.open();
    e.preventDefault();
  });

  // Close Modal on page navigation:
  window.addEventListener('popstate', function() {
    handler.close();
  });
</script>

Pay with Token Markets™ or “Instant Invoices” is a feature that allows for generic bitcoin/token/credit payment collection on any website or app. This is similar to instant checkout functionality on Stripe or Paypal.

Note: A default bitcoin forwarding address must be set up in order to accept bitcoin or token payments.
Stripe Connect required for credit cards. See your Markets Settings for account configuration.

For pricing, refer to “standard item” invoice pricing on your Markets dashboard.

For front end implementation, refer to our javascript SDK and PHP API documentation below.

New Invoice

Creates a new Pay with Token Markets™ invoice.

HTTP Method
POST https://tokenmarkets.com/api/v1/pay-with/new

Authentication: valid api_key query parameter

Request Parameters

Parameter Type Description
customerEmail string Customer email for sending receipt - required
paymentType string What method to pay, valid options: bitcoin, token, credit - required
currency string Currency code/asset name to pay with - required
amount float Required amount to pay - required
peg string Peg the amount to another currency, e.g USD
product string Product label/short description for this invoice - required
company string Company or merchant label/name for this invoice, defaults to your merchant catalog settings.
logoURL string Custom logo to attach to this invoice. Must be https:// and domain must match API origin host. Defaults to merchant catalog logo.
completeMessage string Custom message for when invoice completes.
returnURL string Custom return URL for when invoice completes.
meta array Optional JSON metadata
stripeToken string Include with credit paymentType to attempt payment in the same request.

Returns: (Instant Invoice Object)

{
   "meta": {
        "btcQuote": 121904,
        "btcQuoteFloat": 1219.04,
        "quoteType": "USD"
    },
}

When using the peg option, the amount field in the resulting response is replaced with a calculated real total. For example, {paymentType: bitcoin, currency: BTC, peg: USD, amount: 10} will recalculate the amount to $10 worth of BTC. The original requested value is stored in the pegValue field and the exchange rate in pegRate.

When using the bitcoin payment type and not using the peg option, a USD:BTC quote is included in the response meta object.
Otherwise use the peg/pegValue/pegRate fields to figure out value.

Get Invoice

Get details for an un-expired Pay with Token Markets™ invoice, referenced by uuid.

HTTP Method
GET https://tokenmarkets.com/api/v1/pay-with/{uuid}

Authentication: valid api_key query parameter

Returns: (Instant Invoice Object)

Cancel Invoice

Cancel an unpaid pending Pay with Token Markets™ invoice, referenced by uuid.

An invoice can only be cancelled if it is in pending state with no payment yet received.

HTTP Method
DELETE https://tokenmarkets.com/api/v1/pay-with/{uuid}

Authentication: valid api_key query parameter

Returns: result (boolean)

Pay Invoice with Credit Card

Pay a credit type Pay with Token Markets™ invoice using Stripe. For retrieving the correct payment input, see the Stripe Elements documentation.

HTTP Method
POST https://tokenmarkets.com/api/v1/pay-with/{uuid}/pay

Authentication: valid api_key query parameter

Request Parameters

Parameter Type Description
stripeToken string Obtained via stripe.js - required

Returns: (Instant Invoice Object)

Websocket Notifications

For recieving websocket notifications, use our PusherClient library. More details here: https://github.com/tokenly/pusher-client

Client-side Usage

See the pusher-client.js example for the client javascript code.

Step 1: Include the two libraries

This is best placed near the end of your body tag.

<script src="https://pusher.tokenly.com/public/client.js"></script>
<script src="path/to/js/pusher-client.js"></script>

Step 2: Subscribe and respond to events

After the two script tags below are loaded, you can subscribe to a channel

<script>
    var subscribedClient = PusherClient.subscribeToPusherChanel('pay-with/{uuid}', function(dataReceived) {
        // received a websocket message on channel /pay-with/{uuid}
        console.log('user '+dataReceived.fromUser+' said '+messageText);
    });
</script>

Webhook Notifications

If you have a webhook URL set in your Markets Settings, you can receive instant invoice notifications whenever a bitcoin/token payment is detected or when an invoice is paid and complete.

Notifications are signed with your designated API public/private key pair.

Webhook Notification Data: invoice (Instant Invoice Object)

Instant Invoice Object

{
    "uuid": "a78604cc-ca89-4793-b1aa-4ca3d2901084",
    "status": "pending",
    "paymentType": "bitcoin",
    "currency": "BTC",
    "amount": 2089999,
    "received": 0,
    "peg": "USD",
    "pegRate": 122105,
    "pegValue": 2552,
    "customerEmail": "team@tokenly.com",
    "paymentAddress": "12evCwtsAuovEh6p6QpcSEyH1GC5co5Veh",
    "companyLabel": "Token.FM",
    "productLabel": "6 months service",
    "completeMessage": null,
    "returnUrl": null,
    "expires": 1492558124,
    "originHost": "token.fm",
    "createdAt": "2017-04-18T15:28:44-07:00",
    "updatedAt": "2017-04-18T15:28:49-07:00",
    "meta": [],
    "companyLogo": "https://tokenmarkets.com/files/catalog/d1df0df976b9c340725c.png",
    "pegRateFloat": 1221.05,
    "pegValueFloat": 25.52,
    "amountFloat": 0.02089999,
    "receivedFloat": 0
}

JSON data returned from Pay with Token Markets™ API methods.

Response variables

Variable Type Description
uuid string Unique reference ID for this invoice
status string Current status: pending, receiving, complete, expired
paymentType string Payment method: bitcoin, token or credit
currency string Currency code or asset ID to pay with
amount integer Final total in satoshis (or cents) to pay
amountFloat float Human readable invoice total
received integer Received amount in satoshis (or cents)
receivedFloat float Readable version of received amount
peg string Currency that the amount was pegged to, e.g USD
pegRate integer Exchange rate used to calculated pegged amount, in cents
pegRateFloat float Readable version of exchange rate used
pegValue integer Original requested value for pegged amounts
pegValueFloat float Readable peg value
customerEmail string Customer email address to send receipt
paymentAddress string Bitcoin deposit payment address
companyLabel string Custom company label, defaults to merchant catalog title
productLabel string Short invoice description
completeMessage string Custom text to include on completion
returnUrl string Custom URL to redirect customer on complete
expires integer Unix timestamp of when this invoice expires if pending and unreceived (defaults 2 hours)
originHost string Host domain name that made the API request
createdAt datetime Timestamp of when invoice was created
updatedAt datetime Timestamp of when invoice was last updated
meta array Additional custom metadata that can be included for reference