# 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 {% hint style="warning" %} **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. {% endhint %} #### Create an invoice Use the following body against [extended invoice creation API](https://docs.xgateway.tech/advanced-features-of-invoice-creation#extended-response-for-invoice-creation)
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). > 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. ```json {"openapi":"3.0.0","info":{"title":"x-gateway-external-api","version":"0.0.1"},"servers":[{"url":"https://api.xgateway.tech/api/v2"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"AppSuccessResponse_Gateway9DepositRecipientDetails_":{"description":"The AppSuccessResponse object contains general information about the success execution.","properties":{"success":{"type":"boolean","default":true},"data":{"$ref":"#/components/schemas/Gateway9DepositRecipientDetails"}},"required":["success","data"],"type":"object","additionalProperties":false},"Gateway9DepositRecipientDetails":{"$ref":"#/components/schemas/Pay2PlayHostToHostDepositRecipientDetails"},"Pay2PlayHostToHostDepositRecipientDetails":{"properties":{"recipient":{"type":"string"},"upiInfo":{"properties":{"qrUrl":{"type":"string"},"qrData":{"type":"string"},"recipient":{"type":"string"},"accountNumber":{"type":"string"}},"required":["qrUrl","qrData","recipient","accountNumber"],"type":"object"}},"required":["recipient","upiInfo"],"type":"object","additionalProperties":false},"AppErrorResponse":{"description":"The AppErrorResponse object contains general information about the error message.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array"}},"required":["success","errors"],"type":"object","additionalProperties":false},"IAppError":{"description":"The IAppError interface represents an application error message.","properties":{"code":{"anyOf":[{"$ref":"#/components/schemas/AppClientErrorResponseCode"},{"$ref":"#/components/schemas/AppServerErrorResponseCode"}]},"message":{"type":"string"}},"required":["code","message"],"type":"object","additionalProperties":false},"AppClientErrorResponseCode":{"type":"string","enum":["bad_request","db_violation","unauthorized","payment_required","forbidden","not_found","method_not_allowed","not_acceptable","proxy_authentication_required","request_timeout","conflict","db_unique_violation","gone","length_required","precondition_failed","payload_too_large","uri_too_long","unsupported_media_type","range_not_satisfiable","expectation_failed","misdirected_request","unprocessable_content","db_non_null_violation","locked","failed_dependency","upgrade_required","precondition_required","too_many_requests","request_header_fields_too_large","unavailable_for_legal_reasons"],"nullable":false,"description":"The AppClientErrorResponseCode object contains all client error response codes."},"AppServerErrorResponseCode":{"type":"string","enum":["internal_server_error","not_implemented","bad_gateway","service_unavailable","gateway_timeout","http_version_not_supported","variant_also_negotiates","insufficient_storage","loop_detected","not_extended","network_authentication_required"],"nullable":false,"description":"The AppServerErrorResponseCode object contains all server error response codes."},"AppAuthenticationErrorResponse":{"description":"The AppAuthenticationErrorResponse object contains general information about the authentication\nerror.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array","default":[{"code":"unauthorized","message":"You do not have permission to access this resource."}]}},"required":["success","errors"],"type":"object","additionalProperties":false},"AppValidationErrorResponse":{"description":"The AppValidationErrorResponse object contains general information about the validation error.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{},"type":"array"}},"required":["success","errors"],"type":"object","additionalProperties":false}}},"paths":{"/gateway9/deposit/{invoiceId}/recipient-details":{"get":{"operationId":"GetDepositRecipientDetails","responses":{"200":{"description":"A successful response containing recipient details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppSuccessResponse_Gateway9DepositRecipientDetails_"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAuthenticationErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}},"422":{"description":"Unprocessable content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppValidationErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}}},"description":"Retrieves recipient details for a deposit transaction for a merchant.\nReturns bank account information where the customer should send their payment.\nRequires merchant authentication via API key.","summary":"Get deposit recipient details (Merchant API).","tags":["Gateway9"],"parameters":[{"description":"- Unique identifier of the invoice.","in":"path","name":"invoiceId","required":true,"schema":{"type":"string"}}]}}}} ``` #### Confirm the payment Use the following API to submit the UTR. ## Confirm deposit payment (Merchant API). > 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. ```json {"openapi":"3.0.0","info":{"title":"x-gateway-external-api","version":"0.0.1"},"servers":[{"url":"https://api.xgateway.tech/api/v2"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"AppSuccessResponse_string_":{"description":"The AppSuccessResponse object contains general information about the success execution.","properties":{"success":{"type":"boolean","default":true},"data":{"type":"string"}},"required":["success","data"],"type":"object","additionalProperties":false},"AppErrorResponse":{"description":"The AppErrorResponse object contains general information about the error message.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array"}},"required":["success","errors"],"type":"object","additionalProperties":false},"IAppError":{"description":"The IAppError interface represents an application error message.","properties":{"code":{"anyOf":[{"$ref":"#/components/schemas/AppClientErrorResponseCode"},{"$ref":"#/components/schemas/AppServerErrorResponseCode"}]},"message":{"type":"string"}},"required":["code","message"],"type":"object","additionalProperties":false},"AppClientErrorResponseCode":{"type":"string","enum":["bad_request","db_violation","unauthorized","payment_required","forbidden","not_found","method_not_allowed","not_acceptable","proxy_authentication_required","request_timeout","conflict","db_unique_violation","gone","length_required","precondition_failed","payload_too_large","uri_too_long","unsupported_media_type","range_not_satisfiable","expectation_failed","misdirected_request","unprocessable_content","db_non_null_violation","locked","failed_dependency","upgrade_required","precondition_required","too_many_requests","request_header_fields_too_large","unavailable_for_legal_reasons"],"nullable":false,"description":"The AppClientErrorResponseCode object contains all client error response codes."},"AppServerErrorResponseCode":{"type":"string","enum":["internal_server_error","not_implemented","bad_gateway","service_unavailable","gateway_timeout","http_version_not_supported","variant_also_negotiates","insufficient_storage","loop_detected","not_extended","network_authentication_required"],"nullable":false,"description":"The AppServerErrorResponseCode object contains all server error response codes."},"AppAuthenticationErrorResponse":{"description":"The AppAuthenticationErrorResponse object contains general information about the authentication\nerror.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array","default":[{"code":"unauthorized","message":"You do not have permission to access this resource."}]}},"required":["success","errors"],"type":"object","additionalProperties":false},"AppValidationErrorResponse":{"description":"The AppValidationErrorResponse object contains general information about the validation error.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{},"type":"array"}},"required":["success","errors"],"type":"object","additionalProperties":false},"Gateway9ConfirmDepositInput":{"properties":{"invoiceId":{"type":"string"},"utr":{"type":"string"},"receipt_file":{"type":"string"},"receipt_file_extension":{"type":"string"},"receipt_file_name":{"type":"string"}},"required":["invoiceId","utr"],"type":"object","additionalProperties":false}}},"paths":{"/gateway9/deposit/confirm":{"post":{"operationId":"ConfirmDepositPaymentHostToHost","responses":{"200":{"description":"A successful response with confirmation message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppSuccessResponse_string_"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAuthenticationErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}},"422":{"description":"Unprocessable content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppValidationErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}}},"description":"Confirms a deposit payment for a merchant\nThis endpoint validates and confirms a customer's payment when they provide the UTR (Unique Transaction Reference).\nRequires merchant authentication via API key.","summary":"Confirm deposit payment (Merchant API).","tags":["Gateway9"],"parameters":[],"requestBody":{"description":"- Request body containing payment confirmation details.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Gateway9ConfirmDepositInput","description":"- Request body containing payment confirmation details."}}}}}}}} ``` #### Confirming a transaction {% hint style="danger" %} Due to security risks, merchants *must* use our [API endpoint](https://docs.xgateway.tech/miscellaneous/deposit-data-confirmation) to request transaction details. XGateway is not liable for issues caused by relying only on callback data. {% endhint %} To confirm the received deposit callback is valid, please use the [API endpoint](https://docs.xgateway.tech/miscellaneous/deposit-data-confirmation). ### Testing Demo environment Check [this page](https://docs.xgateway.tech/miscellaneous/deposit-and-withdrawal-simulation) for ways to test the integration. [^1]: --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.xgateway.tech/integration-guides/inr-apm-using-host-to-host.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.