API

Rest API. Return values are JSON. Actual version “V1” is active.

API server

Test server

				
					https://api-test.heliumpay.net
				
			

Live server

				
					https://api.heliumpay.net
				
			

Transaction status table

0: Expecting payment

1: Processing incoming payment

2: Processed

3: Sending payout of the payment to wallet address

4: Payout sent

5: Calling webhook URL

6: Webhook URL called

7: Cleaning temp files

8: Not enough funds received – waiting for more

9: Error occurred – transaction is on hold, further processing is stopped

10: Payout is block for refund till the refund end date is reached

11: Transaction is refunded

 

Services

Fees

				
					https://api-test.heliumpay.net/api/v1/fees/

				
			

Returns the fees.

Retrieve the fees

Methode

GET

Parameters

None

Output

				
					{
"ok":1635782785,
"data":
    {"fix":{"v":0.75,"s":"0.75 USD","c":"USD"},
    "variable":{"v":1.8,"s":"1.8%","c":"HNT"}}
}
				
			

Transactions

Create transactions requests on our server. The transaction status can be retrieved. The transaction itself cannot be changed, once created. Only some values for a refundable transaction can be adjusted.

If you need an adjustment, please create a new transaction.

Once the transaction is created, the JSON will have a field “secret”, that is needed to change the transaction or request a webhook call or other operations regarding the transaction.

Create a transaction request

				
					https://api-test.heliumpay.net/api/v1/trx/
				
			

To receive a HNT payment, you need to register your payment expectation first. You will receive a wallet address and a memo for your client. The easiest way, is to then a QR code generator for you clients. We offer a free implementation here.

Methode

POST

Parameters

data
(String) – JSON with the order details

JSON object (data)

  • order_id (String) (mandatory)
    Max length: 250 lengths.
  • webhook_url (String) (mandatory)
    Your URL to a service that will handle the a call from our server, once the payment is done.
    Example: https://heliumpay.net/webhook/
    Max length: 250 letters.
  • wallet_receiver_address (String) (mandatory)
    Your helium wallet, where we will transfert the funds, once the payment is processed.
    Max length: 128 letters.
  • is_refundable (0|1)
    If you want to have this transaction request refundable, you can active this option. We will block your funds for the provided block time, so that we can refund the payment to your client if needed.
  • refund_days (Integer) – mandatory if is_refundable = 1
    Provide the days for the blocked funds. We will not pay out your funds to your wallet_address from start of the transaction request + amount of provided days. This will be the time period, where you can trigger a refund.
  • wallet_receiver_email (String) (optional, but recommended)
    If provided, you will receive not only the webhook call but also an email for the payment processing. It will be a good backup for your received payments.
    Max length: 255 letters.
  • payer_email (String)
    If provided, the payer will receive an email for the payment processing. 
    Max length: 255 letters.
  • secret (String)
    If not set, the server will generate a secret for you. You need to get it from the return JSON.
    Max length: 250 letters.
  • order_items (Array) (mandatory)
    Contains the order items. Used to calculate the HNT price. Having multiple items with different currencies if needed.
    Min length: 1 order item

JSON object (order item)

  • order_item_id (String or Integer) (optional, but recommended)
    Allows you to have a better trackability, in case you have more items per transaction to be paid.
  • amount_money (Decimal) (mandatory, if amount_crypto is not set)
    The item total price. If the same item is sold in one purchase, sum them up and add them as a total here.
    Max decimals digits for the fraction: 8 positions.
    Max length for the whole number: 29 numbers.
    Example: 99.12345678
  • amount_money_currency (String) (mandatory, if amount_money is set)
    We will calculate your provided currency to USD/HNT. It need to be currency symbol like CHF, USD, EUR and so on.
    Please check if your currency is supported. We are using Coingecko.
  • amount_crypto (Decimal) (mandatory, if amount_crypto is not set)
    Max decimals digits for the fraction: 8 positions.
    Max length for the whole number: 29 numbers.
  •  

