OxaPay Documentation
Search
⌃K

Merchants (Payment gateway)

How to setup OxaPay crypto Gateway?

OxaPay crypto gateway is usable for online business websites, telegram bots, software, applications and etc. Using and setting up the OxaPay crypto payment gateway service is not complicated. Just follow the three steps below:
OxaPay needs your order information to set up your gateway, which can be sent through this endpoint. If the parameters are sent correctly, you will receive trackId as the payment tracking ID in response to this endpoint.
By sending the generated trackId in the previous step to this endpoint, the payment page will appear for you and you are ready to pay.
OxaPay sends the payment status of each order to the callback URL (you have registered it for your merchant). After that, you need to call the transaction confirmation method. It is possible to confirm the successful payment through this endpoint.
If you need to receive information and transaction status in any of the payment steps, by calling this endpoint, you will receive the full details of the desired transaction.
By following the mentioned steps, the payment process of the order ends. The deposit amount will be deposited to your OxaPay wallet through the payment gateway.

Validation

OxaPay uses the merchant parameter to validate the available gateways. After creating each new gateway, this information is available in the OxaPay user panel. All requests sent to OxaPay must contain authentication information:
You can use oxapay as merchant field in all requests to test the payment service.
{
"merchant": "oxapay",
// OTHER FIELDS
}

Payment request (Request)

Use this endpoint to send order information and register it in the OxaPay system.
post
https://api.oxapay.com
/merchants/request
Parameters
Body
merchant*
String
Require for authentication
amount*
Long
Total amount (as dollar if currency filed was not filled. Otherwise amount should be filled with your specified currency amount)
callbackUrl*
String
Payment informations will be sent to this URL
currency
String
If you want that your invoice to be paid by a specified currency fill in this field with its symbol (Find the list of currencies symbol in the accepted coins section)
description
String
Order details (will be shown in different reports)
orderId
String
Your unique order ID (optional - used in reports)
email
String
User's email for report
Responses
200: OK
Successful operation
Sample JSON you sent to this endpoint
{
"merchant": "oxapay",
"amount": 22.22,
"callbackUrl": "https://www.site.com/yourCallback",
"description": "Hello World!",
"orderId": "AB-1122",
"email": "[email protected]"
}
Sample JSON response from OxaPay for this endpoint
{
"result": 100,
"message": "success",
"trackId": 7423199,
"payLink": "https://oxapay.com/mpay/7423199"
}

Result table

100
Successful operation
102
Validating problem - refer to the validation section
103
Invalid merchant
104
Inactive merchant
105
Amount is less than the acceptable amount
106
Amount is more than the acceptable amount
107
Currency is not acceptable or was sent wrong
108
callbackUrl not entered or entered incorrectly

Sample code

php
Node.js
Python
<?php
​
define('OXAPAY_MERCHANT_KEY', 'YOUR-MERCHANT-KEY');
​
function oxapayRequest($path, $params)
{
$url = 'https://oxapay.com/merchants/'.$path;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = curl_exec($ch);
curl_close($ch);
return json_decode($res);
}
​
$params = array(
'merchant' => OXAPAY_MERCHANT_KEY, //required
'amount' => 12.12, //required, usd
'callbackUrl' => 'https://www.site.com/yourCallback' //required
'description' => 'Hello World!', //optional
'orderId' => 'AB-1122', //optional
'email' => '[email protected]', //optional
);
​
$res = oxapayRequest('request', $params);
if ($res->result == 100)
{
// store $res->trackId and redirect to $res->payLink url
}
else{
echo "errorCode: ".$res->result."<br>";
echo "message: ".$res->message;
}
​
?>
var request = require('request-promise');
var params = {
merchant: "YOUR-MERCHANT-KEY",
amount: 22.22,
callbackUrl: "https://www.site.com/yourCallback",
description: "Hello World!",
orderId: "AB-1122",
email: "[email protected]"
};
var options = {
method: "POST",
url: "https://api.oxapay.com/merchants/request",
headers: {
'cache-control': 'no-cache',
'content-type': 'application/json'
},
body: params,
json: true
};
request(options)
.then(function (res) {
if (res.result == 100) {
// store res.trackId and redirect to res.payLink url
}
})
import requests
​
params = {
'merchant': 'oxapay',
'amount': 22.22,
'callbackUrl': "http://localhost:3333/callback",
'description': "Hello World!",
'orderId': "ORD-1122",
'email': "[email protected]",
}
url = "https://api.oxapay.com/merchants/request"
response = requests.post(url = url, json= params)
​
res = response.json()
if res['result'] == 100:
# store res['trackId'] and redirect to res['payLink'] urlth

Payment start (mpay)

Use this endpoint to display the payment page and start paying.
get
https://oxapay.com
/mpay/{{trackId}}
By sending the trackId to the above address and opening this page in the browser, you will be transferred to the OxaPay payment page.
Parameters
No parameters
Responses

