Subscription Integration Guide

🌐 Language Switch / 语言切换

1. Card Subscription

Card subscription is supported across all three products: Direct API, Drop-in, and LinkPay. The first transaction completes card binding and authorizaition, gererating a token. Subsequent charges are initiated using the saved token without requiring the user to re-enter card details.

1.1 Card Subscription via Direct API

Use the POST /payment endpoint. Set recurringProcessingModel: "Subscription" in the first payment to complete card binding and obtain a token.

1.1.1 Initial Card Binding & Payment

Request example:

{
    "merchantTransInfo": {
        "merchantTransTime": "{{merchantTransTime}}"
    },
    "transAmount": {
        "currency": "HKD",
        "value": "100"
    },
    "paymentMethod": {
        "type": "card",
        "card": {
            "cardInfo": {
                "cardNumber": "4895330111111119",
                "expiryDate": "1231"
            }
        },
        "recurringProcessingModel": "Subscription"
    },
    "userInfo": {
        "reference": "your_user_reference"
    },
    "captureAfterHours": "0",
    "allowAuthentication": true,
    "returnURL": "https://www.evonetglobal.com",
    "webhook": "https://webhook.merchant.com"
}

Key fields:

Field	Type	Description	Notes
`paymentMethod.type`	string	Payment method	Set to `card` for card subscription
`paymentMethod.recurringProcessingModel`	string	Transaction type	`Subscription`, `Unscheduled`
`userInfo.reference`	string	Unique user identifier in merchant system	Used to bind card info and token to the user
`allowAuthentication`	boolean	Enable 3DS authentication	Recommend `false` for subscription (MIT)

Key response fields:

Field	Type	Description
`paymentMethod.recurringReference`	string	Recurring agreement ID
`paymentMethod.token.value`	string	Token value for subsequent charges
`paymentMethod.paymentMethodVariant`	string	Indicates `Recurring`

API Reference: POST /payment , GET /payment/{merchantTransID}

1.1.2 Subsequent Subscription Charges

Use the saved token.value, changing paymentMethod.type to token :

{ 
    "merchantTransInfo": {
        "merchantTransTime": "{{merchantTransTime}}"
    },
    "transAmount": {
        "currency": "HKD",
        "value": "100"
    },
    "paymentMethod": {
        "type": "token",
        "token":{
            "value":"pmt_9a4a8a6355c044ce80903ce3d860eacb"
        },
        "recurringProcessingModel": "Subscription"
    },
    "captureAfterHours": "0",
    "allowAuthentication": false,
    "returnURL": "https://www.evonetglobal.com",
    "webhook": "https://webhook.merchant.com"
}

1.2 Card Subscription via Drop-in

Use the Drop-in pre-built UI component to implement subscription without building a custom payment page.

1.2.1 Obtain sessionID

Pass subscription parameters when calling POST /interaction :

{
    "userInfo": {
        "reference": "your_user_reference"
    },
    "paymentMethod": {
        "recurringProcessingModel": "Subscription"
    }
}

Extract sessionID from the response and pass it to the frontend DropInSDK.

API Reference: POST /interaction

1.2.2 Retrieve Token

Obtain token.value from the webhook notification or GET /interaction/{merchantOrderID} query endpoint. Save it and associate it with userInfo.reference.

API Reference: GET /interaction/{merchantOrderID}

1.2.3 Subsequent Subscription Charges

Same as Direct API — call POST /payment :

{
    "paymentMethod": {
        "token": {
            "value": "previously-saved-token"
        },
        "recurringProcessingModel": "Subscription"
    }
}

1.3 Card Subscription via LinkPay

Use LinkPay payment links to implement subscription. Users click the link, select pay by card, and complete card binding.

1.3.1 Create LinkPay Payment Link

Pass subscription parameters when calling POST /interaction :

{
    "userInfo": {
        "reference": "your_user_reference"
    },
    "paymentMethod": {
        "recurringProcessingModel": "Subscription"
    }
}

After obtaining the payment link (LinkUrl), redirect the user to the LinkPay payment page.

API Reference: POST /payment

1.3.2 Retrieve Token

Obtain token.value from the webhook notification or GET /interaction/{merchantOrderID} query endpoint. Save it and associate it with userInfo.reference.

API Reference: GET /interaction/{merchantOrderID}

1.3.3 Subsequent Subscription Charges

Same as Direct API — call POST /payment :

{
    "paymentMethod": {
        "token": {
            "value": "previously-saved-token"
        },
        "recurringProcessingModel": "Subscription"
    }
}

2. e-Wallet Subscription

Supported Wallets:

