0
# Payment APIs
1

2
Comprehensive payment system for WeChat Mini Programs, including WeChat Pay, global payments, plugin payments, and merchant transfers.
3

4
## Capabilities
5

6
### WeChat Payment
7

8
Core WeChat payment functionality for processing transactions in WeChat Mini Programs.
9

10
```typescript { .api }
11
/**
12
 * Launch WeChat payment process
13
 * @param option - Payment parameters from unified order API
14
 */
15
function requestPayment<T extends RequestPaymentOption = RequestPaymentOption>(
16
  option: T
17
): PromisifySuccessResult<T, RequestPaymentOption>;
18

19
interface RequestPaymentOption {
20
  /** Payment timestamp */
21
  timeStamp: string;
22
  /** Random string, length less than 32 characters */
23
  nonceStr: string;
24
  /** Unified order API prepay_id parameter, format: prepay_id=*** */
25
  package: string;
26
  /** Signature algorithm, default MD5 */
27
  signType?: 'MD5' | 'HMAC-SHA256';
28
  /** Payment signature */
29
  paySign: string;
30
  /** Success callback */
31
  success?(res: RequestPaymentSuccessCallbackResult): void;
32
  /** Failure callback */
33
  fail?(res: any): void;
34
  /** Completion callback */
35
  complete?(res: any): void;
36
}
37

38
interface RequestPaymentSuccessCallbackResult {
39
  /** Success message */
40
  errMsg: string;
41
}
42
```
43

44
**Usage Examples:**
45

46
```typescript
47
// Basic WeChat payment
48
wx.requestPayment({
49
  timeStamp: '1414561699',
50
  nonceStr: 'QVqbvGRU',
51
  package: 'prepay_id=u802345jgfjsdfgsdg888',
52
  signType: 'MD5',
53
  paySign: '70EA570631E4BB79628FBCA90534C63FF7FADD89',
54
  success(res) {
55
    console.log('Payment successful:', res);
56
  },
57
  fail(err) {
58
    console.error('Payment failed:', err);
59
  }
60
});
61

62
// With cloud development
63
wx.cloud.callFunction({
64
  name: 'payment',
65
  data: { 
66
    amount: 100,
67
    description: 'Product purchase'
68
  },
69
  success: res => {
70
    const payment = res.result.payment;
71
    wx.requestPayment({
72
      ...payment,
73
      success(res) {
74
        console.log('Payment completed:', res);
75
      }
76
    });
77
  }
78
});
79
```
80

81
### Order Payment (Transaction Component)
82

83
Payment for custom transaction component scenarios with order validation.
84

85
```typescript { .api }
86
/**
87
 * Payment for transaction component orders
88
 * @param args - Order payment parameters with validation
89
 */
90
function requestOrderPayment<T extends RequestOrderPaymentOption = RequestOrderPaymentOption>(
91
  args: T
92
): PromisifySuccessResult<T, RequestOrderPaymentOption>;
93

94
interface RequestOrderPaymentOption {
95
  /** Payment timestamp */
96
  timeStamp: string;
97
  /** Random string */
98
  nonceStr: string;
99
  /** Prepay package */
100
  package: string;
101
  /** Signature type */
102
  signType: string;
103
  /** Payment signature */
104
  paySign: string;
105
  /** Order information for validation */
106
  orderInfo?: OrderInfo;
107
  /** Success callback */
108
  success?(res: RequestOrderPaymentSuccessCallbackResult): void;
109
  /** Failure callback */
110
  fail?(res: any): void;
111
  /** Completion callback */
112
  complete?(res: any): void;
113
}
114

115
interface OrderInfo {
116
  /** Order ID */
117
  order_id: string;
118
  /** Product information */
119
  product_info?: ProductInfo;
120
  /** Payment info for B2B scenarios */
121
  requestPaymentInfo?: RequestPaymentInfo;
122
}
123

124
interface RequestOrderPaymentSuccessCallbackResult {
125
  /** Success message */
126
  errMsg: string;
127
}
128
```
129

130
### Common Payment
131

132
Unified payment interface for various payment scenarios including retail and service payments.
133

134
```typescript { .api }
135
/**
136
 * Common payment interface for unified payment scenarios
137
 * @param option - Common payment configuration
138
 */
139
function requestCommonPayment(option: RequestCommonPaymentOption): void;
140

141
interface RequestCommonPaymentOption {
142
  /** Signed payment data in JSON format */
143
  signData: string;
144
  /** Payment mode: retail goods, service fees, etc. */
145
  mode: 'retail_pay_goods' | 'retail_pay_order' | 'service_fee';
146
  /** Payment description */
147
  description: string;
148
  /** Payment amount information */
149
  amount: PaymentAmount;
150
  /** Additional payment parameters */
151
  attach?: string;
152
  /** Success callback */
153
  success?(res: RequestCommonPaymentSuccessCallbackResult): void;
154
  /** Failure callback */
155
  fail?(res: any): void;
156
  /** Completion callback */
157
  complete?(res: any): void;
158
}
159

160
interface PaymentAmount {
161
  /** Total amount in cents */
162
  total: number;
163
  /** Currency code */
164
  currency: string;
165
}
166

167
interface RequestCommonPaymentSuccessCallbackResult {
168
  /** Success message */
169
  errMsg: string;
170
}
171
```
172

