Documentation
#1 Introduction
1.1. What is NaftyPay?
NaftyPay is a platform for accepting payments with the NAFTY token on the Binance Smart Chain. Anyone who wishes to accept payments with NAFTY can register and add their websites.
1.2. How can i start using NaftyPay to accept payments?
In order to do so, you must register and be approved from an administrator.
1.3. How NaftyPay works?
The payment lifecycle is simple and well known from many other payment providers:
- You create a payment order for a product, subscription or anything else you wish to sell on your website.
- Next you need to make a request to the NaftyPay API containing atleast the required params from 3.3. Payment section.
- If all is good, NaftyPay will return a successfull response, containing the URL for the payment. You need to redirect the user to it.
- The user then finishes the payment. When we validate the payment, you will receive a ping to the provided domain url ping address, containing data about the payment ( See at section 4. API Pings )
At this point you should verify the users order and return a response for the NaftyPay API to know that everything went well. Acceptable responses are "OK" or 1.
#2 Integration
2.1. Payment API
NaftyPay's HTTP API that can be easily integrated into any website, regardless of the plaform and programming languages used. The API methods are accessible through HTTP POST requests.
2.2. API Key
The Api key is required for making requests to the payment API. After registration and account approval, you can generate your API key here. In order to access the API you must provide your API key as a custom header to the request "X-NPK : YOUR_API_KEY".
If you think your API key has been compromised you can regenerate it as many times as you need.
2.3. Site
After adding a site, a domain_id and secret will be generated in the site preview page. You need both to make payments for your website, in order to generate the security signature.
#3 API Methods
The API endpoint is https://naftypay.com/api/v1/METHOD and accepts HTTP POST requests that contain the mandatory API KEY provided as a X-NPK Header. For example "X-NPK: YOUR_API_KEY".
3.1. Ping
This method is used for test purposes.
URL:
https://naftypay.com/api/v1/ping
cURL Example:
curl -H "X-NPK: YOUR_API_KEY" -X POST https://naftypay.com/api/v1/ping
Params:
none
Response:
{"data":"Pong","status":"success","message":"Ping successful"}
3.2. Rate
Get the current NAFTY rate.
URL:
https://naftypay.com/api/v1/rate
cURL Example:
curl -H "X-NPK: YOUR_API_KEY" -X POST https://naftypay.com/api/v1/rate
Response:
{"data":"0.00123456","status":"success","message":"NAFTY to USDT exchange rates"}
Params:
Param | Type | Required | Info |
---|---|---|---|
chain_id | int | Optional | Network Chain ID : Ethereum Mainnet - 1, BSC Mainnet - 56, BSC Testnet - 97. Defaults to BSC Mainnet. |
symbol | string | Optional | Token symbol on the selected chain. Defaults to NAFTY on BSC Mainnet and BNB/ETH on other. |
3.3. Payment
This is the most important method used for creating real payments in NAFTY.
URL:
https://naftypay.com/api/v1/payment
cURL Example:
curl -d "name=SomeName&desc=MoreInfo&amount=10.50&order_id=1000&redirect_url=https://yoursite.com/order/1000&domain_id=qGq1sMUxMR12sOY4&signature=5ee735dfdf8bd4b75732a47258ed6db77287011c7345a734fc4f55db31e50ecf296f58bb9a64fdeaf4c1dd282a0248806ce7bf720b89d310c61dbd3bfcbb587a" -H "X-NPK: YOUR_API_KEY" -X POST https://naftypay.com/api/v1/payment
Response OK:
{"data":"https://naftypay.com/payment/dhIcMh3ZkyP8808WFDWoiw1pM6ECshpO5bpczUdz","status":"success","message":""}
Response ERROR:
{"status":"error","message":"Invalid signature"} - Invalid signature example.
Params:
Param | Type | Required | Info |
---|---|---|---|
name | string | Optional | What you are selling ( product, subscription etc. ) ( Optional ) |
desc | string | Optional | More info on what you are selling |
amount | float | Required | The amount of the order. Defaults for USD, example : 9.99 |
currency | string | Optional | CRYPTO or USD. Default is USD. If crypto is selected, the token currency will be used for the amount. |
order_id | string | Required | Identifier for your order. You will receive this ID on succesful or failed payment |
chain_id | int | Optional | Network Chain ID : Ethereum Mainnet - 1, BSC Mainnet - 56, BSC Testnet - 97. Defaults to BSC Mainnet. |
symbol | string | Optional | Token symbol on the selected chain. Defaults to NAFTY. |
redirect_url | string | Optional | We will provide this url for the user to get back to your website on finished payment ( succesfull or failed ). Full url, including protocol. |
domain_id | string | Required | Domain ID from the site page in naftypay.com. |
signature | string | Required | Sha512 hash used for validating payment requests. |
The signature param is a SHA512 hash of your domain ID, secret and order ID, separated by "|" : "YOUR_DOMAIN_ID|DOMAIN_SECRET|ORDER_ID"
3.4. Test Payment
3.5. Recurring Payment
Create a recurring payment for an order.
URL:
https://naftypay.com/api/v1/rc-payment
cURL Example:
curl -d "name=SomeName&desc=MoreInfo&amount=10.50&order_id=1000&redirect_url=https://yoursite.com/order/1000&domain_id=qGq1sMUxMR12sOY4&signature=5ee735dfdf8bd4b75732a47258ed6db77287011c7345a734fc4f55db31e50ecf296f58bb9a64fdeaf4c1dd282a0248806ce7bf720b89d310c61dbd3bfcbb587a" -H "X-NPK: YOUR_API_KEY" -X POST https://naftypay.com/api/v1/rc-payment
Response OK:
{"data":"https://naftypay.com/payment/rc/dhIcMh3ZkyP8808WFDWoiw1pM6ECshpO5bpczUdz","status":"success","message":""}
Response ERROR:
{"status":"error","message":"Invalid signature"} - Invalid signature example.
Params:
Param | Type | Required | Info |
---|---|---|---|
name | string | Optional | What you are selling ( product, subscription etc. ) ( Optional ) |
desc | string | Optional | More info on what you are selling |
amount | float | Required | The amount of the order in USD |
type | string | Optional | Recurring type - daily, weekly or monthly. Defaults to monthly |
order_id | string | Required | Identifier for your order. You will receive this ID on succesful or failed payment |
trial_period | int | Optional | Number of days before the first pull from the user wallet. If not set, the first pull well be a few minutes after approval. |
user_email | string | Optional | On successfull pulls from the user account we will try to send an email with the pull details, if this param is provided. |
redirect_url | string | Optional | We will provide this url for the user to get back to your website on finished payment ( succesfull or failed ). Full url, including protocol. |
domain_id | string | Required | Domain ID from the site page in naftypay.com. |
signature | string | Required | Sha512 hash used for validating payment requests. |
#4 API Pings
4.1 Payment pings
When a user successfully pays or fails to do so, we will ping ( HTTP POST request ) the provided URL PING for your website. You will receive this ping for payments, test payments and when a successful recurring payment occures. The request parameters are:
Param | Type | Info |
---|---|---|
type | string : 'payment' | Ping type - payment or event. |
order_id | string | Order ID provided by you on the payment request |
amount_usd | float | Payment amount in USD. Minimum amount is $0.10 |
amount | float | Payment amount in CRYPTO. (*Changed from amount_nafty). |
rate | float | Selected crypto rate at order create time(*Changed from nafty_rate). |
symbol | string | Crypto symbol ("NAFTY","BNB","ETH").(*New field) |
txn_id | string or null | Transaction hash of the payment. Value is null if TXN hash is not available. |
status | int | Payment status - 1 = SUCCESS, 2 = FAILED |
status_code | int | A number for more detailed preview of what happend. 1 = OK, 40,41... Error codes. |
4.2 Event pings
When you create a recurring payment for an order, you will be receiving event pings that will provide information to your platform about the users actions. There are currently 4 events that could happen and would be valuable for you to catch.
Ping request parameters
Param | Type | Info |
---|---|---|
type | string : 'event' | Ping type - payment or event. |
event | string | Possible events : approved, failed, expired, terminated, canceled |
order_id | string | Order ID provided by you on the payment request |
amount_usd | float | Payment amount in USD. Minimum amount is $0.10 |
Event types
Event | Info |
---|---|
approved | This event occures when the user approves NaftyPay as a spender to their NAFTY tokens in order to start the recurring payments. The user has not made a payment, our system will create the first payment on the due date - if a traial period has been specified or in a few minutes if not. |
expired | If a user fails to approve the payment for more than 30 min we will mark the payment as faild and send this event. |
failed | We have made an attempt to pull Nafty from the user addres but the request has failed. Most likely approved allowance was removed or insufficient balance. The recurring payment is not marked as failed yet and we will try to pull the amount the next day. If it fails 3 times, the payment is marked as failed (terminated ). |
terminated | The maximum amount of payment attempts has been reached and all have failed. Payment has been terminated. |
canceled | The user has manually canceled the recurring payment subscription. |