Region	Payment Methods
Philippines	GCash / Maya
Indonesia	DANA
Thailand	Truemoney / Rabbit Line Pay
Malaysia	TNG / Boost
South Korea	Kakaopay / Naver Pay
Singapore	GrabPay
Hong Kong SAR	AlipayHK
Mainland China	Alipay

2.1 e-Wallet Subscription

The first binding uses POST /paymentMethod to complete wallet linkage and user authorization; subsequent charges use the saved token.

2.1.1 First Binding — POST /paymentMethod

Set paymentMethod.type to e-wallet, recurringProcessingModel to Subscription, and specify the wallet brand:

{
    "merchantTransInfo": {
        "merchantTransTime": "{{merchantTransTime}}"
    },
    "transAmount": {
        "currency": "THB",
        "value": "100"
    },
    "paymentMethod": {
        "type": "e-wallet",
        "e-wallet": {
            "paymrnyBrand": "TrueMoney_Wallet"
        },
        "recurringProcessingModel": "Subscription"
    },
    "userInfo": {
        "reference": "your_user_reference"
    },
		"transInitiator": {
    	"userCreateIP": "222.71.133.101",
    	"platform": "WEB",
		},
    "returnURL": "https://www.evonetglobal.com",
    "webhook": "https://webhook.merchant.com"
}

Key fields:

Field	Type	Description	Notes
`paymentMethod.type`	string	Payment method	Always `e-wallet` for wallet subscription
`paymentMethod.e-wallet.paymentBrand`	string	Wallet brand	e.g. `TrueMoney_Wallet`, `GCash`, `Dana`
`paymentMethod.recurringProcessingModel`	string	Transaction type	`Subscription`
`userInfo.reference`	string	Unique user identifier	Used for token binding
`paymentMethod.status`	string	`tokenized_pending`	Awaiting user authorization

API Reference: POST /paymentMethod

2.1.2 User Authorization

Redirect the user to action.redirectData.url to complete authorization on the wallet side.

2.1.3 Retrieve Token

Obtain token.value from the webhook notification or GET /paymentMethod?merchantTransID={{}} query endpoint. Save it and associate it with userInfo.reference.

API Reference: GET /paymentMethod?merchantTransID={}

2.1.4 Subsequent Subscription Charges — POST /payment

{
    "paymentMethod": {
        "token": {
            "value": "previously-saved-token"
        },
        "recurringProcessingModel": "Subscription"
    }
}

一、卡订阅

卡订阅支持通过 Direct API、Drop-in、LinkPay 三种方式实现。首次交易完成绑卡授权后生成 token，后续使用 token 发起免密扣款。

1.1 Direct API 实现卡订阅

通过 POST /payment 接口，首次支付时设置 recurringProcessingModel: "Subscription" 完成绑卡并获取 token。

1.1.1 首次绑卡支付

请求示例：

{
    "merchantTransInfo": {
        "merchantTransTime": "{{merchantTransTime}}"
    },
    "transAmount": {
        "currency": "HKD",
        "value": "100"
    },
    "paymentMethod": {
        "type": "card",
        "card": {
            "cardInfo": {
                "cardNumber": "4895330111111119",
                "expiryDate": "1231"
            }
        },
        "recurringProcessingModel": "Subscription"
    },
    "userInfo": {
        "reference": "your_user_reference"
    },
    "captureAfterHours": "0",
    "allowAuthentication": true,
    "returnURL": "https://www.evonetglobal.com",
    "webhook": "https://webhook.merchant.com"
}

关键字段：

字段	类型	描述	注意事项
`paymentMethod.type`	string	支付方式	卡订阅设为 `card`
`paymentMethod.recurringProcessingModel`	string	交易类型	`Subscription`（订阅）、`Unscheduled`（代扣）
`userInfo.reference`	string	商户系统中的用户唯一标识	用于将卡信息及 token 绑定到用户账户
`allowAuthentication`	boolean	是否启用 3DS 认证	后续扣款场景建议 `false`（MIT 免密交易）

响应中关键字段：

字段	类型	描述
`paymentMethod.recurringReference`	string	定期扣款协议 ID
`paymentMethod.token.value`	string	Token 值，用于后续扣款
`paymentMethod.paymentMethodVariant`	string	标识为 `Recurring`

字段规范: POST /payment，GET /payment/{merchantTransID}

1.1.2 后续订阅扣款

使用保存的 token.value 发起后续扣款，paymentMethod.type 改为 token：

{ 
    "merchantTransInfo": {
        "merchantTransTime": "{{merchantTransTime}}"
    },
    "transAmount": {
        "currency": "HKD",
        "value": "100"
    },
    "paymentMethod": {
        "type": "token",
        "token":{
            "value":"pmt_9a4a8a6355c044ce80903ce3d860eacb"
        },
        "recurringProcessingModel": "Subscription"
    },
    "captureAfterHours": "0",
    "allowAuthentication": false,
    "returnURL": "https://www.evonetglobal.com",
    "webhook": "https://webhook.merchant.com"
}

