Merchant Open API

Merchants need to log in to the console -> Developer to obtain the Merchant Developer Secret before calling this series of APIs.

Introduction

Request Method

• HOST: https://open.idatariver.com
• Headers: Authorization: Bear Your_Developer_Secret

Multi-language Support

The platform supports automatic translation of merchant project/product information into multiple languages. To obtain information in a specific language, simply include the X-Idr-Locale field in the Headers.

The translated content will be stored in the nameI18n and descI18n fields.

Currently, the automatic translation includes the name and desc fields of projects/products.

X-Idr-Locale	Language
en	🇬🇧 English
fa	🇮🇷 Persian
zh-cn	🇨🇳 Simplified Chinese
ja	🇯🇵 Japanese
ru	🇷🇺 Russian
zh-hk	🇭🇰 Traditional Chinese
de	🇩🇪 German
ar	🇦🇪 Arabic
es	🇪🇸 Spanish
fr	🇫🇷 French
ko	🇰🇷 Korean
tr	🇹🇷 Turkish
uk	🇺🇦 Ukrainian
uz	🇺🇿 Uzbek
kk	🇰🇿 Kazakh
pl	🇵🇱 Polish
pt	🇵🇹 Portuguese
pa	🇮🇳 Punjabi

Request Example

GET Request

curl https://open.idatariver.com/mapi?key=value \
  -H "Authorization: Bearer $iDataRiver_Merchant_Secret" \
  -H "X-Idr-Locale: en" \

POST Request

curl https://open.idatariver.com/mapi \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $iDataRiver_Merchant_Secret" \
  -H "X-Idr-Locale: en" \
  -d '{
    "key": "value"
  }'

Response Format

To ensure uniform management and maintenance of the API, responses follow the field format below:

Field Name	Description
code	(Required) Return code, an integer representing the business status. Detailed meanings are provided in the table below.
result	(Optional) The complete raw result, with its structure and explanations provided by the supplier.
msg	(Optional) Reason for request failure.

Return Code Explanation

The meaning and explanation of the code field:

code	Description
0	Request successful
1000	Internal error
1001	Parameter error
1002	Requested resource not found
1003	Internal processing busy, please try again later
1004	Insufficient permissions

API Documentation

Use Cases

Open APIs are divided into Public APIs and Private APIs with the following differences:

Public APIs are generally triggered by users, such as placing orders, viewing product information on the merchant's homepage, etc., suitable for use in the frontend of independent sites.

Private APIs should only be used by merchants themselves to access or manage core merchant data, suitable for backend processing of merchant data management.

Even Public APIs should not be directly exposed in the frontend to avoid leaking merchant secrets.

Basic Merchant Store Information Public

Returns basic merchant information.

GET /mapi/merchant/basicInfo

Response Fields

Field	Type	Description
name	string	merchant name
desc	string	merchant introduction
contacts	object	merchant contact info
website	object	website config

Merchant Homepage Information Public

Returns a list of merchant projects along with all product information under each project.

GET /mapi/merchant/info

Response Fields

Example

Field	Type	Description
name	string	merchant name
desc	string	merchant introduction
contacts	object	merchant contact info
guarantee	number	merchant guarantee fee
projects	array	online projects. please refer to the project api for more details.
website	object	website config

Get Order Details Public

Retrieve detailed information of an order by order ID.

GET /mapi/order/info

Field	Type	Required	Description
id	string	Yes	Order ID

Response Fields

Example