173
**Usage Examples:**
174

175
```typescript
176
wx.requestCommonPayment({
177
  signData: JSON.stringify({
178
    mchid: '1234567890',
179
    out_trade_no: 'order_12345',
180
    appid: 'wxapp123456'
181
  }),
182
  mode: 'retail_pay_goods',
183
  description: 'Product purchase',
184
  amount: {
185
    total: 10000, // 100.00 yuan in cents
186
    currency: 'CNY'
187
  },
188
  success(res) {
189
    console.log('Common payment success:', res);
190
  },
191
  fail({ errMsg, errno }) {
192
    console.error('Payment failed:', errMsg, errno);
193
  }
194
});
195
```
196

197
### Global Payment
198

199
International payment system supporting multiple payment methods and regions.
200

201
```typescript { .api }
202
/**
203
 * Create global payment object for international transactions
204
 * @param option - Global payment configuration
205
 */
206
function createGlobalPayment(option: CreateGlobalPaymentOption): GlobalPayment;
207

208
interface CreateGlobalPaymentOption {
209
  /** Merchant region code */
210
  mchRegion: string;
211
  /** Sandbox mode for testing */
212
  isSandbox?: boolean;
213
}
214

215
interface GlobalPayment {
216
  /** Selected payment method key */
217
  methodKey?: string;
218
  
219
  /**
220
   * Open payment method picker
221
   * @param option - Picker configuration
222
   */
223
  openMethodPicker(option: OpenMethodPickerOption): Promise<OpenMethodPickerResult>;
224
  
225
  /**
226
   * Process global payment after method selection
227
   * @param option - Global payment parameters
228
   */
229
  requestGlobalPayment(option: RequestGlobalPaymentOption): Promise<RequestGlobalPaymentResult>;
230
}
231

232
interface OpenMethodPickerOption {
233
  /** Payment amount */
234
  amount: number;
235
  /** Currency code */
236
  currency: string;
237
  /** Merchant information */
238
  merchantInfo?: MerchantInfo;
239
}
240

241
interface RequestGlobalPaymentOption {
242
  /** Payment ID from pre-order */
243
  paymentId: string;
244
  /** Prepay information */
245
  prepayInfo: any;
246
}
247
```
248

249
**Usage Examples:**
250

251
```typescript
252
// Global payment workflow
253
const globalPayment = wx.createGlobalPayment({ 
254
  mchRegion: 'SG', 
255
  isSandbox: true 
256
});
257

258
try {
259
  // Step 1: Let user select payment method
260
  const pickerResult = await globalPayment.openMethodPicker({
261
    amount: 100.00,
262
    currency: 'SGD',
263
    merchantInfo: {
264
      name: 'Example Store',
265
      region: 'Singapore'
266
    }
267
  });
268
  
269
  console.log('Selected method:', pickerResult.methodKey);
270
  
271
  // Step 2: Process payment (for non-WeChat methods)
272
  if (pickerResult.methodKey !== 'wechat_pay') {
273
    // Create pre-order with third-party payment gateway
274
    const preOrderResult = await createTPGPreOrder({
275
      amount: 100.00,
276
      currency: 'SGD'
277
    });
278
    
279
    // Step 3: Complete payment
280
    const paymentResult = await globalPayment.requestGlobalPayment({
281
      paymentId: preOrderResult.payment_id,
282
      prepayInfo: preOrderResult.prepay_info
283
    });
284
    
285
    console.log('Global payment completed:', paymentResult);
286
  }
287
} catch (error) {
288
  console.error('Global payment error:', error);
289
}
290
```
291

292
### Plugin Payment
293

294
Payment functionality for WeChat Mini Program plugins.
295

296
```typescript { .api }
297
/**
298
 * Process payment in plugin context
299
 * @param option - Plugin payment configuration
300
 */
301
function requestPluginPayment(option: RequestPluginPaymentOption): void;
302

303
interface RequestPluginPaymentOption {
304
  /** Plugin version */
305
  version: 'release' | 'trial' | 'dev';
306
  /** Payment fee amount */
307
  fee: number;
308
  /** Payment arguments object */
309
  paymentArgs: Record<string, any>;
310
  /** Currency type */
311
  currencyType: 'CNY';
312
  /** Success callback */
313
  success?(res: any): void;
314
  /** Failure callback */
315
  fail?(res: any): void;
316
  /** Completion callback */
317
  complete?(res: any): void;
318
}
319
```
320

