Creating an order is the first step towards accepting a payment. Generally, you want to create an order AFTER your customer clicks "Complete purchase" or a similar button in your online store. After you create an order using our RESTFUL API, you can redirect the user to the Mycelium Gear payment page associated with this order.
The request and the signature
To create an order, you should issue a signed POST request to https://gateway.gear.mycelium.com/gateways/:gateway_id/orders with at least one param — amount — it determines the amount to be paid for this order. The amount should be in the currency you have previously set for the gateway. If the gateway currency is BTC, then the amount is normally in satoshis. So, the request may look like this:
You can get the api_gateway_id value from your gateway's info in the admin panel.
Keychain id is used to generate an address for the next order. It can be any integer > 0, but it's better if it is a consecutive integer, so keep track of your order ids in your application. With the keychain id, the request will look like this:
Sending additional data
You may want to send some additional data with the transaction that will later be returned to you, unchanged, in the callback. This is useful if you wish to identify which record in your DB is associated with which order by using something other than order_id.
For example, suppose you have a Purchase model in your Rails app. You then might want to create a purchase and send its id in the
Later on, when a callback request is issued, this
callback_data param will be returned back with it and you'll be able to find that purchase in your DB.
In response to the request above, you will receive the following json from Mycelium Gear:
With this information, you can either manually display the payment address to the customer on your website (so he doesn't even have to leave your site), or you can redirect him to the Mycelium Gear payment page using the payment_id. The payment page url for redirection will then be:
Address reuse and keychain_id
keychain_id is used to derive the next address from your BIP32 pubkey. If you try to create orders with the same keychain_id they will also have the same address, which is, as you can imagine, not a very good idea. However it is allowed and there's a good reason for that.
Wallets that support BIP32 pubkeys will only do a forward address lookup for a limited number of addreses. For example, if you have 20 expired, unpaid orders and someone sends you money to the address of the 21-st order, your wallet may not see that. Thus, it is important to ensure that there are no more than 20 expired orders in a row.
If you have 20 orders in a row and try to create another one, Gear will see that and will automatically reuse the keychain_id (and consequently, the address too) of the 20-th order. It will also set the 21-st order's reused field to the value of 1. You will see it marked as reused in the admin panel too.
CAUTION: It is very important to make sure that you don't accidentally provide keychain_id that is too far away from the last used one. For example, if the gateway's
10, do not use
35 for the next order, use
last_keychain_id is always returned with other info when you create or check order status. Make sure you always track
last_keychain_id in your application - it is normally returned to you in the json with the other order info when you create or check orders.
Suppose you have a Rails controller with an action called complete_purchase which handles customer requests when they hit the "Complete purchase" button on your site. This is what code for it may look like:
# Save purchase in own DB
purchase = Purchase.create()
# Perform signed request to Mycelium Gear API
client = StraightServerKit::Client.new(gateway_id: api_gateway_id, secret: gateway_secret)
new_order = StraightServerKit::Order.new(amount: purchase.amount, callback_data: purchase.id)
order = client.orders.create(new_order)
# Save order reference
# Redirect customer to the payment page