Callback

OxaPay sends the payment information to the entered callbackUrl in your request when the status changes.
This information is sent as Query String and through the GET method for callbackUrl.
To end the payment session of an order, if the payment is successful, be sure to confirm the received information through the payment confirmation gateway.

Callback body

success
1 for the successful transaction, 0 otherwise.
trackId
Payment session tracking ID
orderId
Order ID sent when payment request (if sent in request endpoint)
status
Payment status (you can check the status parameters through the status table)
The called callback example
https://site.com/yourcallback?trackId=7423199&success=1&status=2&orderId=AB-1122

Payment verification (Verify)

Use this endpoint to confirm successful payment and end a payment session.
As mentioned earlier, OxaPay notifies you of the status of payment by sending payment information to the registered callbackUrl. This endpoint is installed to ensure that you receive this information and complete the order payment process.
post
https://api.oxapay.com
/merchants/verify
Parameters
Body
merchant*
String
Require for authentication
trackId*
Long
The ID of the payment session you want to confirm
Responses
200: OK
Successful operation
Sample JSON you sent to this endpoint
{
"merchant": "oxapay",
"trackId": 7423199
}
Sample JSON response from OxaPay for this endpoint
{
"paidAt": "2023-01-10T13:23:01",
"amount": 22.22,
"result": 100,
"status": 1,
"message": "success"
}

Result table

100
Successful operation
102
Validating problem - refer to the validation section
103
Invalid merchant
104
Inactive merchant
201
Already approved
202
The order has not been paid or has failed. Read the status table for more information.
203
Invalid trackId

Sample code

php
Node.js
Python
<?php
​
define('OXAPAY_MERCHANT_KEY', 'YOUR-MERCHANT-KEY');
​
function oxapayRequest($path, $params)
{
$url = 'https://oxapay.com/merchants/'.$path;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = curl_exec($ch);
curl_close($ch);
return json_decode($res);
}
​
if($_GET['success']==1) {
//start verfication
$params = array(
'merchant' => OXAPAY_MERCHANT_KEY, //required
'trackId' => $_GET['trackId'], //required
);
​
$res = oxapayRequest('verify', $params);
if ($res->result == 100) {
var_dump($res);
// store $res->transaction data
}
else{
echo "errorCode: ".$res->result."<br>";
echo "message: ".$res->message;
}
}else{
echo "The order has not been paid or has failed";
}
?>
var express = require("express");
var request = require('request-promise');
​
var app = express();
​
app.listen(3333, () => {
console.log("Server running on port 3333");
});
​
app.get("/callback", (req, res) => {
​
// store order status here
​
res.json({ result: 100, message: "success" })
if (req.query.success == '1' && req.query.status == '2') {
var params = {
merchant: "YOUR-MERCHANT-KEY",
trackId: req.query.trackId
};
var options = {
method: "POST",
url: "https://api.oxapay.com/merchants/verify",
headers: {
'cache-control': 'no-cache',
'content-type': 'application/json'
},
body: params,
json: true
};
request(options)
.then(function (res) {
if (res.result == 100) {
// store res.transaction data
}
})
}
})
from http.server import BaseHTTPRequestHandler, HTTPServer
import urllib
import requests
​
class Server(BaseHTTPRequestHandler):
def do_GET(self):
self.send_response(200)
self.send_header('Content-type', 'application/json')
self.end_headers()
req = dict(urllib.parse.parse_qsl(urllib.parse.urlparse(self.path).query))
print(req)
if req["success"] == '1' and req["status"] == '2':
params = {
'merchant': "YOUR-MERCHANT-KEY",
'trackId': req["trackId"]
}
url = "https://api.oxapay.com/merchants/verify"
response = requests.post(url = url, json= params)
res = response.json()
if res['result'] == 100:
# store res['transaction'] data
​
​
def run(server_class=HTTPServer, handler_class=Server, port=3333):
server_address = ('', port)
httpd = server_class(server_address, handler_class)
print('Starting httpd on port %d...' % port)
httpd.serve_forever()
if name == "__main__":
from sys import argv
if len(argv) == 2:
run(port=int(argv[1]))
else:
run()

Payment inquiry (Inquiry)

Use this endpoint to inquire about payment and receive a report of a payment session.
post
https://api.oxapay.com
/merchants/inquiry
Parameters
Body
merchant*
String
Require for authentication
trackId*
Long
The ID of the payment session you want to get its report
Responses
200: OK
Successful operation
Sample JSON you sent to this endpoint
{
"merchant": "oxapay",
"trackId": 7423199
}
Sample JSON response from OxaPay for this endpoint
{
"message": "success",
"result": 100,
"paidAt": "2023-01-10T13:23:01",
"verifiedAt": "2023-01-10T13:25:43",
"status": 1,
"amount": 22.22,
"orderId": "AB-1122",
"description": "Hello World !",
"email": "[email protected]",
"wage": 0,
"createdAt": "2023-01-10T13:06:21",
"transaction": {
"coin": "trx", // Paid currency symbol
"amount": 409.04, // paid currency amount
"txId": "xxx", // Paid transaction hash
}
}

