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.