银联商务天满服务平台
Java PHP Python



import com.chinaums.open.api.OpenApiCache;
import com.chinaums.open.api.OpenApiContext;
import com.chinaums.open.api.constants.ConfigBean;
import com.chinaums.open.api.internal.util.http.HttpTransport;
import java.util.UUID;

public class OpenApiSdkTest {
    public static void main(String[] args) throws Exception{
        String url = "/v6/poslink/transaction/refund";
        //开发者ID
        String appId = "平台分配";
        //开发者秘钥
        String appKey = "平台分配";
        //实例化客户端
        ConfigBean configBean = new ConfigBean();
        OpenApiContext context = new OpenApiContext();
        String request = "{\"merchantCode\":\"898340149000005\",
                    \"terminalCode\":\"00000001\",
                    \"refundRequestId\":\"M23005480001202307180093555\",
                    \"transactionAmount\":\"4160\",
                    \"transactionCurrencyCode\":\"156\",
                    \"systemTraceNum\":\"123456\",
                    \"merchantOrderId\":\"M23005480001202307180092311\",
                    \"originalOrderId\":\"M23005480001202307180092311\",
                    \"merchantRemark\":\"test\",
                    \"limitCrossDevice\":\"false\",
                    \"srcReserved\":\"测试商品\",
                    \"operatorId\":\"01\",
                    \"goods\":\"[{\"goodsId\":\"001\",\"goodsName\":\"鸡蛋\",\"quantity\":\"10\",\"price\":\"1\",\"goodsCategory\":\"food meterial\",\"body\":\"two eggs\",\"discount\":\"5\"}]\",
                    \"refundDesc\":\"test\",
                    \"storeId\":\"01\",
                    \"bizIdentifier\":\"\",
                    \"oriTransDate\":\"\",
                    \"transparentFields\":\"{}\"}";
        context.setStartTime(System.currentTimeMillis());
        context.setRequestId(UUID.randomUUID().toString().replace("-", ""));
        context.setOpenServUrl(url.split("/v")[0].concat("/"));
        context.setApiServiceUrl(url);
        context.setVersion(url.split("/")[3]);
        context.setAppId(appId);
        context.setAppKey(appKey);
        context.setConfigBean(configBean);
        context.setServiceCode(url.split("/v")[1].substring(1));
        OpenApiCache.getCurrentToken(context);
        System.out.println(HttpTransport.getInstance().doPost(context, request));
    }
}
<?php
require_once "../utils/Log.php";
require_once "../utils/Tools.php";
require_once "../DefaultOpenApiClient.php";
class DataRequest

{
    public $url = "";
    public $serviceCode = "";
    public $apiVersion ="";
    public $needToken = true;
    public $needDataTag = false;
    public $data;

    function __construct($data, $url)
    {
        $this->data = $data;
        $apiVersion = preg_split("/[/]+/s",$url)[2];
        $this->apiVersion = $apiVersion;
        $serviceCode = strstr($url,$apiVersion);
        $this->url = strstr($url,"/".$apiVersion,true);
        $this->serviceCode = preg_replace("/^" . preg_quote($apiVersion, "/") . "/", "", $serviceCode);
    }
}

class DataDemo{
    public function main(){
        $appid = "平台分配";
        $appkey = "平台分配";
        $url = "/v6/poslink/transaction/refund";
        $data = json_encode(array("merchantCode"=>"898340149000005",
                    "terminalCode"=>"00000001",
                    "refundRequestId"=>"M23005480001202307180093555",
                    "transactionAmount"=>"4160",
                    "transactionCurrencyCode"=>"156",
                    "systemTraceNum"=>"123456",
                    "merchantOrderId"=>"M23005480001202307180092311",
                    "originalOrderId"=>"M23005480001202307180092311",
                    "merchantRemark"=>"test",
                    "limitCrossDevice"=>"false",
                    "srcReserved"=>"测试商品",
                    "operatorId"=>"01",
                    "goods"=>"json_encode(array([{"goodsId"=>"001","goodsName"=>"鸡蛋","quantity"=>"10","price"=>"1","goodsCategory"=>"food meterial","body"=>"two eggs","discount"=>"5"}]))",
                    "refundDesc"=>"test",
                    "storeId"=>"01",
                    "bizIdentifier"=>"",
                    "oriTransDate"=>"",
                    "transparentFields"=>"{}"));
        $reqiest = new DataRequest($data,$url);
        $client = new DefaultOpenApiClient();
        $content = $client->execute($reqiest,$appid,$appkey);
        $obj = json_decode($content);
        print_r($obj->errCode);
        print_r($obj->errInfo);
    }
}
$p = new DataDemo();
$p->main();
?>
# -*- coding: utf-8 -*-
from webapi.DefaultOpenApiClient import DefaultOpenApiClient

