UltraPay API Documentation
Complete guide for integrating payment gateway for deposits and withdrawals
Overview
UltraPay supports two pay-in integration modes: Redirect and H2H (Host-to-Host).
In Redirect mode, users are sent to a payment page hosted by UltraPay to complete the pay-in. Once finalized, the user is redirected back to the merchant's site. This is the default mode.
In H2H mode, UltraPay returns a UPI QR deeplink (qrData) directly in the API response. The merchant renders it as a QR code or passes it to a UPI app — no hosted page is involved.
This documentation outlines the required APIs for integrating the UltraPay Payment Gateway for both deposits (pay-ins) and withdrawals (pay-outs).
Deposits & Withdrawals
Unified APIs for pay-ins and pay-outs.
Hosted & Secure
Users complete payment on a hosted page.
Simple Integration
Clear endpoints, callbacks, and error codes.
Authentication
All API requests require authentication using an API key provided to the merchant.
All API calls must include your API key in the x-api-key header.
| Header | Value | Description |
|---|---|---|
x-api-key | your_merchant_key | Your assigned API key |
Environments
https://staging-api.ultrapay.livehttps://api.ultrapay.liveAPI Endpoints
Every request must be authenticated with your x-api-key header. Examples below use the production base URL.
Generate Deposit (Pay-in)
/v1/payIn/generate-payinGenerates a pay-in session. The response format depends on the integration mode configured for your merchant account. In Redirect mode a hosted payment URL is returned. In H2H mode the raw UPI payment data is returned directly so you can build your own payment UI. In Both mode you receive both the hosted URL and the raw data.
Important Notes
- The pay-in link (Redirect / Both mode) is valid for 30 days.
- The generated Pay-In ID must be stored until the pay-in process is complete (success or failure).
- H2H mode: use qrData as the UPI deeplink — render it as a QR code or pass it directly to a UPI app to trigger payment.
- H2H mode: no hosted payment page is involved. Your application is responsible for displaying the payment interface to the user.
Request Parameters (Query)
| Field | Type | Required | Description | Conditions |
|---|---|---|---|---|
code | string | Required | The merchantCode assigned by UltraPay | - |
user_id | string | Required | A unique identifier for the user | Must be distinct from merchant_order_id |
ot | string | Required | One-time token indicator | Always pass 'y' |
amount | int | Required | The requested deposit amount | Must be within merchant's Pay-in limits |
merchant_order_id | string | Required | A unique identifier for the transaction | - |
notifyUrl | string | Required | Merchant's endpoint for transaction status callback | Must be https |
returnUrl | string | Required | Redirect page after payment process (Redirect / Both mode) | Must be https |
latitude | string | Optional | Latitude of the request origin | - |
longitude | string | Optional | Longitude of the request origin | - |
name | string | Optional | User's name | - |
mobile | string | Optional | User's mobile number | - |
Sample Request
curl --location 'https://api.ultrapay.live/v1/payIn/generate-payin?code=<your code>&ot=y&amount=<amount>&user_id=<your user id>&merchant_order_id=<your_order_id>¬ifyUrl=https://your-callback.com/notify&returnUrl=https://your-site.com/return' \
--header 'x-api-key: your_merchant_key'Success Responses
{
"message": "PayIn is generated & url is sent successfully",
"statusCode": 200,
"data": {
"payinId": "0dd963cf-5d23-4453-8a88-5bfd59edd05b",
"merchantOrderId": "2db651f4-00f3-4f57-b3f3-80c9337e1522",
"expirationDate": "2026-05-05T15:36:12.434Z",
"payInUrl": "https://payment-site.vercel.app/transaction/..."
}
}{
"message": "PayIn is generated successfully",
"statusCode": 200,
"data": {
"payinId": "700462d9-2bf8-43ed-b0e2-4becab0c1d6b",
"merchantOrderId": "your_order_id",
"status": "INITIATED",
"amount": 506,
"qrData": "upi://pay?pa=merchant@upi&pn=MerchantName&tr=RECEIPT123&tn=RECEIPT123&am=506&cu=INR",
"receipt": "RECEIPT123"
}
}{
"message": "PayIn is generated successfully",
"statusCode": 200,
"data": {
"payinId": "700462d9-2bf8-43ed-b0e2-4becab0c1d6b",
"merchantOrderId": "your_order_id",
"status": "INITIATED",
"expirationDate": "2026-05-05T15:36:12.434Z",
"payInUrl": "https://payment-site.vercel.app/transaction/...",
"amount": 506,
"qrData": "upi://pay?pa=merchant@upi&pn=MerchantName&tr=RECEIPT123&tn=RECEIPT123&am=506&cu=INR",
"receipt": "RECEIPT123"
}
}Generate Withdrawal (Pay-out)
/v1/payOut/create-payoutThis API call initiates a pay-out request, transferring the specified amount to the user's provided bank account.
Important Notes
- If a successful transaction is later reversed by the bank, its status will be marked as REVERSED.
Request Parameters (JSON Body)
| Field | Type | Required | Description | Conditions |
|---|---|---|---|---|
code | string | Required | The merchantCode | - |
user_id | string | Required | Unique user identifier | Must be distinct from merchant_order_id |
bank_name | string | Required | The player's bank name | Full name of the bank must be provided |
acc_no | string | Required | The bank account number | - |
acc_holder_name | string | Required | The account holder's name | - |
ifsc_code | string | Required | The IFSC code of the bank account | - |
amount | int | Required | The payout amount | Must be within merchant's Pay-out limits |
notifyUrl | string | Required | Endpoint to receive transaction status callback | Must be https |
merchant_order_id | string | Required | A unique identifier for the transaction | - |
type | string | Optional | Account type (e.g., savings or current) | - |
name | string | Optional | User's name | - |
mobile | string | Optional | User's mobile number | - |
Sample Request
curl --location 'https://api.ultrapay.live/v1/payOut/create-payout' \
--header 'x-api-key: your_merchant_key' \
--header 'Content-Type: application/json' \
--data '{
"user_id": "Test01",
"code": "<your code>",
"amount": 5770,
"acc_no": "9876543210",
"acc_holder_name": "John Doe",
"ifsc_code": "IFSC0001234",
"bank_name": "Sample Bank",
"notifyUrl": "https://your-callback.com/notify",
"merchant_order_id": "5e672c64-e91d-4c9f-9bf8-776edd19cfac"
}'Success Response201
{
"message": "Payout created successfully",
"statusCode": 201,
"data": {
"merchantOrderId": "5e672c64-e91d-4c9f-9bf8-776edd19cfac",
"payoutId": "bf66316b-4620-4ec9-a3b5-4b7e222fa6c8",
"amount": 5770
}
}Check Deposit Status
/v1/payIn/check-payin-statusThis API allows the merchant to retrieve the status of a specific Pay-in transaction.
Request Parameters (JSON Body)
| Field | Type | Required | Description |
|---|---|---|---|
merchantCode | string | Required | The merchantCode |
merchantOrderId | string | Required | The order ID used during initialization |
payinId | string | Required | The Pay-in ID returned upon initialization |
Sample Request
curl --location 'https://api.ultrapay.live/v1/payIn/check-payin-status' \
--header 'x-api-key: your_merchant_key' \
--header 'Content-Type: application/json' \
--data '{
"payinId": "0dd963cf-5d23-4453-8a88-5bfd59edd05b",
"merchantCode": "<your code>",
"merchantOrderId": "2db651f4-00f3-4f57-b3f3-80c9337e1522"
}'Possible Status Values
| Status | Description |
|---|---|
| SUCCESS | Payment was successful |
| PENDING | Transaction is in process |
| DROPPED | Transaction was initiated but no further action was taken |
| FAILED | Transaction failed |
| DUPLICATE | Transaction was a duplicate |
| DISPUTE | Transaction is under dispute |
| BANK_MISMATCH | Bank details provided did not match |
| IMG_PENDING | Image verification is pending |
Check Withdrawal Status
/v1/payOut/check-payout-statusThis API allows the merchant to retrieve the status of a specific Pay-out transaction.
Request Parameters (JSON Body)
| Field | Type | Required | Description |
|---|---|---|---|
merchantCode | string | Required | The merchantCode |
merchantOrderId | string | Required | The order ID used during initialization |
payoutId | string | Optional | The Pay-out ID returned upon initialization |
Sample Request
curl --location 'https://api.ultrapay.live/v1/payOut/check-payout-status' \
--header 'x-api-key: your_merchant_key' \
--header 'Content-Type: application/json' \
--data '{
"merchantCode": "<your code>",
"merchantOrderId": "8772f4b4-73df-4235-aae7-b68cdbb4cda1",
"payoutId": "270b94c9-d732-4167-aef2-b71780aec35b"
}'Possible Status Values
| Status | Description |
|---|---|
| INITIATED | The payout request has been received and started |
| APPROVED | The payout has been successfully processed |
| REJECTED | The payout request was rejected |
| REVERSED | The successful transaction was later reversed by the bank |
Merchant Callbacks
Callbacks are asynchronous POST notifications sent to your configured notifyUrl when a transaction status changes.
Deposit (Pay-in) Callback
Your notifyUrlUltraPay sends the transaction status after the deposit process is completed on the hosted page.
The structure is identical to the successful response of the Check Deposit Status API, and can have any of the status values (e.g., SUCCESS, DROPPED, PENDING, FAILED, etc.).
Example Callback Body
{
"status": "SUCCESS",
"merchantOrderId": "2db651f4-00f3-4f57-b3f3-80c9337e1522",
"amount": 1200,
"payinId": "0dd963cf-5d23-4453-8a88-5bfd59edd05b",
"req_amount": 1200,
"utr_id": "5342343423"
}Withdrawal (Pay-out) Callback
Your notifyUrlUltraPay sends the transaction status after the withdrawal process is completed.
The structure is identical to the successful response of the Check Withdrawal Status API, and can have any of the status values (e.g., APPROVED, REJECTED, REVERSED).
Example Callback Body
{
"status": "APPROVED",
"merchantOrderId": "79334b7a-f6bc-4131-92f3-5046ff5ef011",
"amount": 5770,
"payoutId": "f01cad58-ec14-46e5-84c4-efde465b60db",
"utr_id": "23423423421"
}Error Codes
HTTP status codes commonly returned across the API to indicate errors.
| Code | Description | Endpoints |
|---|---|---|
| 400 | Bad Request Invalid request: data type mismatch, incomplete request, or other validation error | All Pay-in/Pay-out Endpoints |
| 404 | Not Found Invalid merchant key or code | All Pay-in/Pay-out Endpoints |
| 461 | Limit Exceeded Amount is beyond the configured Pay-in limits (for deposits) or Pay-out limits (for withdrawals) | Initialize Deposit/Withdrawal |
| 500 | Internal Server Error An unexpected server-side error occurred | All Pay-in/Pay-out Endpoints |
Note on Validation Errors
A new error category, Validation Error, has been introduced. This applies to checks on the keys you provide, including their names and data types.