IOTA gateway

Welcome to PayIOTA's API documentation!

1. Introduction

The API provides you programmatical access to our payment gateway’s services. It allows you to create new invoices (address/price pairs) from your IOTA seed, and update the IOTA price of an already created invoice. They are implemented as HTTP(s) POST calls to https://payiota.me/api.php

2. API Setup

All necessary information, such as your API key and verification string can be found on your interface after you sign-up for our service. You need a valid email address to do so. You are responsible for keeping your API key safe.

3. API Response

Our API will return to you a JSON array if the call is an invoice creation. If it is a price compensation call, it will return the new price in integer format (number of IOTA’s).

4. Invoice creation

To create an address/price pair, you will need to send a POST request to the API URL with the following parameters:

api_key=[your_api_key]&currency=[3_letter_currency_code_caps]&price=[price]&custom=[custom_string]&ipn_url=[ipn_url]&action=new

The parameter ipn_url is optional; if you do not specify it, PayIOTA will use your default IPN URL that you set on the interface page. If the request was successful, you will get a response such as this:

["YMG9BPGYKCVAHTOLSIOSFNLNHRVBHMVBWEQCCUNOXATFZMBURWSXCSRVMQOWWGUHRELMCKGRWDUXRHBQQSJBMECXUH","29176011"]

It is a JSON-encoded array. In the 0th place, you have the address your user needs to send the IOTA payment to, for the amount in the 1th place. The value you give for price and currency will always be converted to USD currency and price on our end. You can also use 'IOTA' as the currency value, thus giving the price in IOTA. Be aware that invoices have a maximum life of 1 week - after that our service will not check the address to prevent overloading our server and the full node it is checking from.

If the request was not successful, you will get a raw error coded response such as:

ERR_FATAL_3RD_PARTY (Nodes offline) ERR_IPN_URL_INVALID (when you have no default IPN URL set and you have not specified a custom IPN URL, or your specified IPN URL is invalid) ERR_CUSTOM_INVALID (empty custom variable) ERR_PRICE_INVALID (price variable not an integer) ERR_API_KEY_INVALID (invalid API key) Sorry, a fatal error has occured, service is unavailable! (As a string, if a fatal error happens)

5. Security/Privacy

For security and privacy reasons, you may want to encrypt the custom string on your side. Then, when the payment complete IPN is sent, you can decrypt it on your side. If there is a mismatch, you’d know that the payment was tampered with. It is extremely important to check the verification string when you receive the IPN (Instant Payment Notification).

You should store your verification string from your interface page server-side and verify that the received POST value of ‘verification’ is the same as in your database. If not, someone is attempting to fake transactions.

6. Speed

It takes up to 10 seconds for our server to generate an address from your seed. Therefore, we recommend creating an invoice when a user is created for each item you sell, and storing it in a database. When a user wants to pay, you can pull the invoice out of your database. To compensate for IOTA price changes, we have another API call for updating the price the moment your user wishes to buy something. That API call completes very quickly.

7. Refunds

You are responsible for all refunds unless there is an error on our side. All the addresses are derived from your seed, so you have direct control over your funds. Please see the legal document for more information.

8. Fees

Staying true to IOTA’s idea, we have no service fees either.

9. IPN

When an invoice is paid (meaning the address has a balance equal or more than that of the 1th place in the response when you generated the invoice), our server will send you a POST request with the following variables: address The IOTA address the user paid to

realID : Your ID

price : Price in USD

price_iota : Price in IOTA

custom : Your custom string

ipn_url : Your IPN URL

verification : Your verification string (Verify!)

paid_iota : How much IOTA’s your user paid

done : Should be 1. Whether the payment is complete

created: Date when invoice was created. In UNIX time.

IPN’s are only sent once, but you can see all your invoices on the interface page.

10. Price Compensation

When you generate an invoice for a later date, it will generate using IOTA’s current price (we do not currently have a time machine). So, we have a quick function for updating an invoices price to the current IOTA price. It will update the IOTA price to the USD price you have given it on the original creation, you cannot change that. The parameters are the following:

api_key=[your_api_key]&address=[address_of_saved_invoice]&verification=[verification_string]&action=update

If the request was successful, you will get a response like this:

180000

That integer is the new price in IOTA’s. If it was not successful, you will get a raw error coded response:

ERR_DISALLOWED (address not yours or is already paid, check your verification string)

Or

ERR_NOT_FOUND (address not found)

11. IOTA to USD API

You can use our API to convert an amount of IOTA to it's price in USD.

It is easy: https://payiota.me/api.php?action=convert_to_usd&iota=amount_you_want_to_convert

It will give you the corresponding price in USD.

12. Examples

Please Github, https://github.com/lacicloud/payiota, 'examples' folder for PHP examples.

13. Support

Our support email address is [email protected] - Please be mindful that we do not currently a Shopify plugin. It seems that Shopify does not support extra gateways - We have contacted them and are awaiting their reply on implementing our gateway.