Coinilla API 1.0 Documentation

Accepting payment with our gateway is so simple.


Step 1: Requesting Payment

POST these parameters to https://www.coinilla.com/pay

  • func : this is function ID and should be 1 for making payment.
  • apikey : your website API KEY
  • currency : BTC, USD, EUR, GBP, CNY, CHF, JPY, INR or RUB
  • amount : amount in the currency you set
  • refnum : reference id. unique number or string such as order id. you will use it in callback for reference. (max 255 chars)
  • desc : small description (max 255 chars)
  • return_url : successful payment and default returning url. this overrides default successful URL in the API setup
  • fail_url : failed payment url. override default fail URL in the API setup. if not set, we refer API setup and return_url
  • unconfirm_url : 0 confirmed (pending confirmation) payment url. override default pending URL in the API setup. if not set, we refer API setup and return_url
  • duplicate_refnum : 0 or 1. default is 0. if set to 1 we accept duplicate refnum
  • extra_1 : extra value you may set for use in callback. (max 255 chars)
  • extra_2 : extra value you may set for use in callback. (max 255 chars)
  • extra_3 : extra value you may set for use in callback. (max 255 chars)

In return, we send a JSON array with two parameters:

  • invoice : invoice id
  • error : error message if something is wrong

At this point you should check error message. if it is empty you should redirect users to https://www.coinilla.com/pay?invoice=[invoice id here] for payment.



Step 2: Returning from Gateway and Payment Verification

We will redirect user to one of the URLs (return_url, fail_url or unconfirm_url) you set in the API setup (or overridden in Step #1). We POST these parameters to return_url, fail_url or unconfirm_url:

  • state :
    • `OK` if payment was successful.
    • `PENDING` if payment didn't receive enough confirmation in time period (received 0 confirmations or less than the minimum you set in API).
    • `CANCELED` if user canceled process or the process failed.
    • * We only send OK state to `return_url` URL, PENDING to `unconfirm_url` URL and CANCELED to `fail_url` URL.
  • refnum : your reference id
  • invoice : invoice id
  • trans_id : transaction number
  • address : bitcoin address
  • amount : amount in the currency you sent
  • satoshi : amount in satoshi
  • extra_1 : extra value you set
  • extra_2 : extra value you set
  • extra_3 : extra value you set

Now you SHOULD verify payment before processing customer order/request and do not refer to `state` value only.

POST these parameters to https://www.coinilla.com/verify

  • func : this is function ID and should be 3 for verification using refnum and invoice.
  • apikey : your website API KEY
  • invoice : invoice id
  • refnum : reference id

In return, we send a JSON array with two parameters:

  • status : last status of payment. can be `paid`, `paid-0` or `notpaid`
    • `paid` if payment was successful. you should accept this status only in `OK` state.
    • `paid-0` if payment was 0 confirmed. you should accept this status in `OK` state and `PENDING` state. in `OK` state this mean you set 0 confirmations in the API setup page and payment received 0 confirmations. In `PENDING` state this mean that time ended and 0 confirmations or more confirmation detected for transaction but confirmation not reached minimum you set in the API setup.
    • `nopaid` if the payment failed or canceled. you may accept this status only in `CANCELED` state.
  • error : error message if something is wrong. empty if no error occured.

These are all steps you need to do! Now you can store result in database and process customer order/request.



(Optional) Alternative Verification Function

You can verify the payment by transaction id instead of reference id and invoice id too:

To do this POST these parameters to https://www.coinilla.com/verify

  • func : should be 4 for verification using transaction id.
  • apikey : your website API KEY
  • trans_id : transaction id

In return, we send a JSON `status` and `error` parameters.

  • status : last status of payment. can be `paid`, `paid-0` or `notpaid`
    • `paid` if payment was successful. you should accept this status only in `OK` state.
    • `paid-0` if payment was 0 confirmed. you should accept this status in `OK` state and `PENDING` state. in `OK` state this mean you set 0 confirmations in the API setup page and payment received 0 confirmations. In `PENDING` state this mean that time ended and 0 confirmations or more confirmation detected for transaction but confirmation not reached minimum you set in the API setup.
    • `nopaid` if the payment failed or canceled. you may accept this status only in `CANCELED` state.
  • error : error message if something is wrong. empty if no error occured.


You can find example code in the plugins page.

Disclaimer: We are not affiliated with any business using our services and we are not money transfer service. We are not responsible for any possible fraud and would not be able to issue any refunds because you are paying DIRECTLY and INSTANTLY to merchant Bitcoin address and not ours.