321
### Merchant Transfer
322

323
Direct transfer functionality for merchant-to-user transfers.
324

325
```typescript { .api }
326
/**
327
 * Process merchant transfer to user
328
 * @param option - Transfer configuration
329
 */
330
function requestMerchantTransfer(option: RequestMerchantTransferOption): void;
331

332
interface RequestMerchantTransferOption {
333
  /** Merchant ID */
334
  mchId: string;
335
  /** Sub-merchant ID */
336
  subMchId?: string;
337
  /** Application ID */
338
  appId: string;
339
  /** Sub-application ID */
340
  subAppId?: string;
341
  /** Transfer package data */
342
  package: string;
343
  /** Success callback */
344
  success?(res: any): void;
345
  /** Failure callback */
346
  fail?(res: any): void;
347
  /** Completion callback */
348
  complete?(res: any): void;
349
}
350
```
351

352
### Hong Kong Offline Payment
353

354
Specialized payment interface for Hong Kong offline payment scenarios.
355

356
```typescript { .api }
357
/**
358
 * Open Hong Kong offline payment view
359
 * @param option - HK offline payment parameters
360
 */
361
function openHKOfflinePayView(option: OpenHKOfflinePayViewOption): void;
362

363
interface OpenHKOfflinePayViewOption {
364
  /** Payment timestamp */
365
  timeStamp: string;
366
  /** Random string */
367
  nonceStr: string;
368
  /** Payment package */
369
  package: string;
370
  /** Signature type, must be SHA1 */
371
  signType: 'SHA1';
372
  /** Payment signature */
373
  paySign: string;
374
  /** Success callback */
375
  success?(res: any): void;
376
  /** Failure callback */
377
  fail?(res: any): void;
378
  /** Completion callback */
379
  complete?(res: any): void;
380
}
381
```
382

383
**Usage Examples:**
384

385
```typescript
386
// Hong Kong offline payment
387
wx.openHKOfflinePayView({
388
  timeStamp: '1414561699',
389
  nonceStr: 'QVqbvGRU',
390
  package: 'prepay_id=u802345jgfjsdfgsdg888',
391
  signType: 'SHA1',
392
  paySign: '70EA570631E4BB79628FBCA90534C63FF7FADD89',
393
  success(res) {
394
    console.log('HK offline payment opened:', res);
395
  }
396
});
397

398
// Plugin payment
399
wx.requestPluginPayment({
400
  version: 'release',
401
  fee: 100, // 1.00 yuan
402
  paymentArgs: {
403
    productId: 'product_123',
404
    description: 'Premium feature unlock'
405
  },
406
  currencyType: 'CNY',
407
  success(res) {
408
    console.log('Plugin payment successful:', res);
409
  },
410
  fail(err) {
411
    console.error('Plugin payment failed:', err);
412
  }
413
});
414

415
// Merchant transfer
416
wx.requestMerchantTransfer({
417
  mchId: '1234567890',
418
  appId: 'wxapp123456',
419
  package: 'transfer_data_package',
420
  success(res) {
421
    console.log('Transfer initiated:', res);
422
  }
423
});
424
```
425

426
## Types
427

428
```typescript { .api }
429
interface ProductInfo {
430
  /** Product name */
431
  name: string;
432
  /** Product description */
433
  description?: string;
434
  /** Product price */
435
  price: number;
436
  /** Product quantity */
437
  quantity: number;
438
}
439

440
interface RequestPaymentInfo {
441
  /** Random string, length less than 32 characters */
442
  nonceStr?: string;
443
  /** Prepay package from unified order API */
444
  package?: string;
445
  /** Payment signature */
446
  paySign?: string;
447
  /** Signature type */
448
  signType?: string;
449
  /** Payment timestamp */
450
  timeStamp?: string;
451
}
452

453
interface MerchantInfo {
454
  /** Merchant name */
455
  name: string;
456
  /** Merchant region */
457
  region: string;
458
  /** Merchant contact */
459
  contact?: string;
460
}
461

462
interface OpenMethodPickerResult {
463
  /** Selected payment method key */
464
  methodKey: string;
465
  /** Method display name */
466
  methodName?: string;
467
}
468

469
interface RequestGlobalPaymentResult {
470
  /** Payment result status */
471
  status: 'success' | 'failed' | 'pending';
472
  /** Transaction ID */
473
  transactionId?: string;
474
  /** Error message if failed */
475
  errorMsg?: string;
476
}
477
```