# 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.

<mark style="color:green;">`POST`</mark> `https://api.oxapay.com/merchants/request`

#### Request Body

<table><thead><tr><th width="178">Name</th><th width="98">Type</th><th width="475">Description</th></tr></thead><tbody><tr><td>merchant<mark style="color:red;">*</mark></td><td>string</td><td>Your merchant API key for authentication and authorization.</td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td>long</td><td>The amount for the payment. If the <code>currency</code> 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.</td></tr><tr><td>currency</td><td>string</td><td>Specify the <a href="supported-currencies">currency symbol</a> if you want the invoice amount calculated with a specific currency. You can also create invoices in <a href="supported-fiat-currencies">fiat currencies</a>.</td></tr><tr><td>callbackUrl</td><td>string</td><td>The URL where payment information will be sent. Use this to receive notifications about the payment status.</td></tr><tr><td>underPaidCover</td><td>decimal</td><td><p>Specify the acceptable inaccuracy in payment. Determines the maximum acceptable difference between the requested and paid amount (0-60.00).</p><p><strong>Default:</strong> Merchant setting</p></td></tr><tr><td>feePaidByPayer</td><td>decimal</td><td>Specify whether the payer will cover the invoice commission. <code>1</code> indicates that the payer will pay the fee, while <code>0</code> indicates that the merchant will pay the fee. <strong>Default</strong>: Merchant setting.</td></tr><tr><td>lifeTime</td><td>integer</td><td><p>Set the expiration time for the payment link in minutes (15-2880).</p><p><strong>Default:</strong> 60.</p></td></tr><tr><td>email</td><td>string</td><td>Provide the payer's email address for reporting purposes.</td></tr><tr><td>orderId</td><td>string</td><td>Specify a unique order ID for reference in your system.</td></tr><tr><td>description</td><td>string</td><td>Provide order details or any additional information that will be shown in different reports.</td></tr><tr><td>returnUrl</td><td>string</td><td>The URL where the payer will be redirected after a successful payment.</td></tr></tbody></table>

{% tabs %}
{% tab title="200 The response will contain the following fields" %}

```json
{
  "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.
  "expiredAt": string // The expiration timestamp of the payment link. After this time, the payment link will no longer be valid.
}
```

{% endtab %}
{% endtabs %}

### Additional Notes

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

\- 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](https://docs.oxapay.com/legacy/api-reference/result-code-table) 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

{% tabs %}
{% tab title="cURL" %}

```bash
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": "customer@example.com"
  }'
```

{% endtab %}

{% tab title="PHP" %}

```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' => 'customer@example.com'
);

$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);
?>
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
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: 'customer@example.com'
});

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

{% endtab %}

{% tab title="Python" %}

```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': 'customer@example.com'
}

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

{% endtab %}
{% endtabs %}

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.

<br>