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

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant User as End User
    participant SubMerchant as Sub-merchant
    participant ISVMerechant as ISV Merchant
    participant PM as PayerMax

    %% Business Integration Phase
    SubMerchant->>ISVMerechant: 1. Business association
    ISVMerechant->>PM: 2. System integration of payment services
    PM-->>SubMerchant: 3. Provide payment services

    %% Payment Initiation Phase
    User->>SubMerchant: 4. Initiate payment
    SubMerchant->>ISVMerechant: 5. Request payment
    ISVMerechant->>PM: 6. Initiate payment

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.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryTextColor': '#fff', 'edgeLabelBackground':'#ffffff00'}}}%%
graph LR
    %% 定义一个样式类
    classDef myStyle fill:#0056b3,stroke:#004085,stroke-width:1px,color:#fff,font-weight:bold;

    %% --- 这里是修改点 ---
    %% A( ) 表示圆角矩形
    A(ISV: 
spMerchantNo, appid)
    %% -------------------
    
    %% 使用子图，将子商户锁定在同一垂直列，确保平行
    subgraph SubMerchants [" "]
        %% 子商户使用 ( ) 圆角矩形
        B("Sub Merchant 01:
MerchantNo, merchant_auth_token_01")
        C("Sub Merchant 02:
MerchantNo, merchant_auth_token_02")
        D("Sub Merchant 03:
MerchantNo, merchant_auth_token_03")
    end

    %% 连接
    A --- B
    A --- C
    A --- D

    %% 应用样式
    class A,B,C,D myStyle;

    %% 隐藏子图的边框
    style SubMerchants fill:none,stroke:none;

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
「+......