ASP.NET C# Crypto Payment API
Here you will find everything you need to get started coding for bitcoin/altcoin on ASP.NET.
Accept Bitcoin, BitcoinCash, BitcoinSV, Litecoin, Dash, Dogecoin, Speedcoin, Reddcoin, Potcoin, Feathercoin, BTC, Vertcoin, Peercoin, MonetaryUnit Payments Online on your ASP.NET MVC C# website
If you use PHP, please go to HERE »
If you use Python, Java, Wordpress, Node.js, etc. please go to HERE »
I. ASP.NET Payment Box Installation -
- Two Versions Available (stable version 1.0.10 - iFrame payment box and
version 1.2.0RC1 - mobile friendly json payment box) -
a. Version 1.0.10 - Stable, iFrame Payment Box, Not Mobile Friendly. Demo »
Install package from nuget.org - https://www.nuget.org/packages/GoUrl.io/ (command "Install-Package GoUrl.io", it is package only without examples)
or download full package v1.0.10 with Examples from Github / Gourl.io directly
b. Version 1.2.0RC1, Mobile Friendly, White Label Product. Demo »
Download full package v1.2.0RC1 (Release Candidate 1) with Examples from github or direct zip source file
- Package uses own database with table crypto_payments (file GourlDb.mdf) for storing bitcoin/altcoin payment information (transaction ID, payment Date, user ID, order ID, etc) on your website.
If you wish to move this table to your existing database, run sql query, it will create new MSSQL "crypto_payments" table in your existing database;
and after configure 'connectionStrings' in Web.config.
Package default database store in App_Data folder. Example - Asp Page with All Payment Statistics
- Free Register or Login on the gourl.io, create new payment box/es and get free GoUrl Private/Public Keys (screenshot)
- Place all your GoUrl Private Keys in file Web.config (screenshot)
- Create payment controller with your public/private keys, orderID, userID, etc. See controller example, ready to use with files from directory /Examples/ - ExamplesController.cs (screenshot)
- Edit the function Main in the file NewPayment.cs to add additional actions after a payment has been received (update database records, send email to user, etc). More info
- You will need to place Callback URL in bitcoin/altcoin payment box (screenshot), please use: http://yoursite.com/GoUrl/Callback
- For display bitcoin/altcoin payment box in your View, you need to use Helper Cryptobox (@Html.Cryptobox(DisplayCryptoboxModel) or display Partial View Partial/_Cryptobox.
See /Examples/Basic.cshtml and other Examples.
For use examples, please add your gourl private keys to Web.config and gourl private/public keys to several places in ExamplesController.cs
THAT'S IT! CRYPTO PAYMENT BOX SHOULD NOW BE WORKING ON YOUR SITE
Download ASP.NET Package
100% Free Open Source on Github »
II. JSON Customize Payment Box (your logo)
You can use asp function cryptobox_json_url(), it generates url with your parameters to gourl.io payment gateway. Using this url you can get bitcoin/altcoin payment box values in JSON format and use it on html page with Jquery (on the user side, asp json example).
JSON Data -
Payment Not Received
JSON ASP Box Example
III. ASP.NET Payment box Options
Create payment controller with your public/private keys, orderID, userID, etc.
See controller example - ExamplesController.cs (see screenshot).
Available Options -
OptionsModel options = new OptionsModel()
public_key = "-your gourl public key for Bitcoin/Litecoin/etc box-",
private_key = "-your gourl private key for Bitcoin/Litecoin/etc box-",
webdev_key = "",
orderID = "your_product1_or_signuppage1_etc",
userID = "",
userFormat = "COOKIE",
amount = 0,
amountUSD = (decimal)2.15,
period = "NOEXPIRY",
iframeID = "",
language = "DE"
Crypotcoin Payment Box Public Key from your new payment box. Example
Crypotcoin Payment Box Private Key from your new payment box. Example
Your order id or product name; allow symbols: a..Z0..9_-@.; max size: 50 symbols, examples: 'order44', 'premium_page', 'product123
Some of your users can have the same orderID but combination 'orderID'+'userID' should be unique. For example, on premium page you can use for all visitors: orderID="premium" and userID="" (empty; therefore system will automatically generate unique userID).
Optional, manual setup unique identifier each of your users. By default the Payment Box uses randomly generated string in userID and saves it in user cookies.
You need to use a variable userID when you use Cryptocoin Payment Box for registered users on your website.
You don't need to use userID if using Cryptobox for unregistered website visitors (for example, on website sign-up form).
Examples: 'user1', 'user2', '3vIh9MjEis'
allow symbols: a..Z0..9_-@.; max size: 50 symbols
System uses variable userFormat only if userID above is empty - it will save random auto-generated userID in cookies, sessions or use user IP address as userID.
Default: COOKIE. Available values: COOKIE, SESSION, IPADDRESS, *MANUAL.
*If userID above is not empty, use userFormat=MANUAL.
Amount of cryptocoins which will be used in the payment box/captcha, precision is 4 (number of digits after the decimal), example: 0.0001, 2.444, 100, 2455, etc.
We will use this value of cryptocoins in the payment box with a small fraction after the decimal point to uniquely identify each of your visitors individually -
(for example, if you enter 0.011 BTC, one of your user will see 0.011308 BTC, and another will see 0.011832 BTC, etc).
You can directly specify your price in USD (float values allowed) and cryptobox will automatically convert that USD amount to cryptocoin amount using today live cryptocurrency exchange rates (updated every 30min).
For example, if you select LITECOIN currency and amountUSD = 4.2 USD - we will convert it to litecoins and it will be 0.86 LTC. We will display it in crypto payment box for payment by the user.
User will pay you all times the actual price which is linked on current exchange price in USD on the datetime of purchase.
Also you can use Poloniex.com, Bitstamp.net, etc autosell feature and auto trade your cryptocoins to USD/BTC after payment received.
Using that functionality (price in USD), you don't need to worry if cryptocurrency prices go down or go up.
You can use in cryptobox options one variable only: amount or amountUSD. You cannot place values of those two variables together.
Period after which the payment becomes obsolete and new Cryptocoin Payment Box will be shown (you can use it to take new payments from existing users periodically on daily/monthly basis).
Allow values: NOEXPIRY, 1 MINUTE - 90 MINUTE, 1 HOUR - 90 HOURS, 1 DAY - 90 DAYS, 1 WEEK - 90 WEEKS, 1 MONTH - 90 MONTHS
Optional, html iframe cryptobox element id; when iframeID value is empty - system will autogenerate iframe id. Allow symbols: a..Z0..9
Cryptobox localisation. Languages currently available for GoUrl Payment Box: en - English, es - Spanish, fr - French, de - German, nl - Dutch, it - Italian, ru - Russian, pl - Polish, pt - Portuguese, fa - Persian, ko - Korean, ja - Japanese, id - Indonesian, tr - Turkish, ar - Arabic, cn - Simplified Chinese, zh - Traditional Chinese, hi - Hindi.
We can add your language localisation in the cryptocoin payment box (all texts can be displayed in your local language).
To do this please first download this language file with the text in English.
At the end of each line, please add your translation from English and send this text file with your translation back to us on email and we will include your translation.
If you use the same public_key, orderID and userID
in your multiple cryptocoin payment boxes on different website pages and a user has made payment;
a successful result for that user will be returned on all those pages (if period time not expired).
If you change - public_key or orderID or userID - new cryptocoin payment box will be shown for existing paid user
(function is_paid() starts to return 'false').
We store all your users successful payment results on our server and you have a copy of these results in your local database, MSSQL table crypto_payments with GMT time.
IV. ASP.NET Crypto Class - List of Functions
Cryptocurrency Payment Class (file Cryptobox.cs) have following public functions -
- function is_paid(bool remotedb = false)
Checks your local database whether payment has been received and is stored on your local database.
If use remotedb = true, it will check also on our cryptocoin payment server (gourl.io),
and if payment is received, it saves it in your local database. Usually user will see on bottom
of payment box button 'Click Here if you have already sent coins' and when they click on that button,
script it will connect to our remote cryptocoin payment box server. Therefore you don't need to use
remotedb = true, it will make your webpage load slowly if payment on gourl.io is checked during
each of your page loadings.
- function is_confirmed()
Function return is true if transaction/payment has 6+ confirmations.
It connects with our payment server and gets the current transaction status (confirmed/unconfirmed).
Some merchants wait until this transaction has been confirmed.
Average transaction confirmation time - 10-20min for 6+ confirmations (altcoins)
- function amount_paid()
Returns the amount of coins received from the user. Float value.
- function amount_paid_usd()
Returns the approximate amount in USD received from the user
using live cryptocurrency exchange rates on the datetime of payment.
Live Exchange Rates obtained from sites bitstamp.net, poloniex.com and blockchain.info
and are updated every 30 minutes!
- function set_status_processed()
You can use this function when user payment has been received
(function is_paid() returns true) and want to make one time action,
for example display 'thank you' message to user, etc.
This function helps you to exclude duplicate
processing. Call set_status_processed() and after check status with
Please note that the user will continue to see a successful payment result
in their crypto Payment box during the period/timeframe you specify in cryptobox option "period"
- function is_processed()
If payment status in database is 'processed' - return true,
otherwise return false. You need to use it with function set_status_processed() together.
- function cryptobox_type()
Returns 'paymentbox' or 'captchabox'
The Cryptocoin Payment Box and Crypto Captcha are
absolutely identical technically except for their visual effect.
It uses the same code to get your user payment, to process that
payment and to forward received coins to you. They have only two
visual differences - users will see different logos and different
text on successful result page.
For example, for bitcoin it will be - 'Bitcoin Payment' or
'Bitcoin Captcha' logos and when payment is received we will publish
'Payment received successfully' or 'Captcha Passed successfully'.
We have made it easier for you to adapt our payment system to your website.
On signup page you can use 'Bitcoin Captcha' and
on sell products page - 'Bitcoin Payment'.
- function payment_id()
Returns current record id from your mysql table crypto_payments.
This table stores all payments from your users.
- function payment_date()
Returns payment/transaction datetime in GMT format.
Example - 2014-09-26 17:31:58 (is 26 September 2014, 5:31pm GMT)
- function payment_info()
Returns object with current user payment details -
* coinLabel - cryptocurrency label
* countryID - user location country, 3 letter ISO country code
* countryName - user location country
* amount - paid cryptocurrency amount
* amountUSD - approximate paid amount in USD on datetime of payment made
* addr - your internal wallet address on gourl.io which received this payment
* txID - transaction id
* txDate - transaction date (GMT time)
* txConfirmed - 0 - unconfirmed transaction or 1 - confirmed with 6+ confirmations
* processed - true/false. True if you called function set_status_processed() before
* processedDate - GMT time when you called function set_status_processed()
* recordCreated - GMT time a payment record was created in your database
- function cryptobox_reset()
Optional, it will delete cookies/sessions with userID and new cryptobox with new payment amount
will be displayed after page reload. Cryptobox will recognize user as a new one with new generated userID.
For example, after you have successfully received the cryptocoin payment and had processed it, you can call
one-time cryptobox_reset() in end of your script. Use this function only if you have not set userID manually.
- function coin_name()
Returns coin name (bitcoin, bitcoincash, litecoin, dogecoin, etc)
- function coin_label()
Returns coin label (BTC, BCH, BSV, LTC, DOGE, etc)
- function iframe_id()
Returns payment box frame id
- IEnumerable <crypto_payments> payment_history (int boxID = 0, string orderID = "", string userID = "", string countryID = "", string boxType = "", string period = "7 DAY")
Returns array with history payment details of any of your users / orders / etc. from table crypto_payments (except unrecognised payments) for custom period - period.
- IEnumerable <crypto_payments> payment_unrecognised (int boxID = 0, string period = "7 DAY")
Returns array with unrecognised payments for custom period - $period. (users paid wrong amount to your internal wallet address). You will need to process unrecognised payments manually.
We forward you ALL bitcoins/altcoins received to your internal wallet address including all possible incorrect amount/unrecognised payments automatically every 30 minutes. Therefore you need to deal with your user directly to resolve the situation or return that incorrect payment back to your user. You will have a copy of the statistics on your member page with details of incorrect received payments. You have copy of that statistics on your member page with details of incorrect received payments.
Static Class CryptoHelper (file Cryptobox.cs) have following public methods -
- function string cryptobox_selcoin (string coins, string defCoin = "")
Current selected coin by user (bitcoin, dogecoin, etc. - for multiple coin payment boxes)
- function decimal convert_currency_live (string from_Currency, string to_Currency, double amount)
Fiat Currency Converter using Google Finance live exchange rates.
convert_currency_live("EUR", "USD", 22.30) - convert €22.30 => $25.17
- function string get_country_name (string countryId)
Get country name by country code (i.e. CAN => Canada, FRA => France, etc)
Cryptocurrency Payment Html Helper Cryptobox (file Controls.cs) have following public methods -
- MvcHtmlString (Cryptobox (this HtmlHelper helper, DisplayCryptoboxModel model, bool submit_btn = true, int width = 540, int height = 230, object box_style = null, object message_style = null, string anchor = "")
Display Cryptocoin Payment Box; the cryptobox will automatically display successful message if payment has been received. Usually user will see on bottom of payment box button 'Click Here if you have already sent coins' (option: submit_btn = true) and when user click on that button, script will connect to our remote cryptocoin payment box server and check user payment.
As backup, our server will also inform your server automatically through IPN every time a payment is received (file GoUrlController.cs Action Callback).
I.e. if the user does not click on the button or you have not displayed the button, your website will receive a notification about a given user anyway and save it to your database.
Next time your user goes to your website/reloads page they will automatically see the message that their payment has been received successfully. For big QR code size, please use width >= 565px
- MvcHtmlString LanguageBox (this HtmlHelper helper, string defaultLanguage = "en", string anchor = "gourlcryptolang")
Language selection dropdown list for cryptocoin payment box
- MvcHtmlString CurrencyBox (this HtmlHelper helper, string coins, string defCoin = "", string defLang = "en", int iconWidth = 50,
object style = null, string directory = "images", string anchor = "gourlcryptocoins")
Multiple crypto currency selection list. You can accept payments in multiple crypto currencies. For example you can setup product price in USD and accept payments in bitcoin, bitcoinCash, bitcoinSV, litecoin, dogecoin.
V. ASP.NET Instant Payment Notification/Callback -
- When a user has made a payment, our server will send payment data using HTTP POST method on your callback url specified in field Callback URL of your crypto payment box.
- Please use http://yoursite.com/GoUrl/Callback as your callback url on asp.net website
- Edit the function Main in the file NewPayment.cs to add additional actions after a payment has been received (update database records, send email to user, etc).
It is a IPN function. This function is used every time a new payment from any user is received successfully.
Function receives paymentID - current payment ID (record id in your mssql table crypto_payments), payment details and box_status - 'cryptobox_newrecord' OR 'cryptobox_updated'.
- Please note, all received payments store in your MSSQL table `crypto_payments` also. Asp.net Table Example
Cloudflare & Mod_Security & other CDN services -
If you use Cloudflare & Mod_Security & other CDN services, please add our server IPs in Whitelist !
Our Server IPs: 188.8.131.52 & 184.108.40.206 and IPv6: 2001:41d0:700:1bd8:d216::1 & 2001:41d0:0700:1bd8::1
Instruction for Cloudflare - screenshot and source (6. Allow the IPs of the services you use to access your website).
Instruction for Mod_Security - http://serversitters.com/mod-security-whitelist-ip.html.
IPN Example -
For example, your user with userID = user26 bought product with orderID = order15620A. Product price was 11.5 USD and user paid in Bitcoins.
If payment received with correct amount, function receive status = 'payment_received'.
If incorrectly paid amount, the system can not recognize user; status = 'payment_received_unrecognised'
A. User Has Made Correct Payment -
Your callback url & IPN function (file NewPayment.cs) receive data -
'user' - user who has made payment, 'order' current order ID,
'amount' = 0.0479166 BTC paid by User (~11.5 USD),
private_key_hash - your private key hash / calculated as hash("sha512", your_gourl_private_key) for validation that data has been sent from Gourl Gateway Server
public static void Main(int paymentId, IPNModel callback, string box_status)
// IPN Function will receive -
paymentId = 1; // record id in your table crypto_payments
"private_key_hash":"d91921eef5d136d5cd22bd5210b4494d417...." // hash("sha512", your_gourl_private_key)
"date":"30 January 2015"
box_status = "cryptobox_newrecord" // or "cryptobox_updated" (description below)
B. User Has Made INCORRECT Payment (wrong amount) -
We use amount value of cryptocoins in the payment box with a small fraction after the decimal point to uniquely identify each of your users individually.
If user pay wrong amount on your internal wallet address, GoUrl Gateway cannot identify that user. You need to process all unrecognised payments manually.
We forward you ALL coins received on your internal wallet address/es including all payments with incorrect amounts (unrecognised payments).
In example below, user paid wrong/incorrect amount in 0.05 BTC to you -
public static void Main(int paymentId, IPNModel callback, string box_status)
// IPN Function will receive (incorrect payment) -
paymentID = 2; // record id in your table crypto_payments
"err":"An incorrect bitcoin amount has been received"
"private_key_hash":"d91921eef5d136d5cd22bd5210b4494d417...." // hash("sha512", your_gourl_private_key)
"date":"30 January 2015"
box_status = "cryptobox_newrecord"; // or "cryptobox_updated" (description below)
Fields in callback -
- paymentID - current record id in the table crypto_payments
- status - 'payment_received' (payment received with correct amount) or 'payment_received_unrecognised'
- err - optional, error description
- private_key_hash - your private key hash for validation that data has been sent from Gourl.io; calculated as hash("sha512", your_gourl_private_key)
- box - your cryptobox id, the same as on gourl.io member page
- boxtype - 'paymentbox' or 'captchabox'
- order - your order id
- user - identifier for every user
- usercountry - your user's location (country), 3 letter ISO country code
- amount - paid cryptocurrency amount
- amountusd - approximate paid amount in USD with exchange rate on datetime of payment made
- coinlabel - cryptocurrency label
- coinname - cryptocurrency name
- addr - your internal wallet address on gourl.io which received this payment
- tx - transaction id
- confirmed - 0 - unconfirmed transaction/payment or 1 - confirmed transaction/payment with 6+ confirmations
- timestamp - transaction timestamp (GMT time)
- date - transaction date (GMT time)
- datetime - transaction datetime (GMT time)
Usually IPN function in NewPayment.cs will automatically appear for each new payment two times -
- a) when a new payment is received, with values: box_status = cryptobox_newrecord, callback[confirmed] = 0.
- b) and a second time when existing payment is confirmed (6+ confirmations) with values:
box_status = cryptobox_updated, callback[confirmed] = 1. All other values are the same.
But sometimes if the payment notification is delayed for 20-30min (for example, your site was unavailable and GoUrl Gateway auto re-send data later), the payment/transaction will already be confirmed and the function will appear once with values: box_status = cryptobox_newrecord, callback[confirmed] = 1
VI. Testing Environment
You can use 500 free Speedcoins or Dogecoins for testing, create dogecoin/speedcoin payment box.
The minimum account balance on GoUrl.io which our system will automatically transfer from your GoUrl internal wallet address to your external wallet address is 0.01 BTC for Bitcoin, 5 coins for Speedcoin and Dogecoin, etc
Additional actions after a payment has been received (update database records, send email to user, etc). Read here
Speedcoin Demo Box (debug mode activated already) -
Please use it for test your generated MD5 HASH values
- Correct MD5 Hash - live demo
- Incorrect MD5 Hash - live demo
- Speedcoin Demo Box ID: 20116
- Public Key: 20116AA36hi8Speedcoin77SPDPUBjTMX31yIra1IBRssY7yFy
- Private Key: 20116AA36hi8Speedcoin77SPDPRVNOwjzYNqVn4Sn5XOwMI2c
For tests IPN on your local server you can -
- Create bitcoin/dogecoin new payment box for testing
- Fill-in /Views/Test/Index.cshtml file with your data (order ID, User ID, Hash).
- Then display test page in browser and click on the button 'Send OK'; a recognised payment emulation will be sent to your IPN url.
- If you click 'Send NO' an unecognised/wrong amount will be sent.
Instant Payment Notification/Callback JSON Data (examples) -
Extended JSON Data for website (examples) -
We offer Free Support in the integration of our GoUrl Crypto Payment Gateway in your scripts/plugins/website (accepting Bitcoin/Dogecoin/etc payments from users online).
Please feel free to contact us if you have any questions