Creating an Invoice

This endpoint allows you to create a new payment link and receive a URL that can be used to complete the payment. By sending a request to this endpoint with the required parameters, you can generate a payment link for a specific amount and configure various options for the payment process.

POST https://api.oxapay.com/merchants/request

Request Body

Name	Type	Description
merchant*	string	Your merchant API key for authentication and authorization.
amount*	long	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 create invoices in fiat currencies.
callbackUrl	string	The URL where payment information will be sent. Use this to receive notifications about the payment status.
underPaidCover	decimal	Specify the acceptable inaccuracy in payment. Determines the maximum acceptable difference between the requested and paid amount (0-60.00). Default: Merchant setting
feePaidByPayer	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.
lifeTime	integer	Set the expiration time for the payment link in minutes (15-2880). Default: 60.
email	string	Provide the payer's email address for reporting purposes.
orderId	string	Specify a unique order ID for reference in your system.
description	string	Provide order details or any additional information that will be shown in different reports.
returnUrl	string	The URL where the payer will be redirected after a successful payment.

200 The response will contain the following fields

{
  "result": integer, // The result code indicates the outcome of the request. Refer to the Result Code table for more information.
  "message": string, // A message containing additional information about the result of the request.
  "trackId": string, // The unique identifier for the payment session in the OxaPay payment gateway. You can use this track ID to query the payment status and generate reports.
  "payLink": string // The payment page link associated with the generated track ID. This link can be forwarded to the payer to complete the payment.
}

Additional Notes

- If the payer does not submit a transaction within the specified time for payment (lifeTime), the invoice will be expired.

- If the payer sends a lower amount, the payment will not be made.

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

- If the payer makes multiple payments for one invoice, you will receive the first acceptable payment.

Please note that a successful request will return a result code 100 along with the payment track ID and payment link. In case of any issues or validation problems, refer to the corresponding result codes for further details.

This endpoint allows you to generate payment links with specific amounts and configure various options to tailor the payment process according to your requirements.

Example codes

cURL

curl -X POST https://api.oxapay.com/merchants/request \
  -d '{
    "merchant": "YOUR_MERCHANT_API_KEY",
    "amount": 100,
    "currency": "TRX",
    "lifeTime": 30,
    "feePaidByPayer": 0,
    "underPaidCover": 2.5,
    "callbackUrl": "https://example.com/callback",
    "returnUrl": "https://example.com/success",
    "description": "Order #12345",
    "orderId": "ORD-12345",
    "email": "[e-mail]"
  }'

PHP

<?php

$url = 'https://api.oxapay.com/merchants/request';

$data = array(
    'merchant' => 'YOUR_MERCHANT_API_KEY',
    'amount' => 100,
    'currency' => 'TRX',
    'lifeTime' => 30,
    'feePaidByPayer' => 0,
    'underPaidCover' => 2.5,
    'callbackUrl' => 'https://example.com/callback',
    'returnUrl' => 'https://example.com/success',
    'description' => 'Order #12345',
    'orderId' => 'ORD-12345',
    'email' => '[e-mail]'
);

$options = array(
    'http' => array(
        'header' => 'Content-Type: application/json',
        'method'  => 'POST',
        'content' => json_encode($data),
    ),
);

$context  = stream_context_create($options);
$response = file_get_contents($url, false, $context);
$result = json_decode($response);
var_dump($result);
?>

Node.js

const axios = require('axios');
const url = 'https://api.oxapay.com/merchants/request';
const data = JSON.stringify({
    merchant: 'YOUR_MERCHANT_API_KEY',
    amount: 100,
    currency: 'TRX',
    lifeTime: 30,
    feePaidByPayer: 0,
    underPaidCover: 2.5,
    callbackUrl: 'https://example.com/callback',
    returnUrl: 'https://example.com/success',
    description: 'Order #12345',
    orderId: 'ORD-12345',
    email: '[e-mail]'
});

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

Python

import requests
import json

url = 'https://api.oxapay.com/merchants/request'
data = {
    'merchant': 'YOUR_MERCHANT_API_KEY',
    'amount': 100,
    'currency': 'TRX',
    'lifeTime': 30,
    'feePaidByPayer': 0,
    'underPaidCover': 2.5,
    'callbackUrl': 'https://example.com/callback',
    'returnUrl': 'https://example.com/success',
    'description': 'Order #12345',
    'orderId': 'ORD-12345',
    'email': '[e-mail]'
}

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

Please make sure to replace YOUR_MERCHANT_API_KEY in the code snippets with your actual merchant API key, and usd with the appropriate currency symbol.

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