支付
退款查询
POST
/
v2
/
payments
/
open
/
api
/
refund
/
query
退款查询
curl --request POST \
--url https://gate.uat.payloco.com/gateway/v2/payments/open/api/refund/query \
--header 'Content-Type: application/json' \
--header 'signature: <api-key>' \
--data '
{
"charset": "UTF-8",
"version": "2.0.0",
"signType": "RSA",
"memberId": "2023010558663764",
"merchantId": "2023010558663764",
"requestTime": "2026-05-24T14:29:32.682+08:00",
"keyVersion": "1",
"data": {
"merchantOrderId": "1780673140561",
"orderId": "1929851221343618"
}
}
'import requests
url = "https://gate.uat.payloco.com/gateway/v2/payments/open/api/refund/query"
payload = {
"charset": "UTF-8",
"version": "2.0.0",
"signType": "RSA",
"memberId": "2023010558663764",
"merchantId": "2023010558663764",
"requestTime": "2026-05-24T14:29:32.682+08:00",
"keyVersion": "1",
"data": {
"merchantOrderId": "1780673140561",
"orderId": "1929851221343618"
}
}
headers = {
"signature": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {signature: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
charset: 'UTF-8',
version: '2.0.0',
signType: 'RSA',
memberId: '2023010558663764',
merchantId: '2023010558663764',
requestTime: '2026-05-24T14:29:32.682+08:00',
keyVersion: '1',
data: {merchantOrderId: '1780673140561', orderId: '1929851221343618'}
})
};
fetch('https://gate.uat.payloco.com/gateway/v2/payments/open/api/refund/query', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://gate.uat.payloco.com/gateway/v2/payments/open/api/refund/query",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'charset' => 'UTF-8',
'version' => '2.0.0',
'signType' => 'RSA',
'memberId' => '2023010558663764',
'merchantId' => '2023010558663764',
'requestTime' => '2026-05-24T14:29:32.682+08:00',
'keyVersion' => '1',
'data' => [
'merchantOrderId' => '1780673140561',
'orderId' => '1929851221343618'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"signature: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://gate.uat.payloco.com/gateway/v2/payments/open/api/refund/query"
payload := strings.NewReader("{\n \"charset\": \"UTF-8\",\n \"version\": \"2.0.0\",\n \"signType\": \"RSA\",\n \"memberId\": \"2023010558663764\",\n \"merchantId\": \"2023010558663764\",\n \"requestTime\": \"2026-05-24T14:29:32.682+08:00\",\n \"keyVersion\": \"1\",\n \"data\": {\n \"merchantOrderId\": \"1780673140561\",\n \"orderId\": \"1929851221343618\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("signature", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://gate.uat.payloco.com/gateway/v2/payments/open/api/refund/query")
.header("signature", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"charset\": \"UTF-8\",\n \"version\": \"2.0.0\",\n \"signType\": \"RSA\",\n \"memberId\": \"2023010558663764\",\n \"merchantId\": \"2023010558663764\",\n \"requestTime\": \"2026-05-24T14:29:32.682+08:00\",\n \"keyVersion\": \"1\",\n \"data\": {\n \"merchantOrderId\": \"1780673140561\",\n \"orderId\": \"1929851221343618\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://gate.uat.payloco.com/gateway/v2/payments/open/api/refund/query")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["signature"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"charset\": \"UTF-8\",\n \"version\": \"2.0.0\",\n \"signType\": \"RSA\",\n \"memberId\": \"2023010558663764\",\n \"merchantId\": \"2023010558663764\",\n \"requestTime\": \"2026-05-24T14:29:32.682+08:00\",\n \"keyVersion\": \"1\",\n \"data\": {\n \"merchantOrderId\": \"1780673140561\",\n \"orderId\": \"1929851221343618\"\n }\n}"
response = http.request(request)
puts response.read_body{
"code": "00000003",
"message": "处理中",
"traceId": "33fae7b7aed1233f",
"data": {
"merchantId": "2023010558663764",
"merchantOrderId": "20230105586637641001",
"oriMerchantOrderId": "string",
"status": "PENDING",
"createTime": "2025-01-31T06:57:10+0000",
"completeTime": "2025-01-31T06:57:10+0000",
"orderId": "TR1654005852065107968",
"refundAmount": 100.01,
"refundCurrency": "string",
"resultCode": "string",
"resultMsg": "string"
}
}授权
加签（Signature）
加签是 Payloco 开放平台与商户之间用于保障报文完整性和防篡改的安全机制。
适用场景
- 商户请求 Payloco：商户使用自身私钥对请求报文进行加签。
- Payloco 返回响应：商户使用 Payloco 公钥 对响应报文进行验签。
加签规则（商户请求端）
商户需对 HTTP 请求的 Body 进行签名，具体步骤如下：
1. 计算签名（SHA256withRSA）
Signature signature = Signature.getInstance("SHA256withRSA"); signature.initSign(merchantPrivateKey); // 必须使用 UTF-8 编码 byte[] bodyBytes = requestBody.getBytes(StandardCharsets.UTF_8); signature.update(bodyBytes); byte[] signedBytes = signature.sign();
2. 将加签内容进行 Base64 编码；
String signature = Base64.getEncoder().encodeToString(signedHash);
3. 将编码后的内容放在请求头部 signature 参数中。
POST /v2/payments/open/api/pay HTTP/1.1 Content-Type: application/json signature: MIIC8jCCAdqgAwIBAgI...
请求体
application/json
请求数据体
交互数据的编码【utf-8】
示例:
"UTF-8"
接口版本，当前版本为【2.0.0】,目前只能传2.0.0，不能不传
Maximum string length:
8示例:
"2.0.0"
报文签名类型
示例:
"RSA"
机构号
示例:
"2023010558663764"
商户号
Maximum string length:
32示例:
"2023010558663764"
请求时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ssSSS+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2026-05-20T13:29:35.262+08:00表示，北京时间2026年5月20日13点29分35秒。
Maximum string length:
32示例:
"2026-05-24T14:29:32.682+08:00"
密钥版本 当前值为：1
Maximum string length:
8示例:
"1"
响应
200 - application/json
OK
响应状态码，’00000000’代表成功。’00000003’代表受理中,只代表接口请求成功，不代表订单状态。
示例:
"00000003"
返回描述，’SUCCESS.’ 。只代表接口请求成功，不代表订单状态。
示例:
"SUCCESS"
请求消息唯一标识。traceId为本次调用产生的流水号，接口调用异常，可以提供此流水号用于排查问题。
示例:
"33fae7b7aed1233f"
Hide child attributes
Hide child attributes
商户号
示例:
"2023010558663764"
商户订单号
示例:
"20230105586637641001"
交易状态
可用选项:
SUCCESS, PENDING, FAILED, CLOSED 示例:
"PENDING"
订单创建时间
示例:
"2025-01-31T06:57:10+0000"
原商户订单号
订单号
示例:
"TR1654005852065107968"
退款金额，金额的单位为元。
示例:
"100.01"
交易状态结果描述
交易状态结果描述
⌘I
退款查询
curl --request POST \
--url https://gate.uat.payloco.com/gateway/v2/payments/open/api/refund/query \
--header 'Content-Type: application/json' \
--header 'signature: <api-key>' \
--data '
{
"charset": "UTF-8",
"version": "2.0.0",
"signType": "RSA",
"memberId": "2023010558663764",
"merchantId": "2023010558663764",
"requestTime": "2026-05-24T14:29:32.682+08:00",
"keyVersion": "1",
"data": {
"merchantOrderId": "1780673140561",
"orderId": "1929851221343618"
}
}
'import requests
url = "https://gate.uat.payloco.com/gateway/v2/payments/open/api/refund/query"
payload = {
"charset": "UTF-8",
"version": "2.0.0",
"signType": "RSA",
"memberId": "2023010558663764",
"merchantId": "2023010558663764",
"requestTime": "2026-05-24T14:29:32.682+08:00",
"keyVersion": "1",
"data": {
"merchantOrderId": "1780673140561",
"orderId": "1929851221343618"
}
}
headers = {
"signature": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {signature: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
charset: 'UTF-8',
version: '2.0.0',
signType: 'RSA',
memberId: '2023010558663764',
merchantId: '2023010558663764',
requestTime: '2026-05-24T14:29:32.682+08:00',
keyVersion: '1',
data: {merchantOrderId: '1780673140561', orderId: '1929851221343618'}
})
};
fetch('https://gate.uat.payloco.com/gateway/v2/payments/open/api/refund/query', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://gate.uat.payloco.com/gateway/v2/payments/open/api/refund/query",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'charset' => 'UTF-8',
'version' => '2.0.0',
'signType' => 'RSA',
'memberId' => '2023010558663764',
'merchantId' => '2023010558663764',
'requestTime' => '2026-05-24T14:29:32.682+08:00',
'keyVersion' => '1',
'data' => [
'merchantOrderId' => '1780673140561',
'orderId' => '1929851221343618'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"signature: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://gate.uat.payloco.com/gateway/v2/payments/open/api/refund/query"
payload := strings.NewReader("{\n \"charset\": \"UTF-8\",\n \"version\": \"2.0.0\",\n \"signType\": \"RSA\",\n \"memberId\": \"2023010558663764\",\n \"merchantId\": \"2023010558663764\",\n \"requestTime\": \"2026-05-24T14:29:32.682+08:00\",\n \"keyVersion\": \"1\",\n \"data\": {\n \"merchantOrderId\": \"1780673140561\",\n \"orderId\": \"1929851221343618\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("signature", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://gate.uat.payloco.com/gateway/v2/payments/open/api/refund/query")
.header("signature", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"charset\": \"UTF-8\",\n \"version\": \"2.0.0\",\n \"signType\": \"RSA\",\n \"memberId\": \"2023010558663764\",\n \"merchantId\": \"2023010558663764\",\n \"requestTime\": \"2026-05-24T14:29:32.682+08:00\",\n \"keyVersion\": \"1\",\n \"data\": {\n \"merchantOrderId\": \"1780673140561\",\n \"orderId\": \"1929851221343618\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://gate.uat.payloco.com/gateway/v2/payments/open/api/refund/query")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["signature"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"charset\": \"UTF-8\",\n \"version\": \"2.0.0\",\n \"signType\": \"RSA\",\n \"memberId\": \"2023010558663764\",\n \"merchantId\": \"2023010558663764\",\n \"requestTime\": \"2026-05-24T14:29:32.682+08:00\",\n \"keyVersion\": \"1\",\n \"data\": {\n \"merchantOrderId\": \"1780673140561\",\n \"orderId\": \"1929851221343618\"\n }\n}"
response = http.request(request)
puts response.read_body{
"code": "00000003",
"message": "处理中",
"traceId": "33fae7b7aed1233f",
"data": {
"merchantId": "2023010558663764",
"merchantOrderId": "20230105586637641001",
"oriMerchantOrderId": "string",
"status": "PENDING",
"createTime": "2025-01-31T06:57:10+0000",
"completeTime": "2025-01-31T06:57:10+0000",
"orderId": "TR1654005852065107968",
"refundAmount": 100.01,
"refundCurrency": "string",
"resultCode": "string",
"resultMsg": "string"
}
}