INR APM using host-to-host

The host-to-host communication allows a merchant to send all the data needed for a payment in the background without using XGateway checkout pages. This flow has the best conversion rate because it allows the customer to stay withim merchant domain.

Payment Flow

The host-to-host flow for INR payment includes the following 3 steps:

1. Create an invoice

2. Get payment details

3. Confirm the payment

Important Integration rules

• Make sure to notify the customer to submit a correct UTR.

• If a UTR is not submitted, the invoice will be cancelled.

• If a wrong UTR is submitted, the invoice will be cancelled.

Create an invoice

Use the following body against extended invoice creation API

Request body

{
    "amount":"501",
    "baseCurrency":"INR",
    "customerId":"some-customer-uuid",
    "orderId":"some-order-id",
    "paymentCurrency":"INR",
    "paymentMethod":"basic_h2h",
    "paymentSystem":"UPI"
}

Take the invoice ID from the response body

Response example

{
  "data": {
    "amount": "100.00",
    "baseCurrency": "EUR",
    "createdAt": "2026-01-28T14:35:00.000Z",
    "customerId": "3f0a9b6d-8c2b-4f21-9f6b-7a8e2d5c4b1f",
    "id": "5d7c2f4a-1b6e-4e3a-8c9f-2a3b4d5e6f7a", // <- THIS ONE!!!
    "paymentUrl": "https://checkout.xgateway.tech/5d7c2f4a-1b6e-4e3a-8c9f-2a3b4d5e6f7a",
    "status": "created",
    "strategy": "floating",
    "type": "deposit",
    "accountId": "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "orderId": "f1e2d3c4-b5a6-7f8e-9d0c-1b2a3e4f5d6c",
    "paymentCurrency": "EUR",
    "transactions": []
  },
  "success": true
}

Get payment details

Get the payment details for a UPI transaction using this API and the invoide ID

Get deposit recipient details (Merchant API).

get

Retrieves recipient details for a deposit transaction for a merchant. Returns bank account information where the customer should send their payment. Requires merchant authentication via API key.

Authorizations

api_key

x-api-keystringRequired

Path parameters

invoiceIdstringRequired

• Unique identifier of the invoice.

Responses

200

A successful response containing recipient details.

application/json

The AppSuccessResponse object contains general information about the success execution.

successbooleanRequiredDefault: true

400

Bad request

application/json

401

Unauthorized

application/json

404

Not Found

application/json

422

Unprocessable content

application/json

500

Internal server error

application/json

get

/gateway9/deposit/{invoiceId}/recipient-details

HTTPcURLJavaScriptPython

GET /api/v2/gateway9/deposit/{invoiceId}/recipient-details HTTP/1.1
Host: api.xgateway.tech
x-api-key: YOUR_API_KEY
Accept: */*

{
  "data": {
    "recipient": "Account Holder Name",
    "upiInfo": {
      "accountNumber": "9876543210",
      "recipient": "Account Holder Name",
      "qrData": "upi://pay?pa=merchant@bank&pn=MerchantName&am=100&tn=Payment",
      "qrUrl": "https://example.com/qr/code.png"
    }
  },
  "success": true
}

Confirm the payment

Use the following API to submit the UTR.

Confirm deposit payment (Merchant API).

post

Confirms a deposit payment for a merchant This endpoint validates and confirms a customer's payment when they provide the UTR (Unique Transaction Reference). Requires merchant authentication via API key.

Authorizations

api_key

x-api-keystringRequired

Body

application/json

• Request body containing payment confirmation details.

invoiceIdstringRequired

utrstringRequired

receipt_filestringOptional

receipt_file_extensionstringOptional

receipt_file_namestringOptional

Responses

200

A successful response with confirmation message.

application/json

The AppSuccessResponse object contains general information about the success execution.

successbooleanRequiredDefault: true

datastringRequired

400

Bad request

application/json

401

Unauthorized

application/json

404

Not Found

application/json

422

Unprocessable content

application/json

500

Internal server error

application/json

post

/gateway9/deposit/confirm

HTTPcURLJavaScriptPython

POST /api/v2/gateway9/deposit/confirm HTTP/1.1
Host: api.xgateway.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 114

{
  "invoiceId": "text",
  "utr": "text",
  "receipt_file": "text",
  "receipt_file_extension": "text",
  "receipt_file_name": "text"
}

{
  "data": "Payment confirmed successfully",
  "success": true
}

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 received deposit callback is valid, please use the API endpoint.

Testing Demo environment

Check this page for ways to test the integration.