1.2 Drop-in 实现卡订阅

通过 Drop-in 预构建 UI 组件实现订阅，前端无需自行开发支付页面。

1.2.1 获取 sessionID

调用 POST /interaction 时传入订阅参数：

{
    "userInfo": {
        "reference": "your_user_reference"
    },
    "paymentMethod": {
        "recurringProcessingModel": "Subscription"
    }
}

从响应中获取 sessionID，传递给前端 DropInSDK。

字段规范: POST /interaction

1.2.2 获取 Token

支付完成后，从 webhook 回调通知或 GET /interaction/{merchantOrderID} 查询接口中获取 token.value，保存并与 userInfo.reference 关联。

字段规范：GET /interaction/{merchantOrderID}

1.2.3 后续订阅扣款

与 Direct API 相同，调用 POST /payment：

{
    "paymentMethod": {
        "token": {
            "value": "之前保存的token值"
        },
        "recurringProcessingModel": "Subscription"
    }
}

1.3 LinkPay 实现卡订阅

通过 LinkPay 支付链接实现订阅，用户点击链接后选择卡支付完成绑卡。

1.3.1 创建 LinkPay 支付链接

调用 POST /interaction 时传入订阅参数：

{
    "userInfo": {
        "reference": "your_user_reference"
    },
    "paymentMethod": {
        "recurringProcessingModel": "Subscription"
    }
}

获取支付链接（LinkUrl）后，将用户重定向至 LinkPay 支付页面。

字段规范：POST /interaction

1.3.2 获取 Token

支付完成后，从 webhook 回调通知或 GET /interaction/{merchantOrderID} 查询接口中获取 token.value，保存并与 userInfo.reference 关联。

字段规范：GET /interaction/{merchantOrderID}

1.3.4 后续订阅扣款

与 Direct API 相同，调用 POST /payment：

{
    "paymentMethod": {
        "token": {
            "value": "之前保存的token值"
        },
        "recurringProcessingModel": "Subscription"
    }
}

二、钱包订阅

支持的钱包：

地区	支付方式
菲律宾	GCash / Maya
印尼	DANA
泰国	Truemoney / Rabbit Line Pay
马来	TNG / Boost
韩国	Kakaopay / Naver Pay
新加坡	GrabPay
中国香港	AlipayHK
中国大陆	Alipay

2.1 实现钱包订阅

首次通过 POST /paymentMethod 完成钱包绑定与用户授权，后续使用 token 发起扣款。

2.1.1 首次绑定 — POST /paymentMethod

paymentMethod.type 设为 e-wallet，recurringProcessingModel 设为 Subscription，并指定钱包品牌：

{
    "merchantTransInfo": {
        "merchantTransTime": "{{merchantTransTime}}"
    },
    "transAmount": {
        "currency": "THB",
        "value": "100"
    },
    "paymentMethod": {
        "type": "e-wallet",
        "e-wallet": {
            "paymrnyBrand": "TrueMoney_Wallet"
        },
        "recurringProcessingModel": "Subscription"
    },
    "userInfo": {
        "reference": "your_user_reference"
    },
		"transInitiator": {
    	"userCreateIP": "222.71.133.101",
    	"platform": "WEB",
		},
    "returnURL": "https://www.evonetglobal.com",
    "webhook": "https://webhook.merchant.com"
}

关键字段：

字段	类型	描述	注意事项
`paymentMethod.type`	string	支付方式	钱包订阅 `e-wallet`
`paymentMethod.e-wallet.paymentBrand`	string	钱包品牌	如 `TrueMoney_Wallet`、`GCash`、`Dana` 等
`paymentMethod.recurringProcessingModel`	string	交易类型	`Subscription`
`userInfo.reference`	string	商户用户唯一标识	用于绑定 token
`paymentMethod.status`	string	`tokenized_pending`	等待用户授权

字段规范：POST /paymentMethod

2.1.2 用户授权

将用户重定向至 action.redirectData.url，在钱包端完成授权。

2.1.3 获取 Token

从 webhook 回调通知或 GET /interaction/{merchantOrderID} 查询接口中获取 token.value，保存并与 userInfo.reference 关联。

字段规范： GET /paymentMethod?merchantTransID={}

2.1.4 后续订阅扣款 — POST /payment

{
    "paymentMethod": {
        "token": {
            "value": "之前保存的token值"
        },
        "recurringProcessingModel": "Subscription"
    }
}