First of all, this tutorial is for education purposes only. Make sure it's legal to use Monero (XMR) in your country. You are responsible for your use of Monero (XMR).
Introduction
What Is Monero (XMR)?
Monero (XMR) is a privacy-focused cryptocurrency that aims to provide secure, untraceable, and private transactions.
Unlike many cryptocurrencies, Monero's blockchain design allows transaction amounts, origins, and destinations to be hidden, providing a higher level of privacy and anonymity for its users. Its emphasis on privacy has led to wide adoption among individuals who prioritize confidentiality.
It is also highly scalable with dynamic blocks so it can accomodate a large volume of transactions per second.
Overview of NOWPayments
NOWPayments is a cryptocurrency payment gateway that enables merchants to accept and process payments in various cryptocurrencies like Bitcoin, Ethereum, and Monero.
The platform offers an API, allowing businesses to accept cryptocurrencies on their websites, catering to a global audience looking to utilize digital assets for purchases or donations.
When using NOWPayments, funds are sent to a wallet you own and control before the checkout process finalized. This ensures you have access to the funds without a third party who can take them from you. For this process, NOWPayments takes a small fee, which is their business model.
Importance and benefits of accepting Monero payments
Monero provides the ability to transact with a merchant in a prviate way that cannot be blocked. As we move into a world of increased financial surveillance, third parties are not only able to block transactions they don't like, but each and every transaction can be used to profile and discriminate upon us.
By allowing an individual to pay in Monero, the source of the funds cannot be known. Unlike other cryptocurrencies like Bitcoin which allow a merchant to know exactly how much crypto you have when you transact with them, Monero keeps sender, receiver and amount hidden.
Integrating Monero payments in a C# project using NOWPayments
While it is possible to accept Monero payments without a third party payment processor, using one is a low cost way to create and manage invoice statuses. The NOWPayments API allows for creating an invoice, an application can then receive call back messages on the status of the invoice and perform business logic once it's paid. A status of "paid" indicates that the funds were sent to your personal wallet but it doesn't mean that it has confirmed on the blockchain. For Monero, that can take 20-30 minutes.
Setting Up NOWPayments Account
Setting up a Monero wallet and getting its address
If you don't have a Monero wallet already, you can create one locally with the Monero.com wallet. When you create a wallet, you will see a mnemonic phrase. This phrase is used to restore your wallet so it's essential that you save this phrase somewhere no one else can access it.
Once your wallet is created, you will be able to get your public key. This key can only be used to send funds to so there is no risk in making it public.
Creating a NOWPayments account
The first step in accepting payments with NOWPayments is to create an account. With this, you can check your dashboard for payments and configure settings.
What you need:
- An email address
- A Monero wallet address (where the funds are sent after an invoice has been paid)
Generating an API Key
To communicate with the NOWPayments API, you will first have to create an API key. This can be done in the "Payment settings" section of your NOWPayments account. Here you can create a new API key which you will use as part of making requests to their API.
IPN Notifications Key
In addition to an API key for sending requests to NOWPayments, you will also need to create an IPN (Instant Payment Notifications) secret key. This key is used so that when a request from NOWPayments is received in your application. It allows you to know the request is associated with your account.
You need to receive notifications from NOWPayments on the status of an invoice in the case someone pays an invoice and exits the page. The notifications allow you to see the status of the invoice every step along the way, for example when payment has been received, when it's confirming on the blockchain and when the funds are being sent to your wallet.
Preparing Your C# Project
Setting up a new C# project or using an existing one
When creating code to work with NOWPayments, it is best to put it in its own project. This way, interfaces can be made that can be swapped out for another payment processor if need be.
Installing necessary libraries and dependencies
The only NuGet package that will be required to work with NOWPayments is "Newtonsoft.Json". By using it, you can convert your request and response objects from JSON to and from your C# classses.
Integration Process
Initializing NOWPayments API client with your API Key
The NOWPayments API key goes into a header field called "x-api-key". When you create your HttpClient, you need to add a header which sets this value to your key.
When constructing a NOWPayements API client, it is best to create a model which can encapsulate all of the needed settings. These include: the API key, the IPN secret key, a URL to redirect a person to once they've paid and a call back URL for payment notifications.
Creating a payment request with Monero
First, you will need a model which represents your payment request.
Once you have that, you can submit your payment request to the invoice API.
You call the invoice API with your payment request. The amount you want paid must be specified in an allowed fiat currency like US Dollars. You cannot request to paid a specific amount in Monero.
Your request will return an invoice response, which you can convert into your own response object.
Handling the response and checking the payment status
If your response is successful, then you will get back a URL in the "invoice_url" field. This is the destination to send your customer to. On this page will be a Monero QR code of the address, the raw address string and the amount to pay in Monero.
The buyer simply needs to scan the code and enter the amount. Once the payment has been sent, NOWPayments will begin reporting on its status on the blockchain and it being sent to your personal wallet.
There are two IDs to keep track of in the workflow. The first is your own Order ID, created in your system and used to reference in NOWPayments. The second is Payment ID, created in NOWPayment's system and used to reference the invoice in their system. The Payment ID is returned once you create an invoice.
IPN Notifications
Authenticating the request
Once an invoice has been created, you will begin receiving notifications on it as its status changes. To enable this, you need a controller action which can receive a request. When it receives a request, you will need to validate it so that you can trust the data is coming from NOWPayments.
Processing the request
Once you validate the request, you can get the IPN payment message and convert that into your own object.
Once you have the response, you can get the "order_id" out of it. This value is one you passed to NOWPayments when you created the invoice. From here, you can look up the invoice in your system and perform any business logic you want based on the "payment_status".
Within NOWPayments, you can set their system to repeat the IPN payment message. It can be sent, for example, every 1 minute up to 10 times. This way, if your server restarts, it can come back online and get one of the messages. You can also manually force an invoice to send the IPN message within their portal.
Payment Statuses
These are the possible statuses that an invoice can be in when using NOWPayments.
Error Handling
Common errors and exceptions
Your request or response may have some problems. For this reason, you will want to have some type of logging in place such as Serilog. You can log the raw request you receive to ensure the JSON is being dealt with correctly.
How to handle them in your C# code
Since you cannot have the IPN messages go to your localhost without some kind of proxy or routing, using a live endpoint with logging is one of the best ways to see what messages NOWPayments is sending you.
Testing Your Integration
Creating test payments
Due to the complexity of blockchains, you will want to run tests with live data. In doing so, you will need to use real Monero. Unfortunately, you will have to use payments greater than $1 USD. Micropayments, such as those less than that, will be rejected by the API for being too small.
It is best to have a seperate way to store invoices from orders. A person can create an invoice that doesn't get paid or gets into a bad state such as overpaid, underpaid or out of range of time for the quoted rate. By only creating an order when an invoice is paid, you can better isolate test data and data from people who don't pay from your actual orders.
Validating the payment process
When testing, you should be able to create an pay an invoice. If you have supplied a success URL page, the user will be redirected to it with the query string "NP_id" in the URL. This is a value you received from NOWPayments when you created an invoice. It can be used as another way to look up an invoice in your system and mark the invoice as paid. It is the "payment_id" which can be used to query the payment status.
Security Best Practices
Ensuring the secure handling of API keys and Monero wallet information
It is best to store the API keys in a secure place such as the database or the appsettings.json file. Do not hard code the keys anywhere, especially if your code is open source.
Other security considerations for cryptocurrency payments
Always make sure that the seed phrase of the wallet which stores your funds is in a safe place. Anyone with the seed phrase can control the funds in the wallet.
Use Case For Monero Payments
I created Monerica, a directory for a circular Monero economy. After receiving lots of traffic on the site due to a YouTube video on it, I decided to allow sponsored directory listings. A user can go to the directory without an account, select a listing to sponsor, and pay for it in Monero.
In this way, I have created a privacy focused advertising platform. A user's sponsored listing can go live immediately once they are redirected to the success page. If they leave the page after paying, I can receive a notification that they paid their invoice. From here I can take action to create their live sponsored advertisement.
Conclusion
Recap of steps for integrating Monero payments via NOWPayments
By using NOWPayments, you can create orders for physical or digital products, paid in Monero. NOWPayments deals with all the customer service and your application deals with processing the invoice status.
When an invoice is marked as "paid" in NOWPayments, this means that the funds have been sent to your wallet. From there, you can safely give the user what they paid for.
Other cryptocurrencies and payment options with NOWPayments
While it is possible to accept other cryptocurrencies using NOWPayments, using Monero gives both you and the buyer privacy. If you want to allow other payments, you will have to allow the user to select which currency they want somewhere else along the way. For big e-commerce sites, this may be perferred.
Other Workflows
There are other workflows you may want to make with NOWPayments. For example, instead of creating an invoice, you can create a payment. With this option, the Monero address is returned. In such a scenario, you could keep the customer on your site and just display the address, or generate the QR code for it, on your own.
Where To Sign Up
You can create a free account with NOWPayments here.