Result table

100
Successful operation
102
Validating problem - refer to the validation section
103
Invalid merchant
104
Inactive merchant
203
Invalid trackId

Sample code

php
Node.js
Python
<?php
​
define('OXAPAY_MERCHANT_KEY', 'YOUR-MERCHANT-KEY');
​
function oxapayRequest($path, $params)
{
$url = 'https://oxapay.com/merchants/'.$path;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = curl_exec($ch);
curl_close($ch);
return json_decode($res);
}
​
$params = array(
'merchant' => OXAPAY_MERCHANT_KEY, //required
'trackId' => YOUR-PAYMENT-REQUEST-TRACKID, //required
);
$res = oxapayRequest('inquiry', $params);
if ($res->result == 100)
{
var_dump($res);
//{"result":100,"message":"success","createdAt":"2023-01-08T00:26:46+00:00","paidAt":"2023-01-08T02:28:36+00:00","amount":1,"status":2,"wage":"0","description":"test","orderId":"AB-12345","email":"[email protected]","transaction":{"coin":"trx","txId":"txhash","amount":20}}
}
else{
echo "errorCode: ".$res->result."<br>";
echo "message: ".$res->message;
}
​
?>
var request = require('request-promise');
var params = {
merchant: "YOUR-MERCHANT-KEY",
trackId: YOUR-PAYMENT-REQUEST-TRACKID
};
var options = {
method: "POST",
url: "https://api.oxapay.com/merchants/inquiry",
headers: {
'cache-control': 'no-cache',
'content-type': 'application/json'
},
body: params,
json: true
};
request(options)
.then(function (res) {
if (res.result == 100) {
// store order status and res.transaction data
}
})
import requests
​
params = {
'merchant': "YOUR-MERCHANT-KEY",
'trackId': YOUR-PAYMENT-REQUEST-TRACKID
}
url = "https://api.oxapay.com/merchants/inquiry"
response = requests.post(url = url, json= params)
res = response.json()
if res['result'] == 100:
# store res['transaction'] data

Accepted coins

Use this endpoint to get the list of your merchant's accepted coins.
post
https://api.oxapay.com
/merchants/allowedCoins
Parameters
Body
merchant*
String
Require for authentication
Responses
200: OK
Successful operation
Sample JSON you sent to this endpoint
{
"merchant": "oxapay"
}
Sample JSON response from OxaPay for this endpoint
{
"result": 100,
"message": "success",
"allowed": ['btc', 'eth', 'bnb', 'usdt(trc20)', 'usdt(erc20)']
}

Result table

100
Successful operation
102
Validating problem - refer to the validation section
103
Invalid merchant
104
Inactive merchant

Sample code

php
Node.js
Python
<?php
​
define('OXAPAY_MERCHANT_KEY', 'YOUR-MERCHANT-KEY');
​
function oxapayRequest($path, $params)
{
$url = 'https://oxapay.com/merchants/'.$path;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = curl_exec($ch);
curl_close($ch);
return json_decode($res);
}
​
$params = array(
'merchant' => OXAPAY_MERCHANT_KEY, //required
);
$res = oxapayRequest('allowedCoins', $params);
if ($res->result == 100)
{
var_dump($res);
//{"result":100,"message":"success","allowed":["btc","eth","ltc","bnb","trx","usdt(trc20)","usdt(erc20)"]}
}
else{
echo "errorCode: ".$res->result."<br>";
echo "message: ".$res->message;
}
​
?>
var request = require('request-promise');
var params = {
merchant: "YOUR-MERCHANT-KEY",
};
var options = {
method: "GET",
url: "https://api.oxapay.com/merchants/allowedCoins",
headers: {
'cache-control': 'no-cache',
'content-type': 'application/json'
},
body: params,
json: true
};
request(options)
.then(function (res) {
if (res.result == 100) {
// store res.allowed array
}
})
import requests
​
params = {
'merchant': "YOUR-MERCHANT-KEY"
}
url = "https://api.oxapay.com/merchants/allowedCoins"
response = requests.post(url = url, json= params)
res = response.json()
if res['result'] == 100:
# store res['allowed'] array

Transactions status table

-3
Canceled by the user
-2
Unsuccessful payment
-1
Payment pending
1
Paid, verified
2
Paid, Not verified
Previous
Telegram Channel Gateway
Next
Plugins
Last modified now