Developers

Creating Invoices

To create an invoice you must send an HTTP POST message to smartex.io/invoices with the details of the invoice passed in the request body.

The message must be JSON encoded and the content-type should be set to application/json. On success, the invoice details will be returned in a JSON encoded response.

In case of an error, you will receive a JSON encoded error response. All error responses carry an error field representing an object with two fields called type and message. Please note that our current rate limiters do not allow creation of more than 100 invoices per hour (there are per second and per minute limits in place as well). The fields in the request are described below.

Required POST Fields

price

The amount that shall be collected from the buyer.

currency

The currency code set for the price setting.

Optional Payment Notification (IPN) Fields

Smartex invoices have the ability to send JSON-encoded POST callbacks to a merchant-provided URL endpoint. Settings for this capability are described below.

posData

A variable provided by the merchant to correlate the invoice with a particular order or affiliate. Maximum length is 100 characters. You can encode this variable as a JSON-encoded string, e.g.:

posData: '{ "ref" : 822757, "affiliate" : "sky924" }'

notificationURL

A URL to send status update messages to your server (please note that only https URLs are supported). The URL where the status update messages will be sent by the Smartex servers.

Smartex will send an IPN callback to this URL when the invoice status changes.

notificationEmail

Smartex will send an email to this email address when the invoice status changes.

Optional Order Handling Fields

redirectURL

This is the URL for a return link that is displayed on the receipt, to return the shopper back to your website after a successful purchase. This could be a page specific to the order, or to their account.

Optional Display Information

orderID

Used to display your public order number to the buyer on the Smartex invoice. In the merchant Account Summary page, this value is used to identify the ledger entry. Maximum string length is 100 characters.

itemDesc

Used to display an item description to the buyer. Maximum string length is 100 characters.

itemCode

Used to display an item SKU code or part number to the buyer. Maximum string length is 100 characters.

physical

Defaults to false.

true

Indicates that a physical item will be shipped (or picked up).

false

Indicates that nothing is to be shipped for this order.

Buyer Fields

These fields are used for display purposes only and will be shown on the invoice if provided. Maximum string length of each field is 100 characters.

  • buyerName
  • buyerAddress1
  • buyerAddress2
  • buyerCity
  • buyerState
  • buyerZip
  • buyerCountry
  • buyerEmail
  • buyerPhone

Smartex Server Response

{
                                  "url": "https://smartex.io/invoice?id=8gJ69x5PvFiykRoWtBaLj4",
                                  "status": "new",
                                  "ethPrice": "0.019032",
                                  "ethDue": "0.000000",
                                  "price": 0.09,
                                  "currency": "USD",
                                  "exRates": {
                                    "ETH": 43.63742093999999, "USD": 456.00999999999993
                                  },
                                  "itemDesc": "Test",
                                  "invoiceTime": 1463165984267,
                                  "expirationTime": 1463166884267,
                                  "currentTime": 1463165984267,
                                  "guid": "29baee56-dd10-133f-aa43-8e4f3ae5bded",
                                  "id": "8gJ69x5PvFiykRoWtBaLj4,
                                  "ethPaid": "0.019032",
                                  "rate": 10.45,
                                  "exceptionStatus": false,
                                  "token": "Bbcf45uBVPNoiXbycHDh2cC37auMxhrxf6ijNCsTKGKfX4Y1vbjKNCdvoSdciMNw5G"
                                }
                                

The response to a create invoice request, the response to a get invoice request, and the content of a status update notification are all identical JSON representations of the invoice object. The fields are described below.

id

The unique id of the invoice.

url

An https URL where the invoice can be viewed.

posData

The passthrough variable provided by the merchant on the original invoice creation.

status

The current invoice base status. See Invoice States for more info. Possible states: new, paid, confirmed, complete, expired, invalid.

exceptionStatus

The current invoice extended status. See Invoice States for more info. Possible states: false, paidPartial, paidOver, paidLate.

ethPaid

The amount of ether paid to the invoice.

rate

The numeric exchange rate (based on invoice currency) associated with the invoice at the time of the original purchase.

price

The price set by the merchant (in terms of the provided currency).

currency

The 3 letter currency code in which the invoice was priced.

ethPrice

The amount of ether being requested for payment of this invoice (same as the price if the merchant set the price in ETH).

invoiceTime

The time the invoice was created in milliseconds since midnight January 1, 1970. Time format is .

expirationTime

The time at which the invoice expires and no further payment will be accepted (in milliseconds since midnight January 1, 1970). Currently, all invoices are valid for 15 minutes. Time format is .

currentTime

The current time on the smartex.io system (by subtracting the current time from the expiration time, the amount of time remaining for payment can be determined). Time format is .

Displaying Invoices

The simplest integration is to send your customer to the Smartex site to complete payment, and then back to your site to present order confirmation. In this case, redirect your customer to the url returned in the JSON response from the /invoices endpoint.

You can do this easily by using one of our plugins or directly with one of our supported libraries.

Our responsive invoice design ensures that the user gets optimal presentation on any kind of device and form factor.

Make sure to set the redirectURL this will ensure the user gets redirected to the appropriate confirmation page upon payment.

Embedded Invoice (iFrame)

