API Reference

Bills

Resource

Bills are payment requests addressed to specific buyers. Bill line items have fixed prices, typically denominated in fiat currency.

Schema
Name Type Read-Only
id
Resource id
string
token
API token for bill resource
string
createdDate
Time of bill creation
date
delivered
Indicates whether bill has been delivered to buyer
boolean
number
Bill identifier, specified by merchant
string
status
Can be `draft`, `sent`, `paid`, or `complete`
string
currency
ISO 4217 3-character currency code
string
showRate
Indicates whether corresponding invoice web page should display equivalent fiat amount
boolean
archived
Indicates whether bill is visible in Smartex website
boolean
name
Buyer Name
string
address1
Buyer Street Address
string
address2
Buyer Apartment or Suite Number
string
city
Buyer Locality or City
string
state
Buyer State or province
string
zip
Buyer Zip or Postal Code
string
country
Buyer Country Code (ISO 3166-1 alpha-2)
string
email
Buyer Email
string
phone
Buyer Phone
string
dueDate
UTC date, ISO-8601 format yyyy-mm-dd or yyyy-mm-ddThh:mm:ssZ. Default is current time.
date
items
List of line items
array
description
Line item description
string
price
Line item unit price, in `currency`
number
quantity
Line item number of units
number

POST /bills

Creates a bill for the calling merchant.

Required Parameters description price quantity
Facades merchant

GET /bills

Retrieves all of the caller's bills.

Parameters status
Facades merchant

GET /bills/:billId

Retrieves the specified bill.

Parameters none
Facades merchant

PUT /bills/:billId

Updates the specified bill.

Required Parameters description price quantity
Facades merchant

POST /bills/:billId/deliveries

Delivers the bill to the recipient's email.

Parameters none
Facades merchant

Clients

Resource

Clients are devices or developer applications used to access the Smartex API. A client is identified by its access key id. A client is associated with a token via a pairing process.

Schema
Name Type Read-Only
id
Resource id
string
label
Description of client
string
approved
Indicates whether client is approved
boolean
disabled
Indicates whether client is enabled
boolean
token
API token for clients resource
string

POST /clients

Associates a client identity with a user.

Required Parameters none
Facades public

GET /clients

Retrieves the registered client access keys for the caller.

Parameters none
Facades client

PUT /clients/:keyId

Modifies the given client access key (approving or disabling).

Required Parameters none
Facades client public

Currencies

Resource

Currencies are fiat currencies supported by Smartex

Schema
Name Type Read-Only
code
ISO 4217 3-character currency code
string
symbol
Display symbol
string
precision
Number of decimal places
number
exchangePctFee
Basis points
number
payoutEnabled
Indicates whether Smartex can exchange currency for eth
boolean
name
English currency name
string
plural
English plural form
string
alts
Alternative currency name(s)
string
minimum
Minimum supported value
string
payoutFields
Can be `merchantEIN`
array

GET /currencies

Retrieves the list of supported currencies.

Parameters none
Facades public

Invoices

Resource

Invoices are time-sensitive payment requests addressed to specific buyers. An invoice has a fixed price, typically denominated in fiat currency. It also has an eth equivalent price, calculated by Smartex, with an expiration time of about 15 minutes.

Schema
Name Type Read-Only
id
Resource id
string
token
API token for invoice resource
string
price
Fixed price amount, denominated in `currency`
number
currency
Fixed price currency, not the expiring eth price
string
orderId
Order id
string
orderID
Order id (deprecated)
string
itemDesc
Invoice description, from first line item of bill
string
itemCode
`etherdonation` for donations, otherwise null
string
notificationEmail
Contact for notification of invoice status change. If missing, then account notification email address is notified.
string
notificationURL
Webhook URL for instant payment notification (IPN)
string
redirectURL
URL to redirect your shopper back to your website after a successful purchase
string
posData
Order reference number from the point-of-sale (POS). It should be a unique identifier for each order that you submit. Field is a passthru-variable returned in the payment notification post, without any modifications, for you to match up the Smartex payment notification with the request that was sent to Smartex.
string
fullNotifications
Indicates whether email and IPN notifications should be sent for this invoice. If missing, then account notification settings are used.
boolean
physical
Indicates whether items are physical goods. Alternatives include digital goods and services.
boolean
buyer
Customer who pays the invoice
object
name
Buyer Name
string
address1
Buyer Street Address
string
address2
Buyer Apartment or Suite Number
string
locality
Buyer Locality or City
string
region
Buyer State or province
string
postalCode
Buyer Zip or Postal Code
string
country
Buyer Country code
string
email
Buyer Email
string
phone
Buyer Phone
string
notify
Indicates whether receipt email should be sent to buyer for this invoice
boolean
url
Web address of invoice, expires at `expirationTime`
string
status
Can be `new` (invoice has not yet been fully paid), `paid` (received payment but has not yet been fully confirmed), `confirmed`, `complete` (confirmed by Smartex and credited to the ledger), `expired` (can no longer receive payments), and `invalid` (invoice has received payments but was invalid)
string
ethPrice
eth equivalent of `price`, expires at `expirationTime`
number
ethDue
eth amount due
number
ethPaid
eth amount paid
number
invoiceTime
UNIX time of invoice creation, in milliseconds
number
expirationTime
UNIX time when invoice is last available to be paid, in milliseconds
number
currentTime
Time of API call
date
exceptionStatus
Can be `paidPartial`, `paidOver`, or false
boolean
rate
eth exchange rate used for invoice, denominated in `currency`
number
exRates
All exchange rates used for invoice
array
`currency code`
Exchange rate for given currency code
number
transactions
All transactions used to pay invoice
array
amount
Amount paid, in satoshis
number
confirmations
Number of confirmations in blockchain
number
time
Time of transaction on Ethereum network
date
receivedTime
Time when Smartex received transaction from network
date
flags
Miscellaneous invoice attributes
object
refundable
Indicates whether buyer Ethereum address is available for this invoice
boolean