Input

data JSON object

				
					{
"order_id":20210929001,
"webhook_url":"https://heliumpay.net/webhook/",
"wallet_receiver_address":"21bAVdMx6TkYgv48YJxeaDYQ95dAUtk7hHujHsoXeMQLeAAy1tcc",
"order_items":[
    {
        "order_item_id":"item_1",
        "amount_money":2.45,
        "amount_money_currency":"eur"
    },
    {
        "order_item_id":"item_1",
        "amount_crypto":1.5
    }
]}
				
			

data parameter

				
					data={%22order_id%22:%2220210929001%22,%22webhook_url%22:%22https://heliumpay.net/webhook/%22,%22wallet_receiver_address%22:%221bAVdMx6TkYgv48YJxeaDYQ95dAUtk7hHujHsoXeMQLeAAy1tcc%22,%22order_items%22:[{%22order_item_id%22:%22item_1%22,%22amount_money%22:2.45,%22amount_money_currency%22:%22eur%22},{%22order_item_id%22:%22item_1%22,%22amount_crypto%22:1.5}]}
				
			

Output

JSON object

  • ok (Integer) 
    Timestamp in seconds.
  • trx_id (String)
    The transaction request id. Needed for all operations with the transaction and webhook service calls.
  • total_amount_money (Decimal)
    The total amount in USD. To give you an idea about the equivalent HNT price to the USD.
  • amount_cryptototal_amount_money_currency (String) 
    The currency for your compare price. It will be USD, even if you have EURO prices.
  • total_amount_fee_crypto_est (Decimal)
    Estimated fee in HNT. The real amount of fee will be calculated, as soon as the payout to the wallet_address is started.
  • total_amount_fee_crypto (Decimal)
    The real fee. Zero until the payout was done.
  • timersec (Integer)
    Recommended seconds to for the transaction to be processed.
  • address (String)
    The helium wallet address, your client need to pay to. This is our wallet address to manage incoming payment transactions.
  • type (String)
  • amount (Decimal)
    The total amount of HNT for your client to pay.
    Partial payments are accepted, but we strongly recommend against it, because the HNT total payment have to match and this can be difficult with several payments.
  • memo_base64 (String)
    For the CLI transaction by your client. It is the memo base64 encoded.
  • memo (String)
    The memo contains the transaction id in hexadecimal notation.
  • is_refundable (Integer) [0|1]
    Indicates if this transaction is refundable. If the value is 1, then the transaction can be refunded to the payer.
  • refund_possible_till (String)
    If the transaction is refundable, then this will contain the end date, untill it is possible to refund the transaction. After this date, the funds will be paid out to the provided helium wallet. If the transaction is non refundable, then it will be null.
  • secret (String)
    For each operation will be the secret needed. To protect your transaction. Need to be stored on your side during the lifetime of open transaction.
				
					{
    "ok":1635783444,
    "trx_id":"30-BGRXF",
    "total_amount_money":8.83862068,
    "total_amount_money_currency":"usd",
    "total_amount_fee_crypto_est":0.22727379,
    "total_amount_fee_crypto":0,
    "timersec":300,
    "address":"1ahp2wiedP7v9EGNjjDpRsgB98sJXiGPBSNfnaoYj99MDdqyvBV",
    "type":"payment",
    "amount":2.20965517,
    "memo_base64":"MWUtLS0tLS0=",
    "memo":"1e------",
    "is_refundable":0,
    "refund_possible_till":null,
    "secret":"MRUKUHLORW"
}
				
			

Get the transaction Status

Retrieve the status of a transaction. Add the transaction id to the path.

				
					https://api-test.heliumpay.net/api/v1/trx/TRANSACTION_ID
				
			

Example

				
					https://api-test.heliumpay.net/api/v1/trx/12-LXUYJ
				
			

The status explains at which processing step the transaction is. Unused transactions are deleted after a several days.

Methode

GET

Parameters

None

Output

JSON object

  • ok (Integer) 
    Timestamp in seconds.
  • start (String)
    Creation date of the transaction.
  • status (Integer)
    Check the status table for more details.
				
					{
    "ok":1635888905,
    "start":"2021-09-29 11:43:00",
    "status":5
}
				
			

Get the transaction Status Full

Retrieve the full status of a transaction. Add the transaction id to the path and add /full. This is much slower and returns values you might not needed. Please be reasonable using it.

				
					https://api-test.heliumpay.net/api/v1/trx/TRANSACTION_ID/full
				
			

Example

				
					https://api-test.heliumpay.net/api/v1/trx/12-LXUYJ/full
				
			

The status explains at which processing step the transaction is. Unused transactions are deleted after a several days.

Methode

GET

Parameters

None

Output

JSON object

  • ok (Integer) 
    Timestamp in seconds.
  • start (String)
    Creation date of the transaction.
  • status (Integer)
    Check the status table for more details.
  • payment_request (JSON Object)
    The same JSON object, like you receive from the transaction creation call. Except the secret field is missing.
				
					{
    "ok":1635888902,
    "start":"2021-09-29 11:43:00",
    "status":5,
    "payment_request":{
        "trx_id":"2-YMEJA",
        "total_amount_money":29.25752157,
        "total_amount_money_currency":"usd",
        "total_amount_fee_crypto_est":0.04980883,
        "total_amount_fee_crypto":0,
        "timersec":480,
        "address":"1adJkwpNUjETAZCU7mH3UTDALnxjwxnTTPbBwqiwbruENNZbMbp",
        "type":"payment",
        "amount":1.66235918,
        "memo_base64":"Mi0tLS0tLS0=",
        "memo":"2-------",
        "is_refundable":0,
        "refund_possible_till":null
    }
}
				
			

Update the transaction

You can update the transaction if it is refundable. You can only change the refund end date, by sending the refund days. The days will be used to calculate a new refund end date from now on.

				
					https://api-test.heliumpay.net/api/v1/trx/TRANSACTION_ID
				
			

Example

				
					https://api-test.heliumpay.net/api/v1/trx/12-LXUYJ
				
			

Methode

PUT

Parameters

data
(String) – JSON with the order details

JSON object (data)

  • secret (mandatory)
    The secret value you recieved from the creation service call.
  • refund_days (Integer) (mandatory)
    How many more days from now on, will the transaction be refundable. This will block the funds payout till this new end date.

Input

data JSON object

				
					{
    "secret":"ABCDEF",
    "refund_days":10
}
				
			

data parameter

				
					data={%22secret%22:%22ABCDEF%22,%22refund_days%22:10}]}
				
			