url = "/v6/poslink/transaction/refund"

class DataRequest(object):
    def __init__(self, data: dict) -> dict:
        self.data = data
        self.serviceCode = url[len(url.split("/v")[0])+len(url.split("/")[3])+1: len(url)]
        self.apiVersion = url.split("/")[3]
        self.needToken = True
        self.needDataTag = True

appId="平台分配"
appKey="平台分配"
client = DefaultOpenApiClient(appId, appKey)
cls = DataRequest({\"merchantCode\":\"898340149000005\",
                    \"terminalCode\":\"00000001\",
                    \"refundRequestId\":\"M23005480001202307180093555\",
                    \"transactionAmount\":\"4160\",
                    \"transactionCurrencyCode\":\"156\",
                    \"systemTraceNum\":\"123456\",
                    \"merchantOrderId\":\"M23005480001202307180092311\",
                    \"originalOrderId\":\"M23005480001202307180092311\",
                    \"merchantRemark\":\"test\",
                    \"limitCrossDevice\":\"false\",
                    \"srcReserved\":\"测试商品\",
                    \"operatorId\":\"01\",
                    \"goods\":\"[{\"goodsId\":\"001\",\"goodsName\":\"鸡蛋\",\"quantity\":\"10\",\"price\":\"1\",\"goodsCategory\":\"food meterial\",\"body\":\"two eggs\",\"discount\":\"5\"}]\",
                    \"refundDesc\":\"test\",
                    \"storeId\":\"01\",
                    \"bizIdentifier\":\"\",
                    \"oriTransDate\":\"\",
                    \"transparentFields\":\"{}\"})
response = client.execute(cls)
print(str(response.get("data")))
print(response.get("errCode"))
print(response.get("errInfo"))
print(response.get("resultCode"))
print(response.get("resultInfo"))

交易退款

URL

  • 生产环境: POST https://api-mop-wh.open.chinaums.com/v6/poslink/transaction/refund
  • 测试环境: POST https://test-api-open.chinaums.com/v6/poslink/transaction/refund

描述:进行POS通交易退款操作

ContentType:application/json

请求头

名称 必填 描述 示例值
Authorization 认证内容 (认证参考天满开发者中心->接入指引->平台认证方式:开发者中心 OPEN-BODY-SIG AppId="****",Timestamp="20170606135700",Nonce="99930a147f5353dd8a8f29a5329f37e9",Signature="IPmdGHYCcfN+mto0/02zkwoUF1NT3YqPKaUykMaec1T="

请求参数

名称 类型 必填 最大长度 描述 示例值
merchantCode string 15 商户号 898340149000005
terminalCode string 8 终端号 00000001
refundRequestId string 50 退款请求标识 标识一次退款请求,同一笔订单多次退款需要保证唯一,长度不超过50位 M23005480001202307180093555
transactionAmount number - 交易金额 退货金额,单位:分 4160
transactionCurrencyCode string - 交易币种 必须与原支付交易一致 156
systemTraceNum string 6 系统跟踪号 6位数字 123456
merchantOrderId string 50 商户订单号 商户订单号与银商订单号至少存在一个,如均存在,以银商订单号为准,忽略商户订单号 M23005480001202307180092311
originalOrderId string 50 银商订单号 必须与原支付交易返回的订单号一致 M23005480001202307180092311
merchantRemark string 50 商户备注 长度不超过50位 test
limitCrossDevice boolean - 是否限制跨终端
true : 不可以跨终端
false: 可以跨终端
false
srcReserved string 100 商户冗余信息 用于多种用途,如在特定支付渠道下,冗余信息将被渠道利用长度不超过100位 测试商品
operatorId string - 操作员编号 01
goods array 商品信息 最大长度6000位
   goodsId string - 商品ID 最大长度32位 001
   goodsName string - 商品名称 最大长度256位 鸡蛋
   quantity number - 商品数量 最大长度10位,为非0整数 10
   price number - 商品单价 最大长度12位,单位:分 1
   goodsCategory string - 商品分类 最大长度24位 food meterial
   body string - 商品说明 最大长度100位 two eggs
   discount number - 商品折扣 最大长度12位,单位:分 5
refundDesc string - 退货说明 test
storeId string - 门店号 01
bizIdentifier string 3 业务标识 标识接入的具体业务,除非特殊说明,一般不需要上送
oriTransDate string 8 原交易日期
transparentFields object - 银联冗余字段透传 JSON格式

响应示例

{
  "errCode":"00",
  "errInfo":"10000成功响应码",
  "transactionTime":"131714",
  "transactionDate":"0718",
  "transactionDateWithYear":"20230718",
  "settlementDate":"0718",
  "settlementDateWithYear":"20230718",
  "retrievalRefNum":"29168052038W",
  "totalRefundPromotionAmt":"4160",
  "orderPromotionStatus":"0",
  "eventList":
  [
    {
      "promotionProviderCode":"UMS",
      "flowId":"",
      "eventNo":"",
      "eventName":"",
      "promotionRange":"",
      "promotionType":"",
      "refundPromotionAmt":0,
      "platPromotionAmt":0,
      "mchntPromotionAmt":0,
      "thirdPartyPromotionAmt":0,
      "thirdPartyPromotionDetail":"",
      "goodsList":
      [
        {
          "goodsId":"01",
          "promotionAmt":"5",
          "goodsNum":"10",
          "goodsPrice":"15",
          "goodsRemark":"test"
        } 
      ] 
    } 
  ],
  "bankCardNo":"",
  "orderId":"20230718131532029168052038",
  "systemTraceNum":"",
  "thirdPartyName":"微信钱包",
  "cardAttr":"01",
  "refundInvoiceAmount":"4160",
  "transactionAmount":"4160",
  "installmentNumber":"12",
  "installmentSellerPercent":0,
  "oriInfo":
  {

  },
  "refundPromotionList":"0|0|0",
  "convMchntNo":"103290070111417",
  "convTermNo":"12340511",
  "chnlType":"",
  "acqInstCode":"",
  "issInstCode":"",
  "mCardAmt":""
}

响应参数

名称 类型 必填 最大长度 描述 示例值
errCode string -
平台错误码
业务错误码
00
errInfo string - 错误说明 10000成功响应码
transactionTime string - 交易时间 格式:hhmmss 131714
transactionDate string - 交易日期 格式:MMdd 0718
transactionDateWithYear string - 交易日期 格式:yyyyMMdd 20230718
settlementDate string - 结算日期 格式:MMdd 0718
settlementDateWithYear string - 结算日期 格式:yyyyMMdd 20230718
retrievalRefNum string - 检索参考号 长度12位 29168052038W
totalRefundPromotionAmt number - 优惠退货金额(合计) 单位:分 4160
orderPromotionStatus string - 订单优惠状态
0:订单无优惠
1:订单有优惠但未找到
2:订单有优惠且信息完整
0
eventList array 活动列表 单品营销优惠活动列表
   promotionProviderCode string - 渠道方 最大长度50位
ACP:银联
UMS:银联商务
ALIPAY:支付宝
WXPAY:微信
UMS
   flowId string - 优惠流水ID 最大长度50位
ACP:couponInfo[0].id
UMS:无
ALIPAY:无
WXPAY:promotion_id
   eventNo string - 活动编号 最大长度50位
ACP: couponInfo[0].id
UMS:无
ALIPAY: 无
WXPAY:无
   eventName string - 活动名称 最大长度64位
ACP:couponInfo[0].desc
UMS:无
ALIPAY:无
WXPAY:无
   promotionRange string - 优惠范围 最大长度32位
promotion_provider= ACP场景:
goods_list不存在时GLOBAL,
goods_list存在时SINGLE
   promotionType string - 优惠类型
最大长度32位
promotion_provider= ACP场景:
couponInfo[0].type
DD01随机立减
CP01事后赠予券
CP02事前领取券
   refundPromotionAmt number - 退货优惠金额 最大长度15位,单位:分
ACP:couponInfo[*].offstAmt累加结果
UMS:无
ALIPAY: present_refund_discount_amount present_refund_mdiscount_amount
WXPAY:refund_amount
   platPromotionAmt number - 平台金额 最大长度15位,单位:分
ACP: couponInfo[].offstAmt累加结果(对应的couponInfo[].spnsrId应为00010000)
UMS:无
ALIPAY:present_refund_discount_amount
WXPAY:无
   mchntPromotionAmt number - 商户优惠金额 最大长度15位,单位:分
ACP: couponInfo[].offstAmt累加结果(对应的couponInfo[].spnsrId内容长度为15)
UMS:无
ALIPAY:present_refund_mdiscount_amount
WXPAY:无
   thirdPartyPromotionAmt number - 第三方优惠金额 最大长度15位,单位:分
ACP:couponInfo[].offstAmt累加结果(对应的couponInfo[].spnsrId内容长度为8,且不为00010000)
UMS:无
ALIPAY:无
WXPAY:无
   thirdPartyPromotionDetail string - 第三方出资详情
base64编码
promotion_provider= ACP场景:
couponInfo
   goodsList array 单品列表 单品优惠场景下必填
      goodsId string - 商品编号 最大长度50位
ACP: dctDetail.id
UMS:无
ALIPAY:无
WXPAY:无
01
      promotionAmt number - 单品优惠金额 最大长度15位,单位:分
ACP: dctDetail.dctPrice(银联是单品优惠总额)
UMS:无
ALIPAY:无
WXPAY:无
5
      goodsNum number - 商品数量 最大长度15位,为非0整数
ACP: dctDetail.dctQuantity
UMS:无
ALIPAY:无
WXPAY:无
10
      goodsPrice number - 商品价格 最大长度15位,单位:分
ACP:无
UMS:无
ALIPAY:无
WXPAY:无
15
      goodsRemark string - 商品备注 最大长度128位
ACP: dctDetail.addnInfo
UMS:无
ALIPAY:无
WXPAY:无
test
bankCardNo string - 脱敏后的银行卡号,目前仅云闪付返回
orderId string 50 订单号 20230718131532029168052038
systemTraceNum string - 系统跟踪号 交易流水号,6位数字
thirdPartyName string - 第三方名称 仅仅退款成功的存在该字段 微信钱包
cardAttr string - 卡类型
借记:01
贷记:03
账户余额:91
01
refundInvoiceAmount string - 实际退款金额 最大长度12位,单位:分 4160
transactionAmount number - 交易金额 单位:分 4160
installmentNumber number - 分期期数 花呗分期期数(目前支持支付宝渠道) 12
installmentSellerPercent number - 付息方 花呗暂时只支持0/100,100:商家承担
oriInfo object - 原文信息 支付渠道侧信息chnlInfo:
chnlCode:支付渠道名称(ACP/ALIPAY/WXPAY)
promotionDetail:微信优惠详情(base64编码,channel_code= WXPAY场景必填,具体格式参考微信refund_detail字段说明)
cupPromotionInfo:银联活动优惠详情(base64编码,channel_code= ACP场景必填,具体格式参考银联couponInfo)
issAddiData:银联付款方附加数据(base64编码,channel_code= ACP场景必填,具体格式参考银联issAddnData)
收单机构侧信息acqInfo:
acqCode:收单机构名称(UMS)
refundPromotionList:退货优惠详情(base64编码,acq_code =UMS场景必填,具体格式参考银联商务字段说明)
refundPromotionList string - 优惠出资明细
格式:商户优惠金额
钱包优惠金额
convMchntNo string - 转商户商户号 103290070111417
convTermNo string - 转终端终端号 12340511
chnlType string - 目标渠道类型 目前仅数字货币二维码返回DCEP
acqInstCode string - 受理银行机构代码 ,目前仅数字货币二维码返回
issInstCode string - 发卡行代码 详见返回码说明,目前仅数字货币二维码返回
mCardAmt string - 支卡通最终核销金额 支付宝渠道

错误码