Field	Type	Description
id	string	order id
skuName	string	merchant name
status	string	order status, possible values: NEW (new order), DONE (paid), EXPIRED (expired and not paid), REFUND (refunded)
quantity	number	order quantity
projectName	string	project name
projectType	string	project type
merchant	string	merchant id
oriPrice	number	original order price
price	number	order price.(after deducting the coupon discount)
affCode	string	order affiliates code
anonymous	bool	return true if the order placed anonymously
consumer	string	The consumer's user ID in iDataRiver. It is null when anonymous=true.
contactInfo	string	The query information left by the consumer when paying anonymously. Anyone can use this field to query the order
coupon	string	coupon code
paymentFeeCovered	bool	return true if the merchant pay payment gateway fees.
dt	string	order created date
createdAt	string	order created time (UTC+0)
createdTS	string	order created timestamp
digitalItemsStr	string	return order's digital product content
expiredInterval	number	order expired interval
mContacts	object	merchant contact info
mPayments	array	order payment methods(only display available)
mPayments[*].enabled	bool	return true if payment method enabled
mPayments[*].isPlatform	bool	return true if payment method is iDataRiver provided.
mPayments[*].name	string	payment name
mPayments[*].desc	string	payment description
mPayments[*].method	string	Payment method id, iDataRiver's built-in payment channel can take the following values: credits (platform balance payment), crypto (cryptocurrency), alipay (Alipay), wxpay (WeChat Pay), onramp (Visa/MasterCard), onramp-google (Google Pay), onramp-apple (Apple Pay), onramp-revolut(Revolut), onramp-venmo (Venmo), gcash (GCash)
mPayments[*].ratioRange	string	Payment channel charges a percentage rate
mPayments[*].fixedFeeRange	string	Payment channel charges a fixed fee (USD)
project	object	Project details, please refer to the project api for more details.
sku	object	Product details, please refer to the product/sku api for more details.

Create Product Order Public

Place a product order.

POST /mapi/order/add

Field	Type	Required	Description
projectId	string	Yes	Project ID, You can get the id field of the project in the Get All Projects api
skuId	string	Yes	Product ID
orderInfo	object	Yes	Order details, example: {"quantity": 1,"coupon": "","contactInfo": "","affCode":""}, where quantity is the order quantity, coupon is the discount coupon (if none, pass an empty string), contactInfo is the contact information (required), used for retrieving the order, with string length of 5-100, and affCode is the affiliate promotion code (optional).

For the BUYMEABTC project, the skuId field is not required. The orderInfo field format is as follows:

{"amount":5, "private": false, "name": "", "message": ""}

• amount Sponsorship amount, in USD
• private Whether to make the sponsorship information public
• name Nickname, can be empty
• message Message, can be empty

Response Fields

Field	Type	Description
orderId	string	order id

Pay for Product Order Public

Get the order payment redirection link.

If the order price is 0, the purchase will be successful directly and no payment link will be returned.

POST /mapi/order/pay

Field	Type	Required	Description
id	string	Yes	Order ID
method	string	Yes	Payment method, from the method value in the mPayments field of the order details interface
redirectUrl	string	No	Redirection link after successful payment, should point to the order page and include the complete domain name
callbackUrl	string	No	Backend callback notification triggered when the order completed or refunded, the order data will be sent to this link via a POST request (in JSON format), please process it within 5 seconds and return a 200/201 status code, otherwise it will be considered a callback failure. If the callback fails, it will be retried up to 5 times. This URL must use a domain name (https) and cannot be accessed through IP

callback check

For the order fields returned by callbackUrl, please refer to the order details API.

You can check whether the order is PAID or REFUND by the status field of the callback order.

When receiving an order callback, please request the order information API to confirm the real status of the order.

This can prevent malicious callbacks from third parties when the merchant's callbackUrl is leaked.

Note: The callback priority here is higher than the Event Webhook set by the merchant.

Response Fields

Field	Type	Description
payUrl	string	payment url
payCurrency	string	payment currency
amount	number	payment amount

Query Product Order List Public

Query the order list based on the contact information or order ID left when creating the order.

GET /mapi/order/search

Field	Type	Required	Description
query	string	Yes	Contact information or order number left when placing the order

Response Fields

Field	Type	Description
items	array	order list
items[*].id	string	order id
items[*].price	string	order price
items[*].quantity	string	order quantity
items[*].skuName	string	product name
items[*].status	string	order status
items[*].date	string	order created date (UTC+0)

Get Merchant Order List Private

Retrieve the merchant's order list in reverse chronological order.

GET /mapi/order/list

Field	Type	Required	Description
status	string	No	Order status, default is empty indicating no status filtering, possible values: DONE (completed), NEW (new order), EXPIRED (expired), REFUND (refunded)
page	string	No	Pagination parameter, default is 1, increment by 1 for each page

Get All Projects Private

Returns all projects created by the merchant, including projects that are not yet online.

Response Fields

