Payout Voucher PDF/ZIP API
About 393 wordsAbout 1 min
1. Overview
Description:
- Generate payout voucher PDF files based on payout order numbers(Only when the order status is "Success" or "Failed"). When only one order number is provided, a single PDF file is returned; when multiple orders are provided, a ZIP package containing multiple PDFs is returned.
Request Method:
- HTTP Method:
POST - Content-Type:
application/json
Endpoint:
/common/voucher/pdf
2. Request Parameters
Request Body: JSON
| Parameter | Required | Type | Description |
|---|---|---|---|
| appId | Yes | Long | Business ID (obtained from the backend) |
| orderNos | Yes | List<String> | Payout order number list, must contain at least one order,max 100; single order returns PDF, multiple returns ZIP |
| getFee | No | Integer | Whether to display fee: 0 - do not display, 1 - display, default: 0 |
| isAmount | No | Integer | Amount display type: 0 - use actual credited amount, 1 - use order amount, default: 0 |
| lang | No | String | Voucher language: zh / en, default: zh |
| sign | Yes | String | Signature generated with merchant secret key (same signing rules as other APIs) |
3. Request Examples
3.1 Single Order Example (Returns PDF)
Sample Request Body:
{
"appId": 2065,
"orderNos": [
"1525121020031156560"
],
"getFee": 0,
"isAmount": 0,
"lang": "zh",
"sign": "cvEOw/NyNTvp0NBH+Ef31BP0/UFTEcbkj9Nqh/ek8PqywbbwBKIP5aM5b63BiB8JWxGdVeNvbltMsmKnWVCJOdNVno5xwjJnDFl3NFXy05vIh1OINDPWAbtvm143XrTvv7dD2g1ewrz2Aij9bwM74GvZJwP6QyRMZRjp3rDAMvpxZ/WiASOak9tcp7MPny2wq42irt/4YDY4snjCo8MPqgvhJvjewj0FEjS2YvDED8rmZwCqyW9gqKhYhl101jSLbKQ5rf0WrKZvlc/Y2HZqBQKPjhnOJUJmLe/7gPg6tKzq2pF7FmoxBvGyjQ3sjk9SvyxuD32ugqP1RaI2Q9ukdw=="
}3.2 Multiple Orders Example (Returns ZIP)
Sample Request Body:
{
"appId": 2065,
"orderNos": [
"1525121020031156560",
"1525121020031156561"
],
"getFee": 0,
"isAmount": 0,
"lang": "zh",
"sign": "gpIClDa34j0VE/0SKpy/UCzjqN0i8mTDKhI0gu4oO861ajiRk3C0Ei4RogQmZ5fT5UOVKUK9n7wsyt2psCztuP65tJ8OpOzeiLrtAybQxyiE6Fo56sUMqHok9ubZWp+kZGZnCe2N8uCpxLh39P/NUv/bF7TzpIitdTjYAGI7TG2++YKPqyMnsR0wCu7Aqtk0hN+a8KXXDc+WtGbulP4H257gjD7W6YFDuyLv32MGUyx/VxlbmKN0yyI7D8UFnakrEryIlC4Xi5J2B/8dRfb1l/okMwVI8nRjvCuj0b2ORHHfqefMtHYzWSXtWyoRo/2yxvbaEmckxbyb6e2tfsjLLA=="
}4. Response Description
4.1 Success Response
- HTTP Status Code:
200 - Response Body: Binary file stream
- When
orderNoscontains only one order:- Returns a single PDF file
Content-Typeis usuallyapplication/pdf
- When
orderNoscontains multiple orders:- Returns a ZIP package
Content-Typeis usuallyapplication/zip
- When
Recommendation:
- Determine the file type based on the
Content-Typeresponse header and file size, and save the body as a binary file.- The file name can be defined by the merchant,or by the response header
Content-Disposition,for example: ``attachment;filename*=UTF-8''vouchers_20251229200623.zip`.- The request time for this API interface will increase based on the number of orders, potentially reaching over 30 seconds. Please ensure the stability of the network.
4.2 Error Response
When parameter validation fails, signature verification fails, IP is not in the whitelist, or PDF/ZIP generation fails, the API returns a JSON error structure, for example:
{
"status": "0",
"error": "1001",
"msg": "orderNos can not be empty",
"data": null
}