POST /invoices

Creates an invoice for the calling merchant.

Required Parameters price currency
Facades merchant pos

GET /invoices/:invoiceId

Retrieves the specified invoice for the calling merchant.

Parameters none
Facades public merchant

GET /invoices/:invoiceId/events

Retrieves a bus token which can be used to subscribe to invoice events.

Parameters none
Facades public merchant
Response
Name Type
url
URL where you can subscribe to events
string
token
API token for subscriber resource, passed as `&token=` query parameter value
string
events
All supported `&events[]=` query parameter values. Can be `payment`.
array
actions
All supported `&action=` query parameter values. Can be `subscribe` or `unsubscribe`.
array

GET /invoices

Retrieves invoices for the calling merchant filtered by query. The `limit` and `offset` parameters specify pages for large query sets.

Parameters status orderId itemCode dateStart dateEnd limit offset
Facades merchant

POST /invoices/:invoiceId/refunds

Creates a refund request for the given invoice.

Parameters
Name Type Required Facades
etherAddress string merchant
amount number merchant
currency string merchant
Response
Name Type
id
Refund request resource id
string
requestDate
Time of API call
date
status
Can be `pending`, `success`, or `failure`
string
token
API token for invoice refund request resource
string

GET /invoices/:invoiceId/refunds/:requestId

Returns the status of a refund.

Parameters none
Facades merchant

DELETE /invoices/:invoiceId/refunds/:requestId

Cancels a pending refund request.

Parameters none
Facades merchant

GET /invoices/:invoiceId/refunds

Returns the status of all refunds on an invoice.

Parameters none
Facades merchant

POST /invoices/:invoiceId/adjustments

Accepts the overpayment or underpayment for the invoice. Uses type `acceptUnderpayment` to accept an underpayment. Uses type `acceptOverpayment` to accept an overpayment. Uses `commit` true to commit the adjustment to the invoice or false to preview it.

Parameters
Name Type Required Facades
type string merchant
commit boolean merchant

POST /invoices/:invoiceId/notifications

Resends the IPN for the specified invoice.

Parameters none
Facades merchant

Ledgers

Resource

Ledgers are records of money movement, includes sales, fees, and overpayments.

Schema
Name Type Read-Only
code
Ledger entry code
number
txType
English equivalent of ledger entry code
sale
sourceType
Can be `invoice` or `etherTx`
string
amount
Ledger entry amount
number
timestamp
Ledger entry timestamp
date
description
Ledger entry description
string
scale
Power of 10 used for conversion
number
invoiceId
Invoice identifier
string
invoiceAmount
Invoice amount
number
invoiceCurrency
Invoice currency code
string
exRates
All exchange rates used for invoice
array
`currency code`
Exchange rate for given currency code
number

GET /ledgers/:currency

Retrieves the caller's ledger entries for the given currency.

Parameters startDate endDate
Facades merchant

GET /ledgers

Retrieves the caller's ledgers for each currency with summary.

Parameters none
Facades merchant
Response
Name Type
currency
ISO 4217 3-character currency code
string
balance
Account balance, in given currency code
number

Sessions

POST /sessions

Creates an API session to protect against replay attacks and ensure requests are received in the same order they are sent.

Required Parameters none
Facades public

Settlements

Resource

Settlements are transfers of payment profits from Smartex to bank accounts and Ethereum wallets owned by merchants, partners, etc. This endpoint exposes reports detailing these settlements.

Schema
Name Type Read-Only
id
Resource id
string
amount
Settlement amount, in `currency`
number
currency
`eth` or ISO 4217 3-character currency code
string
status
Can be `processing`, `completed`, or `failed`
string
dateCreated
UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ. Indicates date when settlement was created.
date
dateExecuted
UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ. Indicates date when settlement was executed. This is the time when ledger entries were written.
date
dateCompleted
UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ. Indicates date when settlement was completed. Present for `completed` and `failed` settlements only.
date