Field	Type	Description
hasMore	bool	return true if has more
items	array	order list
items[*].id	string	order id
items[*].price	string	order price
items[*].quantity	string	order quantity
items[*].skuName	string	product name
items[*].status	string	order status
items[*].payMethod	string	consumer paid method
items[*].payTo	string	platform means pay to iDataRiver, merchant means pay to merchant directly.
items[*].platformFee	number	platform fee
items[*].paymentFee	number	payment gateway fee
items[*].paymentFeeCovered	bool	return true if the merchant pay payment gateway fees.
items[*].profit	number	The net profit after deducting all fees
items[*].date	string	order created date (UTC+0)

GET /mapi/project/list

Get Specific Project Private

Retrieve all data contained in a project, including product list, pricing list, and coupon list.

Digital products will return all inventory data.

Response Fields

Example

Field	Type	Description
projects	array	项目列表
projects[*].id	string	projectid
projects[*].type	string	project type
projects[*].status	string	project status
projects[*].cover	string	image link or base64 data
projects[*].name	string	project name
projects[*].nameI18n	object	project name(global languages)
projects[*].desc	string	project description
projects[*].descI18n	object	project description (global languages)
projects[*].i18nType	number	0 means auto translate、1 mean disabled
projects[*].owner	string	merchant id
projects[*].seoPath	string	project url path
projects[*].slug	string	project short id
projects[*].createdTS	string	project created timestamp
projects[*].createdAt	string	project created time
projects[*].updatedAt	string	project updated time

GET /mapi/project/detail

Field	Type	Required	Description
id	string	Yes	Project ID

Response Fields

Example

Field	Type	Description
id	string	project id
type	string	project type
status	string	project status
cover	string	image link or base64 data
name	string	project name
nameI18n	object	project name(global languages)
desc	string	project description
descI18n	object	project description (global languages)
i18nType	number	0 means auto translate、1 mean disabled
owner	string	merchant id
seoPath	string	project url path
slug	string	project short id
createdTS	string	project created timestamp
createdAt	string	project created time
updatedAt	string	project updated time
affiliates	array	affiliates
affiliates[*].id	string	id
affiliates[*].userId	string	aff's merchant id
affiliates[*].code	string	aff code
affiliates[*].name	string	aff name
affiliates[*].ratio	number	commission ratio
affiliates[*].totalAmount	number	aff's total sales
affiliates[*].settledAmount	number	settled amount
affiliates[*].settledProfit	number	settled profit
affiliates[*].lastSettleAt	string	last settlement time
affiliates[*].lastSettleTS	string	ast settlement timestamp
coupons	array	coupons
coupons[*].id	string	id
coupons[*].status	string	coupon status
coupons[*].code	string	coupon code
coupons[*].scope	string	possible values: globle (valid to all products), specific (valid to specific products)
coupons[*].policy	string	Discount strategy, possible values: reduction (price reduction), fixed (fixed price), discount (discount coupon)
coupons[*].fixed	number	the fixed price when policy=fixed
coupons[*].discount	number	the discount rate when policy=discount
coupons[*].capped	number	the reduction amount when policy=reduction
coupons[*].usedNum	number	used times
coupons[*].scopeItems	array	the product/sku id list when scope=specific
pricings	array	pricing list
pricings[*].id	string	id
pricings[*].status	string	pricing status
pricings[*].scope	string	possible values: globle (valid to all products), specific (valid to specific products)
pricings[*].policy	string	The possible values: fixed (fixed price), stage_quantity (tiered discount based on purchase quantity), stage_rpd (API business use, tiered discount based on the number of daily api calls), dynamic (API business use, dynamic pricing for each call)
pricings[*].price	number	price when policy=fixed
pricings[*].stages	array	tiered pricing rules
pricings[*].dynamicCapped	number	The maximum amount allowed when policy=dynamic, the default is no more than 0.2USD
pricings[*].scopeItems	array	the product/sku id list when scope=specific
skus	array	product/sku list
skus[*].id	string	product/sku id
skus[*].status	string	product status
skus[*].priority	number	Product display priority, the smaller the value, the higher the priority
skus[*].sold	number	sold number
skus[*].pricingScope	string	The possible values: global or specific, indicating whether the price is global or specific.
skus[*].docLink	string	external docs link
skus[*].stock	number	stock
skus[*].name	string	product name
skus[*].nameI18n	object	product name(global languages)
skus[*].desc	string	product description
skus[*].descI18n	object	product description(global languages)
skus[*].hiddenStock	bool	whether to hide stock
skus[*].itemType	string	When type=DIGITAL, the possible values: reuse (repeated sale), consumable (delete after sale)
skus[*].items	array	When type=DIGITAL, return all data items
skus[*].itemsNum	string	When type=DIGITAL, return the number of items

