multicurrency payment system

Introduction

The multicurrency payment system enables payments in multiple crypto-currencies by providing a backend structure to organize payment addresses. Payment listeners are created to constantly scan the blockchain and fire off callbacks when certain criteria is met. The multicurrency payment system facilitates easy access to cross-blockchain functionality.

convert, when set to a known currency, will convert amount to the currency set in currency.

amount defines the amount of satoshis of that currency that marks this payment as "complete". If not specified, there is no minimum, and even 1 satoshi will mark the payment as "complete".

min_confirms is the minimum amount of confirms needed to consider the payment complete.

fee_quote, when set to true, will prevent this program from creating a new address or payment listener. The payment response will be the cost (in satoshis of currency) of setting up that listener.

forward_to if specified, the exact amount paid (minus fees) will be forwarded to the address specified.

timeout defines the amount of time in which this payment listener will expire. It is always an int, but behaves differently given different inputs. When given a block number as input, it will timeout when that block is reached. When given a timestamp, it will timeout when that timestamp is reached. timeout cannot be zero.

callback is a JSON object containing information about the callback requested. It defines the requestor's constraints for the payment listener. The payment listener serves data determined by the requestor's JSON parameters. This is the payment system's callback service. It is explained in detail in the examples section below.

callback->method determines the method of callback. Currently supporting HTTP\_POST and BLOCKCHAIN\_WRITE callbacks.

callback->max_confirms is the maximum amount of confirms that will fire off a callback. After max_confirms has passed, no more callbacks will be sent.

callback->params define the callback service.

A successful payment request will create a payment listener. Whenever a payment listener detects certain conditions, a callback is fired off. Callbacks are fired off when both amount and min_confirms are reached. At the moment, HTTP_POST and BLOCKCHAIN_WRITE are the two options for callbacks served by the multi-currency-api.

HTTP_POST PARAMS

HTTP\_POST callbacks are programmable. This makes use of the application's connectivity to the network and cuts down on unnecessary HTTP traffic.

url is the URL that will be served with callback POST data. Note: when a callback fails, it will retry every 2, 4, 8, ... etc seconds, growing exponentially.

tx_notify is a boolean which determines whether or not a callback will be sent when a new transaction paying this address is detected.

data: All boolean data values will assure a response from the system that contains the data requested. For example, setting block to true will cause the system to respond with a callback containing the block number.

custom can be filled with whatever static JSON the requestor determines. It will be served to the callback endpoint URL specified in url.

BLOCKCHAIN_WRITE PARAMS

Callbacks are not limited to HTTP\_POST. You can request writing data to the blockchain instead.

payment response

The payment system responds based upon on the inputs given in the payment request. The system will always, at the very least, respond with an id and payment address for the currency specified as well as the amount that must be paid.

id is a unique identifier that must be passed to the status request. It is a unique identifier that identifies a payment listener and its associated address.

address is a crypto-currency address that payments will be made to. The payment listener associated with this address is created when this response is sent.

currency is the currency the address is associated with, and is the currency payments must be made in to that address.

amount will be an integer representation of the minimum amount of satoshis that must be spent in currency before the payment is considered complete.

fees is the number of satoshis paid in fees.

timeout is the number of seconds the listener will stay alive.

payment examples

If no callback is specified, the system will remain silent and ping nothing when the payment is complete. Requestors will have no choice but to make use of status requests to examine their payment.

If callback is specified, the payment system (which runs as a service) will begin serving callbacks when certain conditions are met. Here is a very general example that would be seen in the wild:

In the above example, a request is sent to get a Bitcoin payment address to watch for a payment equal to 2000000 satoshis of FLO. The response shows that 3050 satoshis of bitcoin are necessary to cover the cost of 2000000 satoshis of FLO. There is a minimum number of confirms set, and a fee quote is requested. The fee quote in this case is 50 satoshis of bitcoin.

The response will contain information about the payment listener binded to the given payment address.

mempool is true or false if the transaction has been listed in the mempool. This will be set to true automatically when confirms is greater than zero, regardless of whether or not the transaction is actually seen in the mempool.

received is the amount of coins received on the address so far.

confirms is an integer representation of the number of confirms since received has reached min_amount.

confirmed will be set to true only when the address has accumulated enough received coins to satisfy min_amount and all transactions in the transactions list have above min_confirms confirmations.

transactions is a JSON object containing a list of txids associated with this address along with the amount of coins sent to the payment address in each transaction..

This response is a JSON object with detailed information about the status of the payment request (identified by the address given in the original payment response) containing relevant info about the callback history.

Front-end preview (web browser)

Here is an example of the system in use as an API for putting messages into the blockchain. In this case, users can pay in multiple currencies to put a message into the Florincoin blockchain.

Contributions

Joseph A Fiscella @metacoin

License

ISC License

Copyright (c) 2014, Joseph A Fiscella <jfiscella@gmail.com>
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.