GET /settlements

Retrieves settlement reports for the calling merchant filtered by query. The `limit` and `offset` parameters specify pages for large query sets.

Parameters dateStart dateEnd currency status limit offset
Facades merchant

GET /settlements/:settlementId

Retrieves the specified settlement report.

Parameters none
Facades merchant

GET /settlements/:settlementId/ledgerEntries

Gets an array of ledger entries that were paid out in the specified settlement. In some cases, only a partial amount of a ledger entry will be included in the settlement, and the ledger entry will be split across multiple settlements. All ledger entries will be for the same currency as the settlement itself.

Parameters none
Facades merchant
Response
Name Type
description
Description of the ledger entry
string
timestamp
UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ. Time when the ledger entry was written
date
amount
The amount that was paid out from this ledger entry in this settlement.
number
startAmount
For split entries only. The amount that this settlement begins paying from. This is equivalent to the endAmount of this entry from the previous settlement.
number
endAmount
For split entries only. The amount up to which was paid out in this settlement
number

GET /settlements/:settlementId/reconciliationReport

Gets a detailed reconciliation report based on the correlated ledgerEntries from this settlement.

Parameters none
Facades merchant
Response
Name Type
header object
numericId
Organization id
string
currency
Currency of the settlement. Formatted as `eth` or ISO 4217 3-character currency code
string
amount
Total settlement amount in currency being settled
number
settlementId
Resource id
string
settlementDate
UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ Date when the settlement was executed.
date
settlementPayoutInfo
Destination of the settlement. This can be a Ethereum address or bank account.
object
ledgerEntries array
code
Ledger entry code
number
orderId
Invoice order id (if applicable)
string
invoiceId
Invoice id (if applicable)
string
amount
Total settlement amount for this entry, in currency being settled
number
invoiceTime
UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ. Time of invoice creation(if applicable)
date
ledgerEntryDate
UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ. Time that this entry was written to the ledger
date
txAmount
Amount paid to the invoice (if applicable)
number
txCurrency
Invoice pricing currency (if applicable)
string
description
Ledger entry description
string

Subscriptions

Resource

Subscriptions are repeat billing agreements with specific buyers. Smartex sends bill emails to buyers identified in active subscriptions according to the specified schedule.

Schema
Name Type Read-Only
id
Resource id
string
token
API token for subscription resource
string
billData
See `bills` resource
object
schedule
Schedule of repeat bill due dates. Can be `weekly`, `monthly`, `quarterly`, `yearly`, or a simple cron expression specifying seconds, minutes, hours, day of month, month, and day of week. Smartex maintains the difference between the due date and the delivery date in all subsequent, automatically-generated bills.
string
status
Can be `draft` or `active` or `cancelled`. Subscriptions in active state will create new Bills on the nextDelivery date.
string
nextDelivery
UTC date, ISO-8601 format yyyy-mm-dd or yyyy-mm-ddThh:mm:ssZ. Default is current time. Current or past date indicates that the bill can be delivered immediately. Smartex may modify the hh:mm:ss values in order to distribute deliveries evenly throughout the day.
date

POST /subscriptions

Creates a repeat billing subscription.

Required Parameters billData schedule
Facades merchant

GET /subscriptions

Retrieves all of the caller's subscriptions.

Parameters status
Facades merchant

GET /subscriptions/:subscriptionId

Retrieves the specified subscription.

Parameters none
Facades merchant

PUT /subscriptions/:subscriptionId

Updates the specified subscription.

Required Parameters none
Facades merchant

Tokens

Resource

Tokens are API access identifiers which are associated with a set of capabilities. A capability may be very broad, for example, retrieve the list of all exchange rates. Or a capability may be very specific, for example, update bill #12345.

Schema
Name Type Read-Only
id
Client identity
string
pairingCode
Access approval code
string
facade
Can be `merchant`, or `pos`
string
label
Token label, may include spaces, underscores, and dashes
string

POST /tokens

Creates or claims an access token.

Required Parameters id
Facades public merchant onboarding
Response
Name Type
policies
undefined
array
policy
Can be `sin`, `access`, `events`, `id`, or `session`
string
method
Can be `requireSin`, `requireFacadeAccess`, `allowEventStream`, `invalidated`, `inactive`, `unclaimed`, `requireSession`
string
params
Can be `support`, SIN value, or null
array
resource
Token identifier
string
token
API token for token resource
string
facade
Can be `merchant`, or `pos`
string
dateCreated
UNIX time of creation, in milliseconds
number
pairingExpiration
UNIX time of expiration, in milliseconds
number
pairingCode
Access approval code
string