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

NameTypeDescription

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.

{
  "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 -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"
  }'

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.

Last updated