So, if I understand correctly, the refund is held until a new purchase is done by someone?

I'm looking into a replacement for mybitcoin. I had one question on your service.
It seems that you forward payments directly to the bitcoin address provided by merchant, so no e-wallet/account balance.
However the part that talks about refunds seems to indicate that there is an e-wallet/account balance.

Could you shed some light on how that works?

It kind of works, but it needs to be more robust and documented.

1) implement API and transactions log - so I can see what API calls you sent and received. It will be helpful in debugging and disputes.
2) implement test API endpoint - it's not a problem to send real transactions during tests, but they take an hour to get confirmed so my development is slowed down
3) document when and how often you try to call back. What happens if my server does not respond or DNS resolution fails? Are HTTP redirects followed? Is HTTPS supported? etc
4) document foreign_order_id, custom_field and transaction_timestamp, order_status
5) What happens if I want to use one address per customer, as opposed to one address per order? It seems subsequent transactions to an address still fire the callback. Is total_amount in POST /order necessary at all? What happens if customer sends less or more than total_amount?
6) Think about better/more standard cryptography. A homemade HMAC and plaintext authtoken are not good ideas, they are just temporary quick-and-dirty solutions.

Looks great. I might try this.  I have one one question.  I'm not all savvy with the forms and stuff.  If I wanted to gather the persons shipping address, would that be done on your form and sent to me or would I have to make a seperate form to direct the person to after payment is made?

I will make a node.js npm package for the API one day if the API proves useful.

So far I have a few bug reports/feature requests:

1) Stop violating HTTP/1.1. http://tools.ietf.org/html/rfc2616#section-14.1 says:

   If no Accept header field is present, then it is assumed that the
   client accepts all media types. If an Accept header field is present,
   and if the server cannot send a response which is acceptable
   according to the combined Accept field value, then the server SHOULD
   send a 406 (not acceptable) response.

Your server (not necessarily the code you wrote but maybe web server or Ruby stuff you are using) sends 406 if no accept: header is present. This is clearly a violation as it contradicts "If no Accept header field is present, then it is assumed that the client accepts all media types."

As a quick and dirty solution, you can say in your documentation that accept: */* header must be present because of a bug in such and such software you use.

2) Enhance your documentation. Your API expects HTTP requests with content-type 'application/x-www-form-urlencoded' and responds with application/json. But from your documentation it seems that API expects JSON passed in POST body, which is a different thing. I only could figure out by looking at your Ruby example.

3) Document your existing or planned private key recycling policy. You must either destroy, reuse or send your outdated private keys to API users. Otherwise you are going to end with verifying transactions for millions of keys.

Usecase:

0. US Govt makes bitcoin a legal tender.
1. Google Checkout and Paypal start to accept bitcoins using your API
2. Zillions of users request a bitcoin address to pay for a service but never pay and even don't record the generated addresses
3. Zillions of addresses (and corresponding private keys!) become stranded
4. Your service keeps storing zillions of key pairs generated 10 years ago and keeps looking for a transaction for any of them.

So I suggest:

a) to document default expiration time for addresses
b) to reuse expired addresses so your wallet.dat grows slower over time
c) to implement order cancellation API to allow manual expiration

I think, I will make a Ruby on Rails gem to work with such Gateways easy. I think, it could be a great improvement in current situation with setting bitcoin payments on your websites...