Smartex allows you to embed the invoice on your page content, so the shopper never has to leave your site during the checkout process.

  1. When you create an invoice with a POST request to our API, Smartex returns the url field, which is the URL at which this invoice can be viewed.
  2. To display the embedded invoice on your page, append the code &view=iframe to the invoice URL and specify this value as the src in an iframe.
  3. The embedded invoice will automatically update when payments have been received. In addition to the server IPN sent to your notificationURL, the iframe will send a POST message to the parent window that the status has changed.

If your website has a dark background theme, append the code &theme=dark to the invoice URL. Note that the iframe background color is transparent.

<iframe id="smartex_invoice_iframe"
                                  scrolling="no"
                                  allowtransparency="true"
                                  frameborder="0"  src='https://smartex.io/invoice?id=8gJ69x5PvFiykRoWtBaLj4&view=iframe'
                                  style='width:500px; overflow: hidden; padding:20px; max-width:100%'>
                                </iframe>
                                

Post to Parent Window

Any invoice presented in an iframe has the ability to send status updates to the parent window. This option is useful for updating the parent window or redirecting it to another URL upon payment.

When the invoice iframe receives a status update from the Smartex server the new status is posted from the invoice iframe to the parent window via the Window.postMessage method and passing {status: string} where status can be any of the Invoice States according to the descriptions provided.

Your implementation should take into consideration the browser support for this method. See CanIUse for a list of browsers supporting Window.postMessage.

Following is an HTML code example illustrating a simple interaction between an invoice iframe and its parent document.

<html>
                                  <head>
                                    <title>Parent</title>
                                  </head>
                                  <body>
                                    <p>Invoice status: <span id="s1"></span>
                                    <iframe src="https://smartex.io/invoice?id="8gJ69x5PvFiykRoWtBaLj4" style="width: 800px; height: 800px;"></iframe>
                                    <script language="javascript">
                                  window.addEventListener("message", function(event) {
                                      document.getElementById("s1").innerHTML=event.data.status;
                                  }, false);
                                    </script>
                                  </body>
                                </html>
                                

Invoice Callbacks

An IPN (Instant Payment Notification) is an HTTP POST message sent from the Smartex server to the merchant’s eCommerce server.

{
                                "id": "123SmartexInvoiceID",
                                "url": "https://smartex.io/invoice?id=123SmartexInvoiceID",
                                "posData": "{\"paymentID\":\"123PAYMENTID\",\"orderID\":\"123ORDERID\"}",
                                "status": "paid",
                                "ethPrice": "0.010000",
                                "price": 0.09,
                                "currency": "USD",
                                "invoiceTime": 1463165984267,
                                "expirationTime": 1463166884267,
                                "currentTime": 1466003352038,
                                "ethPaid": "0.01",
                                "rate": 10.45,
                                "exceptionStatus": false,
                                "smartex":
                                  {
                                    "id": "123SmartexInvoiceID",
                                    "url": "https://smartex.io/invoice?id=123SmartexInvoiceID",
                                    "posData": "{\"paymentID\":\"123PAYMENTID\",\"orderID\":\"123ORDERID\"}",
                                    "status": "confirmed",
                                    "ethPrice": "0.010000",
                                    "price": 0.09,
                                    "currency": "USD",
                                    "invoiceTime": 1463165984267,
                                    "expirationTime": 1463166884267,
                                    "currentTime": 1466003352038,
                                    "ethPaid": "0.0512",
                                    "rate": 10.45,
                                    "exceptionStatus": false
                                  }
                              }

The IPN serves the purpose of updating the merchant server on a Smartex invoice status change.

The Smartex server will schedule several attempts to send the IPN update. If a 200 response code is received, the IPN communication is deemed successful. If none of the attempts receive such a response, the Smartex server will give up. Please note that IPN updates do not follow redirects.

The invoice status that is sent with the IPN is the status at the time of IPN delivery (not the status at the time IPN was first attempted).

Invoice States

On the Smartex API an invoice might be in one of several different states.

Any invoice has two subset of states: base states and exception states. Base states provide basic information needed to understand the status of an invoice. Exception states provide additional information regarding the status of the invoice if an error has occurred.

Exception states can be used to detect payment exceptions and to trigger further execution of automated rules. For example, it is possible to detect an underpaid invoice, apply decision logic, and either refund the payment or accept the underpayment.

Base States

new

An invoice starts in this state. If an invoice has received a partial payment, it will still reflect a status of new to the merchant

paid

As soon as payment is received, it is evaluated against the invoice requested amount. If the amount paid is equal to or greater than the amount expected, then the invoice is marked as being paid. To detect whether the invoice has been overpaid consult the invoice exception status (exStatus).

confirmed

Invoices are considered complete after 15 blocks on the Ethereum network.

complete

When an invoice is complete, it means that Smartex has credited the merchant’s account for the invoice. Currently, 15 confirmation blocks on the Ethereum network are required for an invoice to be complete.

expired

An expired invoice is one where payment was not received and the 15 minute payment window has elapsed.

Exception States

false

The invoice is not in an exception state.

paidPartial

If the amount paid is less than expected then the invoice is marked as being partially paid.

paidOver

If the amount paid is greater than expected then the invoice is marked as being overpaid.