Generate Invoice

This endpoint enables you to generate a new invoice and obtain a payment URL for completing the transaction. By providing the required parameters in your request, you can specify the invoice amount and customize various options for the payment process.

POST https://api.oxapay.com/v1/payment/invoice

Authentication

You must include the Merchant API Key in the request header to authenticate your access to the API.

Name	Type	Description
merchant_api_key*	string	Your merchant API Key for authentication and authorization.

Request Body

Name	Type	Description
amount*	decimal	The amount for the payment. If the currency field is not filled, the amount should be specified in dollars. If the `currency` field is filled, the amount should correspond to the specified currency.
currency	string	Specify the currency symbol if you want the invoice amount calculated with a specific currency. You can also generate invoices in fiat currencies.
lifetime	integer	Set the expiration time for the payment link in minutes (15-2880). Default: 60.
fee_paid_by_payer	decimal	Specify whether the payer will cover the invoice commission. 1 indicates that the payer will pay the fee, while 0 indicates that the merchant will pay the fee. Default: Merchant setting.
under_paid_coverage	decimal	Specify the acceptable inaccuracy in payment. Determines the maximum acceptable difference between the requested and paid amount (0-60.00). Default: Merchant setting
to_currency	string	The currency symbol of the cryptocurrency you want to convert to. You only can convert paid crypto currencies to USDT.
auto_withdrawal	boolean	1 indicates that the received currency will be sent to the address specified in your Address List on the Settings page and 0 indicates that the amount will be credited to your OxaPay balance.
mixed_payment	boolean	Specify whether the payer can cover the remaining amount with another currency if they pay less than the invoice amount. 1 allows the user to pay the remainder with a different coin, while 0 doesn't allow it. Default: Merchant setting.
callback_url	string	The URL where payment information will be sent. Use this to receive notifications about the payment status.
return_url	string	The URL where the payer will be redirected after a successful payment.
email	string	Provide the payer's email address for reporting purposes.
order_id	string	Specify a unique order ID for reference in your system.
thanks_message	string	A thanks message that brief note displayed to the payer after a successful payment.
description	string	Provide order details or any additional information that will be shown in different reports.
sandbox	boolean	The sandbox field is a boolean that specifies whether the API request should operate in sandbox mode (test environment). Set it to true for testing and false for live transactions.

200 OK

{
    "data": {
        "track_id": string, // Unique identifier for the payment session in the OxaPay gateway. It is used to track the payment status, query details, and generate reports.
        "payment_url": string, // The URL of the payment page linked to the track ID. This link is shared with the payer to complete the payment process.
        "expired_at": integer, // The expiration timestamp (UNIX epoch) of the payment link. After this time, the link becomes invalid.
        "date": integer // The creation timestamp (UNIX epoch) of the payment session.
    },
    "message": string,  // A message containing additional information about the result of the request.
    "error": {
        "type": string, 
        "key": string, 
        "message": string 
    } || {}, // An object that provides details about any errors that occurred.
    "status": integer, // The status of the request response. Typically provided as a numeric code (e.g., 200 for success or other codes for errors).
    "version": string // The version of the API being used.
}

If the payer sends the exact amount or a higher amount, you will receive the paid amount.

Please note that a successful request will return status 200. In case of any issues or validation problems, refer to the corresponding error for further details.

API Request Sample Codes

cURL

curl -X POST https://api.oxapay.com/v1/payment/invoice \
  -H "merchant_api_key: YOUR_MERCHANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "USD",
    "lifetime": 30,
    "fee_paid_by_payer": 1,
    "under_paid_coverage": 2.5,
    "to_currency": "USDT",
    "auto_withdrawal": false,
    "mixed_payment": true,
    "callback_url": "https://example.com/callback",
    "return_url": "https://example.com/success",
    "email": "[e-mail]",
    "order_id": "ORD-12345",
    "thanks_message": "Thanks message",
    "description": "Order #12345",
    "sandbox": false
  }'

PHP

<?php

$url = 'https://api.oxapay.com/v1/payment/invoice';

$data = [
    "amount" => 100,
    "currency" => "USD",
    "lifetime" => 30,
    "fee_paid_by_payer" => 1,
    "under_paid_coverage" => 2.5,
    "to_currency" => "USDT",
    "auto_withdrawal" => false,
    "mixed_payment" => true,
    "callback_url" => "https://example.com/callback",
    "return_url" => "https://example.com/success",
    "email" => "[e-mail]",
    "order_id" => "ORD-12345",
    "thanks_message" => "Thanks message",
    "description" => "Order #12345",
    "sandbox" => false
];

$headers = [
    'Content-Type: application/json',
    'merchant_api_key: YOUR_MERCHANT_API_KEY'
];

$options = array(
    'http' => array(
        'header'  => implode("\r\n", $headers),
        'method'  => 'POST',
        'content' => json_encode($data),
    ),
);

$context  = stream_context_create($options);
$response = file_get_contents($url, false, $context);
if ($response === FALSE) {
    die('Error occurred');
}
$result = json_decode($response, true);
var_dump($result);
?>

Node.js

const axios = require('axios');

const url = 'https://api.oxapay.com/v1/payment/invoice';

const data = {
    amount: 100,
    currency: "USD",
    lifetime: 30,
    fee_paid_by_payer: 1,
    under_paid_coverage: 2.5,
    to_currency: "USDT",
    auto_withdrawal: false,
    mixed_payment: true,
    callback_url: "https://example.com/callback",
    return_url: "https://example.com/success",
    email: "[e-mail]",
    order_id: "ORD-12345",
    thanks_message: "Thanks message",
    description: "Order #12345",
    sandbox: false
};

const headers = {
  'merchant_api_key': `YOUR_MERCHANT_API_KEY`,
  'Content-Type': 'application/json',
};

axios.post(url, data, { headers })
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error(error);
  });

Python

import requests
import json

url = 'https://api.oxapay.com/v1/payment/invoice'

data = {
    "amount": 100,
    "currency": "USD",
    "lifetime": 30,
    "fee_paid_by_payer": 1,
    "under_paid_coverage": 2.5,
    "to_currency": "USDT",
    "auto_withdrawal": False,
    "mixed_payment": True,
    "callback_url": "https://example.com/callback",
    "return_url": "https://example.com/success",
    "email": "[e-mail]",
    "order_id": "ORD-12345",
    "thanks_message": "Thanks message",
    "description": "Order #12345",
    "sandbox": False
}

headers = {
    'merchant_api_key': 'YOUR_MERCHANT_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.post(url, data=json.dumps(data), headers=headers)
result = response.json()
print(result)

Please make sure to replace YOUR_MERCHANT_API_KEY in the code snippets with your actual merchant API Key.

These example code snippets demonstrate how to request the "Generate Invoice" endpoint using different programming languages. You can customize the data parameters according to your specific requirements.

API Response Example

{
    "data": {
        "track_id": "184747701",
        "payment_url": "http://pay.oxapay.com/12373985/184747701",
        "expired_at": 1734546589,
        "date": 1734510589
    },
    "message": "Operation completed successfully!",
    "error": {},
    "status": 200,
    "version": "1.0.0"
}

The response example above is provided to help you understand the format and structure of the response. If you have any further questions or need assistance, please feel free to contact to your account manager.