Payment Gateway Integration

UltraPay API Documentation

Complete guide for integrating payment gateway for deposits and withdrawals

Introduction

Overview

UltraPay provides a hosted payment solution. This means users are redirected to a payment page managed by UltraPay to complete the pay-in process. Once the transaction is finalized (successful or failed), the user is redirected back to the merchant's specified website.

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.

Access

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

Base URLs

Environments

Staging

https://staging-api.ultrapay.live

Production

https://api.ultrapay.live

Reference

API Endpoints

Every request must be authenticated with your x-api-key header. Examples below use the production base URL.

Generate Deposit (Pay-in)

GET/v1/payIn/generate-payin

This API call is used to generate a secure pay-in link (payInUrl) that redirects the user to the hosted payment page.

Important Notes

The pay-in link is valid for only 10 minutes.
The generated Pay-In ID must be stored until the pay-in process is complete (success or failure).

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	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

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>&notifyUrl=https://your-callback.com/notify&returnUrl=https://your-site.com/return' \
--header 'x-api-key: your_merchant_key'

Success Response200

JSON

{
  "message": "PayIn is generated & url is sent successfully",
  "statusCode": 200,
  "data": {
    "expirationDate": "2026-05-05T15:36:12.434Z",
    "payInUrl": "https://payment-site.vercel.app/transaction/...",
    "payinId": "0dd963cf-5d23-4453-8a88-5bfd59edd05b",
    "merchantOrderId": "2db651f4-00f3-4f57-b3f3-80c9337e1522"
  }
}

Generate Withdrawal (Pay-out)

POST/v1/payOut/create-payout

This 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

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

JSON

{
  "message": "Payout created successfully",
  "statusCode": 201,
  "data": {
    "merchantOrderId": "5e672c64-e91d-4c9f-9bf8-776edd19cfac",
    "payoutId": "bf66316b-4620-4ec9-a3b5-4b7e222fa6c8",
    "amount": 5770
  }
}

Check Deposit Status

POST/v1/payIn/check-payin-status

This 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

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

POST/v1/payOut/check-payout-status

This 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

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

Async Notifications

Merchant Callbacks

Callbacks are asynchronous POST notifications sent to your configured notifyUrl when a transaction status changes.

Deposit (Pay-in) Callback

POSTYour notifyUrl

UltraPay 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

JSON

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

POSTYour notifyUrl

UltraPay 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

JSON

{
  "status": "APPROVED",
  "merchantOrderId": "79334b7a-f6bc-4131-92f3-5046ff5ef011",
  "amount": 5770,
  "payoutId": "f01cad58-ec14-46e5-84c4-efde465b60db",
  "utr_id": "23423423421"
}

Troubleshooting

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.