Add Payment Interface
Developmentadd-payment-interfaceAdd Payment Interface is an Agent Skill for development published in the go-pay/gopay repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Add new payment interfaces to GoPay project following standard workflow - analyze docs, implement code, update documentation and version records. Use when adding WeChat Pay, Alipay or other payment platform APIs.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/go-pay/gopay/blob/HEAD/.claude/skills/add-payment-interface/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/add-payment-interface, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Add Payment Interface
Standardized workflow for adding new payment platform interfaces to the GoPay project.
When to Activate
- Adding new WeChat Pay v3 interfaces
- Adding new Alipay v3 interfaces
- Adding interfaces for other payment platforms
- Updating existing payment interfaces with new capabilities
Standard Workflow
Step 1: Analyze Interface Documentation
Objective: Extract complete interface specifications from official documentation.
Actions:
- Use
WebFetchto retrieve official documentation - Use browser automation (
mcp__browser-automation__*) if interactive navigation needed - Extract:
- HTTP method (GET/POST/PUT/DELETE/PATCH)
- URL path (e.g.,
/v3/med-ins/orders) - Request parameters (name, type, required, description)
- Response parameters (name, type, description)
Example Output:
Interface: 医保自费混合收款下单
Method: POST
Path: /v3/med-ins/orders
Request: mix_pay_type, order_type, appid, openid, ...
Response: mix_trade_no, mix_pay_status, ...
Step 2: Implement Interface Code
Objective: Implement interface following project conventions.
2.1 Add API Path Constants
File: wechat/v3/constant.go or alipay/v3/constant.go
Naming: v3 + ModuleName + ActionName
Example:
// 医保支付
v3MedInsOrder = "/v3/med-ins/orders" // 医保自费混合收款下单 POST
v3MedInsOrderQueryByMixNo = "/v3/med-ins/orders/mix-trade-no/%s" // mix_trade_no 查询 GET
v3MedInsOrderQueryByOutNo = "/v3/med-ins/orders/out-trade-no/%s" // out_trade_no 查询 GET
2.2 Define Data Models
File: Create or update model_*.go (e.g., model_medins.go)
Required structures:
// Response wrapper
type XxxRsp struct {
Code int `json:"-"`
SignInfo *SignInfo `json:"-"`
Response *Xxx `json:"response,omitempty"`
ErrResponse ErrResponse `json:"err_response,omitempty"`
Error string `json:"-"`
}
// Response data
type Xxx struct {
Field1 string `json:"field1"` // 字段说明
Field2 int `json:"field2"` // 字段说明
// ... more fields
}
2.3 Implement Interface Methods
File: Create or update module file (e.g., medins.go)
Method naming: V3 + ModuleName + ActionName
Implementation pattern:
func (c *ClientV3) V3XxxMethod(ctx context.Context, bm gopay.BodyMap) (wxRsp *XxxRsp, err error) {
// 1. Generate authorization
authorization, err := c.authorization(MethodPost, v3ApiPath, bm)
if err != nil {
return nil, err
}
// 2. Send request (use doProdPost for POST, doProdGet for GET)
res, si, bs, err := c.doProdPost(ctx, bm, v3ApiPath, authorization)
if err != nil {
return nil, err
}
// 3. Initialize response
wxRsp = &XxxRsp{Code: Success, SignInfo: si, Response: new(Xxx)}
if res.StatusCode != http.StatusOK {
wxRsp.Code = res.StatusCode
wxRsp.Error = string(bs)
_ = js.UnmarshalBytes(bs, &wxRsp.ErrResponse)
return wxRsp, nil
}
// 4. Parse response
if err = json.Unmarshal(bs, wxRsp.Response); err != nil {
return nil, fmt.Errorf("[%w]: %v, bytes: %s", gopay.UnmarshalErr, err, string(bs))
}
// 5. Verify signature
return wxRsp, c.verifySyncSign(si)
}
Key points:
- POST requests: use
doProdPost - GET requests: use
doProdGet - Path parameters: use
fmt.Sprintfto format URL - Always verify signature with
verifySyncSign
Step 3: Update Documentation
Objective: Document new interfaces in project docs.
3.1 Update API Documentation
File: doc/wechat_v3.md or doc/alipay_v3.md
Location: Appendix section, grouped by functionality
Format:
* <font color='#07C160' size='4'>Module Name</font>
* Interface description: `client.V3MethodName()`
* Interface description: `client.V3MethodName2()`
Example:
* <font color='#07C160' size='4'>医保支付</font>
* 医保自费混合收款下单:`client.V3MedInsOrder()`
* 使用医保自费混合订单号查看下单结果:`client.V3MedInsOrderQueryByMixNo()`
* 使用商户订单号查看下单结果:`client.V3MedInsOrderQueryByOutNo()`
Step 4: Update Version Records
Objective: Record changes in version history.
4.1 Update Version Number
File: constant.go (root directory)
Action: Increment patch version (e.g., v1.5.116 → v1.5.117)
4.2 Update Release Notes
File: release_note.md
Action: Add new version section at the top
Format:
## 版本号:v1.5.xxx
* 修改记录:
* 平台名:新增 功能模块 相关接口。
* client.MethodName(),接口说明。
* client.MethodName2(),接口说明。
Step 5: Commit Changes
Objective: Stage all modified files for commit.
Actions:
# Add all related files
git add constant.go
git add release_note.md
git add doc/wechat_v3.md # or corresponding platform doc
git add wechat/v3/constant.go # or corresponding platform
git add wechat/v3/new_file.go
git add wechat/v3/model_new_file.go
# Check status
git status
# Add any linter-formatted files
git add <formatted_files>
Implementation Example
Case: WeChat Pay v3 Medical Insurance Payment
Documentation: https://pay.weixin.qq.com/doc/v3/merchant/4016781466
Interfaces identified:
- Create medical insurance order - POST
/v3/med-ins/orders - Query by mix trade no - GET
/v3/med-ins/orders/mix-trade-no/{mix_trade_no} - Query by merchant order no - GET
/v3/med-ins/orders/out-trade-no/{out_trade_no}
Files modified:
constant.go- version bump to v1.5.117release_note.md- added v1.5.117 changelogdoc/wechat_v3.md- added medical insurance sectionwechat/v3/constant.go- added 3 API path constantswechat/v3/medins.go- new file with 3 methodswechat/v3/model_medins.go- new file with data structures
Quality Checklist
Before completing:
- Code compiles without errors (
go build ./wechat/v3/...) - All API paths added to constants
- Data models include all documented fields
- Methods follow existing implementation patterns
- Error handling is complete
- Signature verification is included
- API documentation is updated
- Version number is incremented
- Release notes are updated
- All files are staged for commit
Reference Files
- Constants:
wechat/v3/constant.go,alipay/v3/constant.go - Models:
wechat/v3/model_*.go,alipay/v3/model_*.go - Implementations:
wechat/v3/*.go,alipay/v3/*.go - Documentation:
doc/wechat_v3.md,doc/alipay_v3.md - Version:
constant.go,release_note.md
Tools Used
- WebFetch - Retrieve documentation content
- Browser automation - Navigate interactive documentation
- Read - Reference existing implementations
- Write/Edit - Create or modify code files
- Bash - Execute git commands and build verification