ISV Integration

1. What is ISV

ISV stands for "Independent Service Provider". Within PayerMax, payment institutions or SaaS service providers that have their own sub-merchant resources are recommended to join as ISVs. After the ISV completes the system integration with PayerMax, it can initiate transaction requests on behalf of the sub-merchants.

2. Use Scenarios

The ISV itself can be an institution with a payment license or a SaaS service provider. Before using the ISV model to connect with PayerMax, please contact the business department to confirm whether the business scenario and user process are appropriate.

3. Process and Role Relationships

4. Supported Integration Mode

Merchants who access PayerMax through the ISV integration are not different from ordinary merchants in terms of supported integration modes, which are cashier payment, direct-API, Front-end Component, PayByLink, and Tokenization.

5. API Parameters

In the ISV integration, ISV as the integrator needs to pay attention to several core parameters:

• spMerchantNo: Refers to the ISV merchant's own merchant ID, which is assigned by PayerMax when registering as an ISV on PayerMax.

• merchantNo: Refers to the merchant ID of the sub-merchant. Sub-merchants generally need to register in PayerMax, which will assign it to the ISV merchant and provide it to the merchant when initiating a transaction.

• appId: It represents the application of the system integrator, and the key is bound to the appId. For ISV service providers, the system integration is done by the ISV service provider, so the appId sent in the transaction interface is the appId of the ISV service provider.

• Auth Token: When an ISV merchant and its sub-merchants complete their registration in PayerMax, PayerMax will generate an Auth Token based on the binding relationship between the two. If an ISV has multiple sub-merchants, PayerMax will allocate multiple Auth Tokens to distinguish transactions from different sub-merchants. When the ISV service provider requests a transaction on behalf of a sub-merchant, it sends merchant_auth_token=authorized Auth Token in the HTTP Header.

6. Parameter Transfer Guide

Request Header: Pass in merchant_auth_token, the example is as follows:

"headers": {
	"Accept": "application/json",
	"merchant_auth_token": "2024071***73504",// Required
	"sign": "Please refer to Config Settings and Signature Rules: https://docs-v2.payermax.com/en/doc-center/developer/config-settings.html",// Required
	"Content-Type": "application/json"
}

Request Body: The examples are as follows. For detailed API documentation, please refer to Cashier Payment API.

Note:

There is no spMerchantNo in the API, please refer to the Body below.

{
	"requestTime": "2024-08-12T14:59:53.279+08:00",
	"version": "1.1",
	"appId": "Need to be replaced with the appid of the ISV service provider",
	"merchantNo": "Need to be replaced with the sub-merchant number",
	"spMerchantNo": "Need to be replaced with the ISV service provider merchant number",
	"keyVersion": "1",
	"data": {
		"outTradeNo": "20240812025xxxx",
		"userId": "704138842",
		"subject": "Product Description",
		"totalAmount": 700,
		"country": "KR",
		"currency": "KRW",
		"language": "en",
		"frontCallbackURL": "https://www.baidu.com",
		"notifyUrl": "https://www.baidu.com"
	}
}

Parameter	Type	If Required	Length Max.	Description	Example
version	String	M	8	API version. Current value: 1.1	1.1
keyVersion	String	M	8	Signature Algorithm Version。Current Value：1
requestTime	String	M	32	Request time，Comply with rfc3339 specification, format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX	2022-01-22T10:00:00.500+08:00
appId	String	M	64	Integration App Id of the integrator	46153e2b787241ae8b01857bb087d1bd
spMerchantNo	String	M	15	Merchant ID of the ISV service provider
merchantNo	String	M	15	Merchant Id, the unique identifier generated when the merchant signs the contract with PayerMax	010229810189301
+data	Object			Please refer to the specific fields under each service interface
「+......