Alternative Payment Methods using Checkout

Please read this page before starting. The invoice creation API uses several parameters that need explanation.

XGateway supports deposits with preliminary creation of invoices with a fixed exchange rate. This is the recommended integration form, which providers merchants with ready-made UI for deposits with crypto assets.

Creating an invoice

In order to create a Fixed Rate Invoice in the payment processing system, you need to make a POST request to the Invoice API endpoint.

URLs

For tests use Demo env:

https://api.demo.xgateway.tech/api/v2/invoices

For production:

https://api.xgateway.tech/api/v2/invoices

The XGateway provides one API endpoint, which automatically defines a corresponding payment method based on the input parameters provided by the merchant. Below are examples of a payload to create an invoice for various Alternative Payment Methods.

The system will skip all XGateway intermediate pages and redirect the customer directly to the payment method only if all required data is provided.

TRY deposits

For Papara and Havale the amount must be a multiple of 50 (example: 150, 200, 250 TRY etc.)

Create an invoice:

{
    "amount": 150,
    "baseCurrency": "TRY",
    "displayCurrencies": "TRY",
    "customerId": "test-customer-id",
    "orderId": "test-order-id"
}

Create and activate an invoice for Havale (opens the payment method directly):

{
    "customerId": "test-try-customer",
    "orderId": "test-try-order",
    "baseCurrency": "TRY",
    "invoiceStrategy": "fixed",
    "amount": 50,
    "paymentMethod": "bankpay",
    "paymentCurrency": "TRY",
    "customerFullName": "John Doe"
}

Create and activate an invoice for Papara (opens the payment method directly):

{
    "customerId": "test-try-customer",
    "orderId": "test-try-order",
    "baseCurrency": "TRY",
    "invoiceStrategy": "fixed",
    "amount": 50,
    "paymentMethod": "papara",
    "paymentCurrency": "TRY",
    "customerFullName": "John Doe"
}

Curl example

curl -X POST https://api.demo.xgateway.tech/api/v2/invoices \
  -H "x-api-key: 31adcf55-8dea-41b0-b2eb-4b32f0966c6b" \
  -H "Content-Type: application/json" \
  -H "Accept: */*" \
  -d '{ 
"customerId": "test-try-customer",
"orderId": "test-try-order",
"baseCurrency": "TRY",
"amount": 1000,
"paymentMethod": "papara",
"paymentCurrency": "TRY",
"customerFullName": "John Doe"
}'

For Papara and Havale the amount must be a multiple of 50 (example: 150, 200, 250 TRY).

INR deposits

Create an invoice:

{
    "orderId": "order-test-prod",
    "customerId": "test-prod2025",
    "baseCurrency": "INR",
    "amount": 1000
}

Create and activate an invoice for INR (opens the payment method directly):

{    
    "orderId": "order-test-prod",
    "customerId": "test-prod2025",
    "baseCurrency": "INR",
    "amount": 1000,
    "customerFirstName": "John",
    "customerLastName": "Doe",
    "paymentCurrency": "INR",
    "customerEmail": "[email protected]",
    "customerCountry": "AU", // Optional for INR-P3
    "customerPhone": "1234567890" // Must be a 10 digits number. Optional for INR-P3
}

The request returns a link to a correspondingly configured Checkout page.

The Checkout page will request from a customer any data missed in the initial request and required to create an invoice.

The Checkout page will eventually redirect the customer to the local payment system like Papara or UPI.

Remember to authorise the request with your key using x-api-key header.

The default lifetime of an invoice is 15 minutes.

iFrame or redirect

The URL may be used to redirect a user to a new page, where they finish the payment. This can be done using a new tab too. A redirect is an option with less efforts.

When the deposit is done, a user is redirected back to your app to the URLspecified in the redirectUrl parameter.

The invoice URL may also be used in an iFrame. Please check this page for detailed instructions on the iFrame setup.

Limits

The invoice creation API validates the amount value. The minimum and maximum amount values may differ based on the payment provider used for this exact invoice.

Use the following validation as a safe measure. Contact the support team if your currency is not listed or you want to confirm the limits.

An invoice will not be created, if the amount exceeds the limits.

Invoice limits

Currency	Min value	Max value
INR	300 (500 on Sandbox and for exceptional cases in production)	49000
TRY Papara	1000	10000
TRY Havel	100	500000
PKR	500	1000000

Processing a callback

When a customer makes a deposit using a cryptocurrency, XGateway detects the transaction and sends a deposit callback to the merchant. Below is an example of such a callback. For detailed information, please visit this page.

{
   "callbackType":"transaction",
   "amount":"200",
   "applicationId":null,
   "currency":"TRY",
   "customerId":"000394",
   "hash":"...",
   "id":"7e71d132-d80d-4140-8e60-9c89d0bd9eed",
   "invoiceId":"184e9933-1526-...-fe567091b5bd",
   "network":null,
   "orderId":null,
   "status":"confirmed",
   "transactionHash":null,
   "type":"deposit",
   "info":{
      "exchangeRate":"1.03759",
      "referenceAmount":"207.52",
      "referenceCurrency":"USD",
      "referenceExchangeRate":"1.000065",
      "transactionAmount":"207.51518",
      "transactionCurrency":"tUSDT"
   },
   "fees":{
      "processing":"7.263031",
      "technical":null
   },
   "eur":"200.12",
   "usd":"207.52"
}

Confirming a transaction

Due to security risks, merchants must use our API endpoint to request transaction details. XGateway is not liable for issues caused by relying only on callback data.

To confirm the callback is valid, please use the API endpoint.

Testing Alternative Payment Methods deposits on Demo environment

You can test direct crypto deposits in the demo environment.

The easiest option to use is to setup INR account (even if you do not plan to use it) - because we have a partner with stable sandbox in INR. For INR flow, the pages of local payment system, such as UPI, provide a button to simulate a deposit.

For the time being no sandbox is available for TRY. The Demo environment is connected to a separate Papara production instance.

INR testing flow on Demo environment

Open the invoice link. Select the UPI provider.

Proceed up untill the form with a request of transaction information. Input any 12 digits

Send the data. Wait till the system "confirms" the payment.