Output

JSON object

  • ok (Integer) 
    Timestamp in seconds.
  • trx_id (String)
    The transaction request id. Needed for all operations with the transaction and webhook service calls.
  • total_amount_money (Decimal)
    The total amount in USD. To give you an idea about the equivalent HNT price to the USD.
  • amount_cryptototal_amount_money_currency (String) 
    The currency for your compare price. It will be USD, even if you have EURO prices.
  • total_amount_fee_crypto_est (Decimal)
    Estimated fee in HNT. The real amount of fee will be calculated, as soon as the payout to the wallet_address is started.
  • total_amount_fee_crypto (Decimal)
    The real fee. Zero until the payout was done.
  • timersec (Integer)
    Recommended seconds to for the transaction to be processed.
  • address (String)
    The helium wallet address, your client need to pay to. This is our wallet address to manage incoming payment transactions.
  • type (String)
  • amount (Decimal)
    The total amount of HNT for your client to pay.
    Partial payments are accepted, but we strongly recommend against it, because the HNT total payment have to match and this can be difficult with several payments.
  • memo_base64 (String)
    For the CLI transaction by your client. It is the memo base64 encoded.
  • memo (String)
    The memo contains the transaction id in hexadecimal notation.
  • is_refundable (Integer) [0|1]
    Indicates if this transaction is refundable. If the value is 1, then the transaction can be refunded to the payer.
  • refund_possible_till (String)
    If the transaction is refundable, then this will contain the end date, untill it is possible to refund the transaction. After this date, the funds will be paid out to the provided helium wallet. If the transaction is non refundable, then it will be null.
				
					{
    "ok":1635888902,
    "trx_id":"2-YMEJA",
    "total_amount_money":29.25752157,
    "total_amount_money_currency":"usd",
    "total_amount_fee_crypto_est":0.04980883,
    "total_amount_fee_crypto":0,
    "timersec":480,
    "address":"1adJkwpNUjETAZCU7mH3UTDALnxjwxnTTPbBwqiwbruENNZbMbp",
    "type":"payment",
    "amount":1.66235918,
    "memo_base64":"Mi0tLS0tLS0=",
    "memo":"2-------",
    "is_refundable":1,
    "refund_possible_till":"2021-10-07 11:43:00"
}
				
			