Create New Project Private

Create a new project.

POST /mapi/project/add

Field	Type	Required	Description
name	string	Yes	Project name
type	string	Yes	Project type, currently supports digital products: DIGITAL

Response Fields

Field	Type	Description
id	string	project id

Update Project Information Private

Update basic project information.

POST /mapi/project/update

Field	Type	Required	Description
id	string	Yes	Project ID, can be obtained from the project list interface
name	string	Yes	Project name, no more than 50 characters
status	string	Yes	Project status, possible values: ONLINE, OFFLINE
i18nType	string	No	Automatic translation status, possible values: enable-0, disable-1, default is 1
desc	string	No	Project description, no more than 500 characters
cover	string	No	Image base64 encoding, no more than 2Mb, only supports PNG, JPG, JPEG formats, example: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAkACQAAD...

Delete Project (Irreversible) Private

Delete a project.

POST /mapi/project/remove

Field	Type	Required	Description
project	string	Yes	Project ID

Get Single Product/SKU Details Private

Retrieve detailed information of a specific product under a project. Digital products will return data items.

GET /mapi/project/sku/detail

Field	Type	Required	Description
id	string	Yes	Product/SKU ID

Response Fields

Example

Field	Type	Description
id	string	product/sku id
status	string	project status
name	string	project name
nameI18n	object	project name(global languages)
desc	string	project description
descI18n	object	project description (global languages)
owner	string	merchant id
project	string	project id
priority	number	Product display priority, the smaller the value, the higher the priority
sold	number	sold number
docLink	string	external docs link
stock	number	stock
hiddenStock	bool	whether to hide stock
itemType	string	When type=DIGITAL, the possible values: reuse (repeated sale), consumable (delete after sale)
items	array	When type=DIGITAL, return all data items
itemsNum	string	When type=DIGITAL, return the number of items
order	object	order info
createdTS	string	project created timestamp
createdAt	string	project created time
updatedAt	string	project updated time

Add Project Product/SKU Private

Add a product under a specified project.

POST /mapi/project/sku/add

Field	Type	Required	Description
projectId	string	Yes	Project ID

Response Fields

Field	Type	Description
id	string	product/sku id

Update Product/SKU Private

Update product information.

When modifying digital product inventory data, the new data will directly overwrite the original inventory data items.

Therefore, if you need to change the inventory data items of digital products, please take the product offline first to avoid conflicts with ongoing orders.

POST /mapi/project/sku/update

Field	Type	Required	Description
id	string	Yes	Product/SKU ID
name	string	No	Product name, no more than 50 characters
status	string	No	Product status, possible values: ONLINE, OFFLINE
priority	number	No	Product priority, range is 1-100
itemType	string	No	Data item type, possible values: reusable-reuse, consumable-consumable
items	array	No	Digital product data items, each element corresponds to a card code, example: ["123", "456"], must pass the itemType parameter simultaneously. 🔔 This value will directly overwrite the original card codes, please use cautiously
docLink	string	No	External document link
hiddenStock	bool	No	Whether to hide inventory, values true or false
desc	string	No	Project description, no more than 500 characters

When updating a product, at least one valid field needs to be updated, otherwise it will return a failure.

Delete Product/SKU Private

Permanently delete a product, cannot be undone.

POST /mapi/project/sku/remove

Field	Type	Required	Description
id	string	Yes	Product/SKU ID

Add Pricing Plan Private

Add a pricing plan.

POST /mapi/project/pricing/add

Field	Type	Required	Description
projectId	string	Yes	Project ID

Response Fields

Field	Type	Description
id	string	pricing id

Update Pricing Plan Private

Update a pricing plan.

POST /mapi/project/pricing/update

Field	Type	Required	Description
id	string	Yes	Pricing plan ID
status	string	Yes	Product status, possible values: ONLINE, OFFLINE
scope	string	Yes	Product status, possible values: global-global, specific range-specific
scopeItems	array	No	When scope=specific, this array contains the IDs of the products to be affected and cannot be empty
policy	string	Yes	Pricing strategy, possible values: fixed price-fixed, wholesale price-stage_quantity
price	string	No	Fixed price, required when policy=fixed
stages	object	No	Wholesale price settings, required when policy=stage_quantity, example: [{ "threshold": 0, 'price': 10 },{ "threshold": 10, 'price': 8 }] means the unit price is 10 USD for purchases less than 10 units, and 8 USD for purchases of 10 units or more, with a maximum of 5 stages

