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.

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

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",
    "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",
    "amount": 50,
    "paymentMethod": "papara",
    "paymentCurrency": "TRY",
    "customerFullName": "John Doe"
}

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

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

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

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

If you get a bad request response without exact information about the erroneous field, please check the syntax of the request.

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

If you get a bad request response without exact information about the erroneous field, please check the syntax of the request.

INR Peer to Peer 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
}

If you get a bad request response without exact information about the erroneous field, please check the syntax of the request.

INR UPI Intent deposits

NOTE: Intents method is not currently available on Demo Environment due to specifics of the APM.

Create an invoice:

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

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

{    
    "paymentMethod": "intent",
    "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
}

If you get a bad request response without exact information about the erroneous field, please check the syntax of the request.

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 returned by the invoice creation API can be used in two ways: as a redirect or within an iFrame.

In case of a redirect, the user is sent to a new page where they complete the payment. This can be done using a new tab too. A redirect is an option with less effort. When the deposit is done, the user is redirected back to your app: either to the dynamic URL specified in the redirectUrl parameter or to a pre-set static URL.

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

Our local partners for Alternative Payment Methods may block customers using VPN. It is a general recommendation to warn customers that a payment method can not be accessed through a VPN.

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.

Callback example

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

Callbacks for Withdraw requests will be sent to the same URL. Make sure to properly filter callbacks by type.

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 deposits in the Demo Environment. Some (not all) of the APMs provide simulation capability directly in the UI of the sandbox environment.

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.

For the time being no sandbox is available for TRY. The Demo environment is connected to a separate Papara production instance. Instead, try using the simulation API.

Testing with transaction simulation

The Demo Environment provides an API to simulate a deposit from any supported APM.