Webhooks

The webhook is called  automatically by us, once the payment is processed. If the transaction is refundable, the webhook will be called before the payout is done.

You can request a webhook call in case the call is missing due to network issues or other events.

Get the webhook calls

Retrieve all webhook calls made from our server.

				
					https://api-test.heliumpay.net/api/v1/trx/TRANSACTION_ID/?secret=SECRET
				
			

Example

				
					https://api-test.heliumpay.net/api/v1/webhook/7-FMXAU/?secret=abcdef
				
			

Methode

GET

Parameters

  • secret (String)
    the secret of the transaction

Output

JSON object

  • ok (Integer) 
    Timestamp in seconds.
  • data (Array of JSON objects)
    The single call in an array.
    • id (Integer)
      The internale webhook call id.
    • start (String)
      The date of the URL call.
    • success (Integer) [0|1]
      Indicates if the call was successful executed.
    • errormsg (String)
      Will contain an error message if available.
    • status_code (Integer)
      Return value from the server of the webhook URL.
    • webhook_url (String)
      The called URL.
    • note (String)
      A note from the server. If it is a notification or normal call.
    • data (JSON Object)
      Contains the values sent toward the webhook URL.
				
					{
    "ok":1635938726,
    "data":[
        {
            "id":32,
            "start":"2021-10-13 17:31:10",
            "success":1,
            "errormsg":"",
            "status_code":400,
            "webhook_url":"https:\/\/vollstart.de\/wc-api\/wc_gateway_heliumpay\/?order_id=2502",
            "note":"Clean up call. Cancel payment",
            "data":{
                "trx_id":"7-FMXAU",
                "start":"2021-10-02 19:36:00",
                "lastchange":"2021-10-13 16:09:01",
                "total_amount_money":97.40605053,
                "total_amount_money_currency":"usd",
                "total_amount_crypto":5.06531724,
                "total_amount_fee_crypto":0,
                "status":7,
                "order_id":2502,
                "wallet_receiver_address":"1bAVdMx6TkYgv48YJxeaDYQ95dAUtk7hHujHsoXeMQLeAAy1tcc",
                "wallet_receiver_email":"",
                "paid_at":null,
                "is_refundable":0,
                "refund_possible_till":null
            }
        }
        ]
}
				
			

Request a webhook call

Request a webhook call to the webhook URL of the transaction.

				
					https://api-test.heliumpay.net/api/v1/trx/TRANSACTION_ID
				
			

Methode

POST

Parameters

  • secret (String)
    the secret of the transaction

Output

JSON object

  • ok (Integer) 
    Timestamp in seconds.
  • data (Integer)
    The ID of the webhook call log entry.
				
					{
    "ok":1635938726,
    "data":34
}
				
			

Refunds

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut elit tellus, luctus nec ullamcorper mattis, pulvinar dapibus leo.

Clients

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut elit tellus, luctus nec ullamcorper mattis, pulvinar dapibus leo.