Delete Pricing Plan Private

Permanently delete a pricing plan, cannot be undone.

Please ensure that there is at least one available pricing plan for the product.

POST /mapi/project/pricing/remove

Field	Type	Required	Description
id	string	Yes	Pricing plan ID

Add Coupon Private

Add a coupon.

POST /mapi/project/coupon/add

Field	Type	Required	Description
projectId	string	Yes	Project ID

Response Fields

Field	Type	Description
id	string	coupon id

Update Coupon Private

Update coupon rules.

POST /mapi/project/coupon/update

Field	Type	Required	Description
id	string	Yes	Coupon ID
status	string	Yes	Product status, possible values: ONLINE, OFFLINE
scope	string	Yes	Product status, possible values: global-global, specific range-specific
scopeItems	array	No	When scope=specific, this array contains the IDs of the products to be affected and cannot be empty
policy	string	Yes	Pricing strategy, possible values: reduction coupon-reduction, discount coupon-discount, fixed price coupon-fixed
reduction	number	No	Reduction amount for reduction coupons, required when policy=reduction
fixed	number	No	Fixed price amount for fixed price coupons, required when policy=fixed
discount	number	No	Discount percentage, range 1-100, required when policy=discount
capped	number	No	Discount cap amount, used to control the maximum discount amount when policy=discount

Delete Coupon Private

Permanently delete a coupon, cannot be undone.

POST /mapi/project/coupon/remove

Field	Type	Required	Description
id	string	Yes	Coupon ID

Telegram Bot Bulk Messaging Private

This feature requires merchants to first enable a custom Telegram bot. Merchants can also use the Telegram Bulk Messaging Assistant directly in the store.

Add a Telegram broadcast message to be sent using the merchant's custom Telegram bot.

🔔 This interface does not limit the number of bulk messages, but only one bulk message can be processed at a time. You must wait for the previous bulk message to be processed before sending another.

It is strongly recommended to use this feature wisely. Each bulk message will automatically filter out invalid users.

POST /mapi/rainbow/broadcast/add

Field	Type	Required	Description
content	string	Yes	Bulk message content, no more than 4000 characters
test	bool	Yes	Whether it is test mode, pass true to send only to the account bound by the merchant (commonly used for testing before official bulk messaging), pass false to send to all users who can receive messages

Get Telegram Bot Bulk Messaging History Private

Retrieve recent Telegram bot bulk messaging history, including total number of users, number of users who declined, number of successful sent, and total execution time.

GET /mapi/rainbow/broadcast/list

Response Fields

Example

Field	Type	Description
items	array	broadcast list
items[*].id	string	braodcast id
items[*].eid	string	business id (for deduplication)
items[*].status	string	status
items[*].params	object	broadcast params
items[*].createdTS	string	created timestamp
items[*].createdAt	string	created time

Query License Info Public

Query License details.

GET /mapi/license/query

Field	Type	Required	Description
code	string	Yes	License code, supports pass multiple values (comma-separated), up to 100 at a time

Response Fields

Field	Type	Description
items	array	license list
items[*].license	string	license code
items[*].status	string	license status
items[*].states	string	business states
items[*].order	string	order id
items[*].merchant	string	merchant id
items[*].skuName	string	product name
items[*].createdTS	string	created timestamp
items[*].createdAt	string	created time
items[*].activateTS	string	activate timestamp
items[*].activateAt	string	activate time

Activate License Private

Mark the License as used, this process is irreversible.

License can only be activated once, and the merchant should call this API to activate the License after it is used to prevent it from being reused.

POST /mapi/license/activate

Field	Type	Required	Description
code	string	Yes	License code, supports pass multiple values (comma-separated), up to 100 at a time

The response data will include the successfully activated License information.

Response Fields

Field	Type	Description
items	array	license list
items[*].license	string	license code
items[*].status	string	license status
items[*].states	string	business states
items[*].order	string	order id
items[*].merchant	string	merchant id
items[*].skuName	string	product name
items[*].createdTS	string	created timestamp
items[*].createdAt	string	created time
items[*].activateTS	string	activate timestamp
items[*].activateAt	string	activate time