> ## Documentation Index
> Fetch the complete documentation index at: https://doc2.payloco.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 退款
## OpenAPI
````yaml 2024-03-31_zh-CN.yaml post /v2/payments/open/api/refund
openapi: 3.1.0
info:
version: '2024-03-31'
title: Payloco开放平台接口文档
description: "# Introduction.\n\nWelcome to Payloco.\n\nThe Payloco API is designed to be flexible and give you control in how and when you convert currencies, make payments and manage your accounts.\n\nWe recommend you read through the API Documentation in full to familiarise yourself with the features and workflows associated with the product. Demo account access can also be provided to you, and the Client ID and API key can be generated within Account settings > API keys in the Web Application.\n\nFor any assistance through the integration, your PayLoco Business Development Manager and your allocated PayLoco Client Integration Manager will be able to help guide you.\n# Versioning\n\nPayLoco uses versioning to improve our API contracts without affecting existing users.\n\nWhen we need to introduce a backwards-incompatible change, such as renaming or splitting a field, we will create a new date version which clients can migrate to when ready.\n### What is the latest version?\nThe latest version is `2024-03-31`.\n\n\n\n## 支付方式\n | 支付方式 | 支持国家 | 支付类型 | Tokenization | MIT | 必填参数(端到端支付必填) | 交易币种 |\n| :----: | :----: | :----: | :----: | :----:| :----:| :----: |\n| VISA | 全球 | CREDIT_CARD | ☑️ | ☑️ | cardNo/firstName/lastName/cvv/expireYear/expireMonth | 全币种 |\n| MasterCard | 全球 | CREDIT_CARD | ☑️ | ☑️ | cardNo/firstName/lastName/cvv/expireYear/expireMonth | 全币种 |\n| JCB | 全球 | CREDIT_CARD | ☑️ | ☑️ | cardNo/firstName/lastName/cvv/expireYear/expireMonth | 全币种 |\n| DISCOVER | 全球 | CREDIT_CARD | ☑️ | ☑️ | cardNo/firstName/lastName/cvv/expireYear/expireMonth | 全币种 |\n| UNION_PAY | 全球 | CREDIT_CARD | ☑️ | ☑️ | cardNo/firstName/lastName/cvv/expireYear/expireMonth | 全币种 |\n| WEIXIN | 中国香港(HK) | QRCODE,MICROPAY,JSAPI,MINIPROGRAM,APP,H5\t | - | - | - | CNY,HKD |\n| UNIONPAY | 中国香港(HK) | WEB,PAN_PRESENT,QRCODE,H5,3DS | - | - | - | CNY,HKD |\n| ALIPAY_CN | 中国(CN) | H5,WEB,APP\t | - | - | - | CNY,USD,HKD|\n| ALIPAY_HK | 中国香港(HK) | H5,WEB,APP\t | - | - | - | HKD,USD|\n| ALIPAY_HK | 中国香港(HK) | H5,WEB,APP\t | - | - | - | HKD,USD|\n| GCASH | 菲律宾(PH)| H5,WEB,BILLS\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | PHP,USD |\n| BPI | 菲律宾(PH)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | PHP,USD |\n| MAYA | 菲律宾(PH)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | PHP |\n| BILLEASE | 菲律宾(PH)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | PHP,USD |\n| Dragonpay | 菲律宾(PH)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | PHP |\n| GrabPay_PH | 菲律宾(PH)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | PHP |\n| TNG | 马来西亚(MY)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | MYR,USD |\n| BOOST | 马来西亚(MY)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | MYR,USD |\n| GrabPay_MY | 马来西亚(MY)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | MYR |\n| DANA | 印度尼西亚(ID)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | IDR,USD |\n| KAKAOPAY | 韩国(KR)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | KRW,USD |\n| NAVERPAY | 韩国(KR)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | KRW,USD |\n| TOSSPAY | 韩国(KR)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | KRW,USD |\n| TRUEMONEY | 泰国(TH)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | THB,USD |\n| RABBIT_LINE_PAY | 泰国(TH)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | THB,USD |\n| BRAZIL_PIX | 巴西(BR)| H5,QRCODE | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | BRL |\n| Ewallet_PicPay | 巴西(BR)| H5,QRCODE | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | BRL |\n| Khipu | 智利(CL)| H5 | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | CLP |\n| GrabPay_SG | 新加坡(SG)| H5,WEB\t | - |- | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | SGD,USD |\n| GoPay | 印度尼西亚(ID)| H5,WEB\t| - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | IDR |\n| OVO | 印度尼西亚(ID)| H5,WEB\t| - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | IDR |\n| DOKU | 印度尼西亚(ID)| H5,WEB\t| - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | IDR |\n| Konbini | 日本(JP)| H5,WEB\t| - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | JPY |\n| PayEasy | 日本(JP)| H5,WEB\t| - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | JPY |"
termsOfService: https://www.payloco.com
contact:
name: 技术支持
email: support@payloco.com
url: https://www.payloco.com
license:
url: https://www.apache.org/licenses/LICENSE-2.0.html
name: Apache 2.0
summary: ''
servers:
- url: https://gate.uat.payloco.com/gateway
description: Development server
- url: https://gate.payloco.com/gateway
description: Live server
security:
- signature: []
tags:
- name: 收单
- name: 其他交易类型
- name: 商户管理
- name: 文件下载
- name: 用卡人
- name: 卡管理
- name: 卡交易管理
- name: 收件人
paths:
/v2/payments/open/api/refund:
parameters: []
post:
tags:
- 收单
summary: 退款
operationId: post-v1-payments-open-api-refund
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VoidsRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/VoidsResponse'
security:
- signature: []
components:
schemas:
VoidsRequest:
title: VoidsRequest
allOf:
- $ref: '#/components/schemas/BaseRequest'
- type: object
x-stoplight:
id: a8nlvsq6i8rhq
properties:
data:
type: object
x-stoplight:
id: ze764f7lcy7w2
required:
- merchantOrderId
- refundCurrency
- refundAmount
- oriMerchantOrderId
properties:
merchantOrderId:
type: string
x-stoplight:
id: 5div29bnl5904
description: 商户订单号
example: '20230105586637641001'
refundCurrency:
type: string
x-stoplight:
id: yslxsw2uefmii
description: >-
订单币种[ISO4217](https://www.iso.org/standard/46121.html)币种的字母码
eg. USD, CNY, EUR
example: USD
maxLength: 3
refundAmount:
type: string
x-stoplight:
id: sc0ehnh8isl5y
description: 交易金额
example: '10.01'
refundNotifyUrl:
type: string
x-stoplight:
id: ivlaxxsf826fc
description: 异步通知地址
example: https://www.google.com
oriMerchantOrderId:
type: string
x-stoplight:
id: xpo90fxi5m24m
description: 原商户订单号
example: '20230105586637641002'
oriOrderId:
type: string
x-stoplight:
id: tvo7riw381rfv
description: 原Payloco订单号
example: TR1654008732742455296
comments:
type: string
x-stoplight:
id: fy4jr8wk76wzq
description: 退款原因
example: 退货
x-stoplight:
id: imy9t36jgz16r
examples:
- 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: '20230105586637641001'
refundCurrency: USD
refundAmount: '10.01'
refundNotifyUrl: https://www.google.com
oriMerchantOrderId: '20230105586637641002'
oriOrderId: TR1654008732742455296
comments: 退货
VoidsResponse:
title: VoidsResponse
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
properties:
data:
type: object
required:
- merchantOrderId
- merchantId
- orderId
- completeTime
- currency
- refundAmount
properties:
merchantOrderId:
type: string
example: '20230504142243'
description: 商户订单号
merchantId:
type: string
description: 商户号
example: '2023010558663764'
orderId:
type: string
description: 订单号
example: TR1654008732742455296
completeTime:
type: string
description: >-
订单完成的时间，遵循[rfc3339](https://datatracker.ietf.org/doc/html/rfc3339)标准格式，格式为yyyy-MM-DDTHH:mm:ssSSS+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC
8小时，即北京时间）。例如：2015-05-20T13:29:35.262+08:00表示，北京时间2015年5月20日13点29分35秒。
format: date-time
example: '2024-07-18T17:03:02.262+08:00'
currency:
type: string
description: >-
订单币种[ISO4217](https://www.iso.org/standard/46121.html)币种的字母码
eg. USD, CNY, EUR
example: USD
refundAmount:
type: number
example: 100.01
description: 交易金额
x-stoplight:
id: dwjv1d2arzldw
x-stoplight:
id: 1uzkkn1hoapck
examples:
- code: '00000003'
message: 处理中
traceId: 33fae7b7aed1233f
data:
merchantOrderId: '20230504142243'
merchantId: '2023010558663764'
orderId: TR1654008732742455296
completeTime: '2024-07-18T17:03:02.262+08:00'
currency: USD
refundAmount: 100.01
BaseRequest:
type: object
x-stoplight:
id: 4hhyl9c4c4skc
x-examples:
Example 1:
charset: UTF-8
version: 2.0.0
transType: string
accessType: PAY
signType: RSA
memberId: stringstri
merchantId: stringstri
required:
- charset
- version
- signType
- memberId
- merchantId
- requestTime
- keyVersion
properties:
charset:
type: string
description: 交互数据的编码【utf-8】
default: UTF-8
examples:
- UTF-8
version:
type: string
description: "接口版本，当前版本为【2.0.0】,目前只能传2.0.0，不能不传\t"
example: 2.0.0
maxLength: 8
signType:
type: string
description: 报文签名类型
example: RSA
memberId:
type: string
description: 机构号
example: '2023010558663764'
merchantId:
type: string
description: 商户号
example: '2023010558663764'
maxLength: 32
requestTime:
type: string
x-stoplight:
id: njc3cd378x9h1
description: >-
请求时间，遵循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秒。
example: '2026-05-24T14:29:32.682+08:00'
maxLength: 32
keyVersion:
type: string
x-stoplight:
id: k14bjqd1dyfwh
description: 密钥版本 当前值为：1
maxLength: 8
example: '1'
examples:
- charset: UTF-8
version: 2.0.0
signType: RSA
memberId: '2023010558663764'
merchantId: '2023010558663764'
requestTime: '2026-05-24T14:29:32.682+08:00'
keyVersion: '1'
BaseResponse:
type: object
x-stoplight:
id: 4lloo3c92r1n3
x-examples:
Example 1:
isSuccess: true
errCode: '00000003'
errMessage: 处理中
status: PENDING
traceId: 33fae7b7aed1233f
examples:
- code: '00000000'
message: SUCCESS
traceId: 33fae7b7aed1233f
required:
- code
- message
- traceId
properties:
code:
type: string
description: |
响应状态码，’00000000’代表成功。’00000003’代表受理中,只代表接口请求成功，不代表订单状态。
example: '00000003'
x-stoplight:
id: zocifrrgwx3bv
message:
type: string
description: |+
返回描述，’SUCCESS.’ 。只代表接口请求成功，不代表订单状态。
example: SUCCESS
x-stoplight:
id: smef8x7rur0cy
traceId:
type: string
description: "请求消息唯一标识。traceId为本次调用产生的流水号，接口调用异常，可以提供此流水号用于排查问题。\t"
example: 33fae7b7aed1233f
securitySchemes:
signature:
type: apiKey
description: |-
## 加签（Signature）
加签是 Payloco 开放平台与商户之间用于保障报文**完整性**和**防篡改**的安全机制。
### 适用场景
1. **商户请求 Payloco**：商户使用**自身私钥**对请求报文进行加签。
2. **Payloco 返回响应**：商户使用 **Payloco 公钥** 对响应报文进行验签。
### 加签规则（商户请求端）
商户需对 HTTP 请求的 **Body** 进行签名，具体步骤如下：
### 1. 计算签名（SHA256withRSA）
```java
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 编码；
```java
String signature = Base64.getEncoder().encodeToString(signedHash);
```
### 3. 将编码后的内容放在请求头部 signature 参数中。
```java
POST /v2/payments/open/api/pay HTTP/1.1
Content-Type: application/json
signature: MIIC8jCCAdqgAwIBAgI...
```
name: signature
in: header
````