zedpayz Integration API Documentation

Complete guide for integrating payment gateway for deposits and withdrawals

Overview

zedpayz provides a hosted payment solution. This means users are redirected to a payment page managed by zedpayz 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 zedpayz Payment Gateway for both deposits (pay-ins) and withdrawals (pay-outs).

Authentication

All API requests require authentication using two keys provided to the merchant:

Public Key: Should be included in most request headers.

Private Key: Must be stored securely on your end.

Authentication Header

All API calls must include the Public Key in the x-api-key header.

Header Name	Value	Description
`x-api-key`	`your_merchant_key`	Your assigned Public Key

Environments (Base URLs)

Environment	Base URL
Staging	`https://api.staging.zedpayz.com`
Production	`https://api.zedpayz.com`

API Endpoints

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

Field	Type	Required	Description	Special Conditions
`code`	string	Required	The merchantCode assigned by zedpayz	-
`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)

bash

curl --location 'https://api.staging.zedpayz.com/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 Response(Status: 200 OK)

json

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

2. 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 Note:

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	Special Conditions
`code`	string	Yes	The merchantCode	-
`user_id`	string	Yes	Unique user identifier	Must be distinct from merchant_order_id
`bank_name`	string	Yes	The player's bank name	Full name of the bank must be provided
`acc_no`	string	Yes	The bank account number	-
`acc_holder_name`	string	Yes	The account holder's name	-
`ifsc_code`	string	Yes	The IFSC code of the bank account	-
`amount`	int	Yes	The payout amount	Must be within merchant's Pay-out limits
`notifyUrl`	string	Yes	Endpoint to receive transaction status callback	Must be https
`merchant_order_id`	string	Yes	A unique identifier for the transaction	-
`type`	string	No	Account type (e.g., savings or current)	-
`name`	string	No	User's name	-
`mobile`	string	No	User's mobile number	-

Sample Request (cURL)

bash

curl --location 'https://api.staging.zedpayz.com/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 Response (Status: 201 Created)

json

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

3. 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	Yes	The merchantCode
`merchantOrderId`	string	Yes	The order ID used during initialization
`payinId`	string	Yes	The Pay-in ID returned upon initialization

Sample Request (cURL)

bash

curl --location 'https://api.staging.zedpayz.com/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

The response structure is the same for all statuses, but the values change. The utr_id is now included even for PENDING statuses.

Status Value	Description
SUCCESS	Payment was successful
PENDING	Transaction is in process
DROPPED	Transaction was initiated but no further action was taken (pre-update this was marked as Failed)
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

4. 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	Yes	The merchantCode
`merchantOrderId`	string	Yes	The order ID used during initialization
`payoutId`	string	No	The Pay-out ID returned upon initialization

Sample Request (cURL)

bash

curl --location 'https://api.staging.zedpayz.com/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 Value	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 notifications sent to the merchant's configured notifyUrl when a transaction status changes. Both callbacks are sent as a POST request.

Deposit (Pay-in) Callback

POSTYour notifyUrl

zedpayz sends the transaction status after the deposit process is completed on the hosted page.

Endpoint: The callbackUrl provided in the Initialize Deposit request.

Example Callback Body

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

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

zedpayz sends the transaction status after the withdrawal process is completed.

Endpoint: The callbackUrl provided in the Initialize Withdrawal request.

Example Callback Body

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

json

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

Error Codes

The following HTTP status codes are commonly used across the API to indicate errors.

HTTP Status 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.