NAV Navbar
Logo text
cURL PHP Java Go

Welcome

Welcome to Yuansfer POS API Developer Center.
点击查看中文文档.

API Basics

The Yuansfer offers RESTful interface to help you create a payments solution that meets your needs. The API enables you to incorporate Chinese payment methods including WeChat Pay, China UnionPay, and Alipay. You can enable customers to make Chinese online and mobile payments with only a few clicks.

Get Started

The Yuansfer REST APIs use HTTP verbs and a RESTful endpoint structure. JSON is returned by all API responses, including errors.

Authentication and Authorization

The Yuansfer API uses API credentials including API token, Merchant ID, Store ID, Store Admin ID to authenticate requests. You can retrieve and manage API credentials in your Yuansfer Dashboard.
API credentials carry many privileges, so be sure to keep them secure! Do not share your secret API credentials in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.



Signing API parameters

<?php
function getVerifySign()
{
    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'date' => '20180620',
        'currency' => 'USD',
        'vendor' => 'alipay'
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
}

getVerifySign();
?>
import java.util.Map;
import java.util.TreeMap;
import org.json.simple.JSONObject;
import com.nengjian.yuansfer.pos.utils.MapUrlUtils;
import com.nengjian.yuansfer.pos.utils.Md5Utils;

public class VerifySignExample {
    public static void main(String[] args) {
        Map<String, Object> map = new TreeMap<String, Object>();
        String yuansferToken = "59600f2a9ad644c6a9570233560cc94e";
        map.put("merchantNo", "200043");
        map.put("storeNo", "300014");
        map.put("storeAdminNo", "3000140001");
        map.put("amount","0.01");
        VerifySignExample example = new VerifySignExample();
        String verifySign = example.getYuansferVerifySign(map, yuansferToken);
        JSONObject json = new JSONObject();
        json.put("verifySign", verifySign);
        System.out.println(json);
    }

    public String getYuansferVerifySign(final Map<String, Object> map, final String yuansferToken) {
        String calculateValue = commonGetVerifySign(map, yuansferToken);
        return calculateValue;
    }

    private String commonGetVerifySign(final Map<String, Object> map, final String yuansferToken) {
        Map<String, Object> treeMap = new TreeMap<String, Object>(map);
        String str = MapUrlUtils.getUrlParamsByMap(treeMap);
        str = str + "&" + Md5Utils.cryptHash(yuansferToken);

        String calculateValue = Md5Utils.cryptHash(str);
        return calculateValue;
    }
}


public class MapUrlUtils {
    public static String getUrlParamsByMap(Map<String, Object> map) {
        if (map == null) {
            return "";
        }
        StringBuilder sbuilder = new StringBuilder();
        for (Map.Entry<String, Object> entry : map.entrySet()) {
            sbuilder.append(entry.getKey()).append("=").append(entry.getValue());
            sbuilder.append("&");
        }
        String s = sbuilder.toString();
        if (s.endsWith("&")) {
            s = StringUtils.substringBeforeLast(s, "&");
        }
        return s;
    }
}


public class Md5Utils {
    public static String cryptHash(String hashStr) {
        String strCrypt = hashStr;
        if (strCrypt.length() > 0) {
            strCrypt = hash(strCrypt);
        }
        return strCrypt;
    }

    public static  String hash(String str) {
        try {  
            MessageDigest md = MessageDigest.getInstance("MD5");  
            md.update(str.getBytes());  
            byte b[] = md.digest();  

            int i;  

            StringBuilder buf = new StringBuilder("");  
            for (int offset = 0; offset < b.length; offset++) {  
                i = b[offset];  
                if (i < 0)  
                    i += 256;  
                if (i < 16)  
                    buf.append("0");  
                buf.append(Integer.toHexString(i));  
            }  
            //32-bit Encryption
            return buf.toString();  
            //16-bit Encryption
            //return buf.toString().substring(8, 24);  
        } catch (NoSuchAlgorithmException e) {  
            e.printStackTrace();  
            return null;  
        } 
    }
}

package main

import (
    "crypto/md5"
    "encoding/hex"
    "sort"
)

func main() {
    var token string = "5cbfb079f15b150122261c8537086d77a"
    var data = make(map[string]string)

    data["amount"] = "1.00"
    data["storeNo"] = "300014"
    data["currency"] = "USD"
    data["merchantNo"] = "200043"
    data["callbackUrl"] = "https://wx.yuansfer.yunkeguan.com/wx"
    data["terminal"] = "ONLINE"
    data["ipnUrl"] = "https://wx.yuansfer.yunkeguan.com/wx"
    data["reference"] = "seq_1525922323"
    data["vendor"] = "alipay"
    data["timeout"] = "120"
    data["goodsInfo"] = `[{"goods_name":"Yuansfer","quantity":"1"}]`

    //Step 1, 2:
    step2 := map2Str(data)
    //Step 3:
    step3 := step2 + md5Token(token)
    //Step 4:
    verifySign := md5Token(step3)
}

func md5Token(data string) string {
    md5 := md5.New()
    md5.Write([]byte(data))
    md5Data := md5.Sum([]byte(""))
    return hex.EncodeToString(md5Data)
}

func map2Str(m map[string]string) string {
    var keys []string
    for k := range m {
        if m[k] != "" {
            keys = append(keys, k)
        }
    }
    sort.Strings(keys)
    dec := ""
    for _, key := range keys {
        dec += key + "=" + m[key] + "&"
    }
    return dec
}

Signing the API parameters is a feature that allows you to prevent any interference and enhance the security of calling Yuansfer APIs, by using MD5 authenticated hash.
You need to retrieve API token from Yuansfer Dashboard for building signature.

Build the API parameter signature

To sign the API parameters, you need to follow these steps:
1. Sort the parameters alphabetically.
2. Concatenate the parameter names and values using ‘=’ and ‘&’ character.
3. Append MD5 hash value of API token with ‘&’ prefix.
4. Calculate MD5 hash value of Step 3 result.

EXAMPLE

Let’s consider the following parameters:


1. Sort the parameters alphabetically


2. Concatenate the parameter names and values using ‘=’ and ‘&’ character

amount=1.00&callbackUrl=https://wx.yuansfer.yunkeguan.com/wx&currency=USD&goodsInfo=[{"goods_name":"Yuansfer","quantity":"1"}]&ipnUrl=https://wx.yuansfer.yunkeguan.com/wx&merchantNo=200043&reference=seq_1525922323&storeNo=300014&terminal=ONLINE&timeout=120&vendor=alipay


3. Append MD5 hash value of API token with ‘&’ prefix.

When the API token is 5cbfb079f15b150122261c8537086d77a, the MD5 hash value is 186abea4b8610d7ff03768255588597a.
So the result string is :
amount=1.00&callbackUrl=https://wx.yuansfer.yunkeguan.com/wx&currency=USD&goodsInfo=[{"goods_name":"Yuansfer","quantity":"1"}]&ipnUrl=https://wx.yuansfer.yunkeguan.com/wx&merchantNo=200043&reference=seq_1525922323&storeNo=300014&terminal=ONLINE&timeout=120&vendor=alipay&186abea4b8610d7ff03768255588597a


4. Calculate MD5 hash value of Step 3 result string.

MD5 hash value is b6bfd66531ae7c9499115c7480a2c8aa


Online Payments API

Use the Online Payments API to easily and securely accept online payments. The Yuansfer secure payment interface provides online payment services, including UnionPay, Alipay and WeChat Pay.

Online payment workflow

Sflow en 1. The Merchant’s system submits the order to the Yuansfer system when a customer places an order.
2. The Yuansfer system checks if the request is rightful.
3. The Yuansfer system leads the customer to the Cashier Page to check out. The Cashier Page displays a different payment method depends on selected payment services.
4. The customer confirms to pay on Cashier Page.
5. The Yuansfer system sends the payment result to the Merchant’s system.
6. The Merchant’s system shows the payment result to the customer.


Note: Some screenshots of Cashier Page

Cashier alipay

Cashier Page for Alipay payment service.

Cashier wechatpay

Cashier Page for WeChat Pay payment service.

Cashier unionpay

Cashier Page for UnionPay payment service.

securepay()

Endpoint

POST https://mapi.yuansfer.com/appTransaction/v2/securepay
POST https://mapi.yuansfer.com/appTransaction/v2/securepay
POST https://mapi.yuansfer.com/appTransaction/v2/securepay
POST https://mapi.yuansfer.com/appTransaction/v2/securepay

Example Request

curl "https://mapi.yuansfer.com/appTransaction/v2/securepay" \
-d amount="1.00" \
-d storeNo="300014" \
-d currency="USD" \
-d merchantNo="200043" \
-d callbackUrl="https://wx.yuansfer.yunkeguan.com/wx" \
-d terminal="ONLINE" \
-d ipnUrl="https://wx.yuansfer.yunkeguan.com/wx" \
-d reference="seq_1525922323" \
-d vendor="alipay" \
-d verifySign="4f0cc35728849e4b4aa4a176f4a5edac"
<?php
function securepay()
{
    $url = 'https://mapi.yuansfer.com/appTransaction/v2/securepay';
    $token = '5cbfb079f15b150122261c8537086d77a';

    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'amount' => '0.01',
        'currency' => 'USD',
        'vendor' => 'alipay',
        'ipnUrl' => 'https://nengjtian.s1.natapp.cc/login/test',
        'callbackUrl' => 'https://nengjtian.s1.natapp.cc/login/test2?transactionId={transactionId}&status={status}&amount={amount}&time={time}&reference={reference}&note={note}',
        'terminal' => 'ONLINE',
        'reference' => 'test2018070101',
        'description' => 'test_description',
        'note' => 'test_note',
        'timeout' => '120'
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
    echo "\n";

    $ch = curl_init($url);
    curl_setopt_array($ch, array(
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($params),
    ));

    $result = curl_exec($ch);
    curl_exec($ch);

    echo $result;
    echo "\n";
    return json_decode($result, true);
}

securepay();
?>
/**
 * testing class of securepay API
 * @author zhoukai
 *
 */
public class SecurepayTest {
    public static final String TEST_URL = "https://mapi.yuansfer.yunkeguan.com";            //Testing domain
    public static final String PROD_URL = "https://mapi.yuansfer.com";                      //Production domain
    public static final String YUANSFER_TOKEN = "5c5fe30183be69fceff8174358d4b8ae";

    public static void main(String[] args) {
        YuansferVerifySignHelper helper = new YuansferVerifySignHelper();

        YuansferSecurepayDto dto = paramSetting();
        Map<String, Object> params = ReflectionUtils.convertBean2MapIgnoreNullVal(dto, new String[]{"serialVersionUID"});
        String verifySign = helper.getYuansferVerifySign(params, YUANSFER_TOKEN); 
        params.put("verifySign", verifySign);

        String url = TEST_URL + "/appTransaction/v2/securepay";
        String ret = HttpClientUtils.post(url, null, params);
        System.out.println(ret);
    }

    public static YuansferSecurepayDto paramSetting() {
        YuansferSecurepayDto dto = new YuansferSecurepayDto();
        /**
         * merchantNo,storeNo is necessory, and they are provided by Yuansfer
         */
        dto.setMerchantNo("200043");                                                //The Merchant NO.
        dto.setStoreNo("300014");                                                   //The Store NO.

        /**
         * transaction infomation is necessory
         */
        dto.setAmount("0.01");                                                      //The amount, unit "division"
        dto.setCurrency("USD");                                                     //currency, "USD" or "CAD"
        dto.setIpnUrl("https://nengjtian.s1.natapp.cc/login/test");                 //Asynchronous callback address
        dto.setCallbackUrl("https://nengjtian.s1.natapp.cc/login/test2");           //Synchronous callback address
        dto.setReference("9091023122");                                             //order NO. of client's system
        dto.setTerminal("ONLINE");                                                  //"ONLINE" or "WAP"
        dto.setTimeout("120");                                                      //unit "minute"
        dto.setVendor("alipay");                                                    //“alipay","wechatpay" or "unionpay"

        /**
         * note,desription are optional 
         */
        dto.setDescription("test-description");                                     //description
        dto.setNote("test-note");                                                   //note

        return dto;
    }
}
import (
    "fmt"
    "time"

    yuan "github.com/yuansfer/golang_sdk"
)

func securepay() {
    req := &yuan.Securepay{
        MerchantNo:  "200043", //customer The merchant NO.
        StoreNo:     "300014",
        Currency:    "USD",
        Amount:      "0.01",
        Vendor:      "wechatpay",
        Reference:   fmt.Sprintf("demo_%d", time.Now().Unix()), //sequence number of customer system
        IpnUrl:      "https://customer-ipn",        //internet accessible 
        CallbackUrl: "https://customer-callback",   //internet accessible 
        Description: "description",
        Note:        "note",
        Terminal:    "ONLINE",
        Timeout:     "120",
    }

    goods := "Yuansfer"
    quantity := "1"
    if quantity != "" && goods != "" {
        goodsInfos := []yuan.GoodsInfomation{
            yuan.GoodsInfomation{
                GoodsName: goods,
                Quantity:  quantity,
            },
        }
        _ = req.Format(goodsInfos)
    }

    resp, err := req.PostToYuansfer(yuansferToken)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(resp)
}

Use the securepay() API to pay an order.

HTTP Request

POST https://mapi.yuansfer.com/appTransaction/v2/securepay

Request Parameters

Parameter Type Description
merchantNo

required

string The ID of the merchant.
storeNo

required

string The ID of the store.
amount

optional

decimal The transaction amount.
Either amount or rmbAmount is required.
rmbAmount

optional

decimal The transaction amount in RMB.
Either amount or rmbAmount is required.
currency

required

enum The three-character currency code that identifies the currency.
The possible values are: “USD”.
vendor

required

enum The payment method.
The possible values are: “alipay”, “wechatpay”, “unionpay”.
ipnUrl

required

string The Instant Payment Notification Handler url. IPN url must be secure.
For more details, see here.
For a list of parameters, see here.
callbackUrl

required

string The synchronous HTTP callbacks that receive notification messages for events. The callback url follows macro substitution rules like xxxcallback_url?trans_no={amount}&amount={amount}, then Yuansfer will automatically replace the values of {}.
For a list of parameters, see here.
terminal

required

enum The terminal code.
The possible values are: “ONLINE”, “WAP”.
reference

required

string The ID of the transaction in the merchant’s system.
description

optional

string The description of the transaction which will be displayed on the invoice.
note

optional

string The payment note.
timeout

optional

integer The timeout in minute.
Default value is 120.
goodsInfo

required

string JSON encoded string of an array of items that the customer purchases from the merchant. Special characters are not supported.
e.g.: [{"goods_name":"name1","quantity":"quantity1"},{"goods_name":"name2","quantity":"quantity2"}]
verifySign

required

string The parameter signature.

Response

Parameter Description
* When vendor is “wechatpay” and terminal is “WAP”, return html. But Cashier Page can be opened in only WeChat Pay browser directly.
In other cases, return a html page source as string which will show Cashier Page.

securepayrefund()

Endpoint

POST https://mapi.yuansfer.com/appTransaction/v2/securepayRefund
POST https://mapi.yuansfer.com/appTransaction/v2/securepayRefund
POST https://mapi.yuansfer.com/appTransaction/v2/securepayRefund
POST https://mapi.yuansfer.com/appTransaction/v2/securepayRefund

Example Request

curl "https://mapi.yuansfer.com/appTransaction/v2/securepayRefund" \
-d "amount=0.01" \
-d "storeNo=300014" \
-d "currency=USD" \
-d "merchantNo=200043" \
-d "reference=origin_reference" \
-d "verifySign=verifySign"
<?php
function securepayRefund()
{
    $url = 'https://mapi.yuansfer.com/appTransaction/v2/securepayRefund';
    $token = '5cbfb079f15b150122261c8537086d77a';

    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'amount' => '0.01',
        'reference' => 'test2018070101',
        'managerAccountNo' => '3000140001',
        'password' => '1e2958a66c609467a4794c6c8adf3b84'
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
    echo "\n";

    $ch = curl_init($url);
    curl_setopt_array($ch, array(
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($params),
    ));

    $result = curl_exec($ch);
    curl_exec($ch);

    echo $result;
    echo "\n";
    return json_decode($result, true);
}

securepayRefund();
?>
public class SecurepayRefundTest {
    public static final String TEST_URL = "https://mapi.yuansfer.yunkeguan.com";            //Testing domain
    public static final String PROD_URL = "https://mapi.yuansfer.com";                      //Production domain
    public static final String YUANSFER_TOKEN = "5c5fe30183be69fceff8174358d4b8ae";

    public static void main(String[] args) {
        YuansferSecurepayRefundDto refundDto = new YuansferSecurepayRefundDto();
        YuansferVerifySignHelper verifyHelper = new YuansferVerifySignHelper();
        refundDto.setAmount("0.01");
        refundDto.setCurrency("USD");
        refundDto.setMerchantNo("200043");
        refundDto.setStoreNo("300014");
        refundDto.setReference("9091023122");

        /**
         * When managerAccountNo and password are refund, 
         * shop manager's permission check can be configured in the yuansfer background, 
         * and the check is unnecessary. If you don't check, you don't need to enter store account and password.
         */
        // YuansferPwdHelper pwdHelper = new YuansferPwdHelper();
        // refundDto.setManagerAccountNo("3000140001");    
        // String managerPwd = pwdHelper.genPwd("111111"); 
        // ßrefundDto.setPassword(managerPwd);

        Map<String, Object> params = ReflectionUtils.convertBean2MapIgnoreNullVal(refundDto, new String[]{"serialVersionUID"});
        String verifySign = verifyHelper.getYuansferVerifySign(params, YUANSFER_TOKEN);
        refundDto.setVerifySign(verifySign);
        params.put("verifySign", verifySign);

        String url = TEST_URL + "/appTransaction/v2/securepayRefund";
        String ret = HttpClientUtils.post(url, null, params);
        JSON json = JSON.parseObject(ret);
        System.out.println(json);
    }
}
func refund(t *table) {
    req := yuan.Refund{
        MerchantNo:       "200043", //customer The merchant NO.
        StoreNo:          "300014",
        Currency:         "USD",
        Reference:        "original sequence No.", //sequence number of customer system
        Amount:           "0.01",
    }

    resp, err := req.PostToYuansfer(yuansferToken)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(resp)
}

Example Response

{
    "result":{
        "amount": "0.01",
        "status": "success",
        "currency": "CNY",
        "reference": "44444",
        "refundAmount": "0.01",
        "refundTransactionId": "297245675773380538",
        "oldTransactionId": "297245675773319174"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "result":{
        "amount": "0.01",
        "status": "success",
        "currency": "CNY",
        "reference": "44444",
        "refundAmount": "0.01",
        "refundTransactionId": "297245675773380538",
        "oldTransactionId": "297245675773319174"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "result":{
        "amount": "0.01",
        "status": "success",
        "currency": "CNY",
        "reference": "44444",
        "refundAmount": "0.01",
        "refundTransactionId": "297245675773380538",
        "oldTransactionId": "297245675773319174"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "result":{
        "amount": "0.01",
        "status": "success",
        "currency": "CNY",
        "reference": "44444",
        "refundAmount": "0.01",
        "refundTransactionId": "297245675773380538",
        "oldTransactionId": "297245675773319174"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}

Use the securepayrefund() API to refund payments.

HTTP Request

POST https://mapi.yuansfer.com/appTransaction/v2/securepayRefund

Request Parameters

Parameter Type Description
merchantNo

required

string The ID of the merchant.
storeNo

required

string The ID of the store.
amount

optional

decimal The refund amount.
Either amount or rmbAmount is required.
rmbAmount

optional

decimal The refund amount in RMB.
Either amount or rmbAmount is required.
reference

required

string The ID of the transaction in the merchant’s system.
managerAccountNo

optional

string The ID of the store admin.
Required when store manager validation is set.
password

optional

string Password generation algorithm: MD5(“@yuanex” + Store admin password)
Required when store manager validation is set.
verifySign

required

string The parameter signature.

Response

Parameter Type Description
result object The result of the refund.
ret_msg string The response return message.
ret_code string The response return code. For more details, see here.

result object

Parameter Type Description
amount decimal The transaction amount.
refundAmount decimal The transaction refund amount.
currency string The three-character currency code that identifies the currency.
The possible values are: “USD”.
status enum The state of the refund.
reference string The ID of the transaction in the merchant’s system.
refundTransactionId string The ID of the refund transaction in the Yuansfer system.
oldTransactionId string The ID of the transaction in the Yuansfer system which the refund transaction is based on.

securepay-reference-query()

Endpoint

POST https://mapi.yuansfer.com/appTransaction/v2/securepay-reference-query
POST https://mapi.yuansfer.com/appTransaction/v2/securepay-reference-query
POST https://mapi.yuansfer.com/appTransaction/v2/securepay-reference-query
POST https://mapi.yuansfer.com/appTransaction/v2/securepay-reference-query

Example Request

curl "https://mapi.yuansfer.com/appTransaction/v2/securepay-reference-query" \
-d "storeNo=300014" \
-d "merchantNo=200043" \
-d "reference=origin_reference" \
-d "verifySign=verifySign"
<?php
function securepayReferenceQuery()
{
    $url = 'https://mapi.yuansfer.com/appTransaction/v2/securepay-reference-query';
    $token = '5cbfb079f15b150122261c8537086d77a';

    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'reference' => 'test2018070101'
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
    echo "\n";

    $ch = curl_init($url);
    curl_setopt_array($ch, array(
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($params),
    ));

    $result = curl_exec($ch);
    curl_exec($ch);

    echo $result;
    echo "\n";
    return json_decode($result, true);
}

securepayReferenceQuery();
?>
public class SecurepayReferenceQueryTest {
    public static final String TEST_URL = "https://mapi.yuansfer.yunkeguan.com";            //Testing domain
    public static final String PROD_URL = "https://mapi.yuansfer.com";                      //Production domain
    public static final String YUANSFER_TOKEN = "5cbfb079f15b150122261c8537086d77a";

    public static void main(String[] args) {
        YuansferVerifySignHelper helper = new YuansferVerifySignHelper();

        YuansferSecurepayQueryDto dto = paramSetting();
        Map<String, Object> params = ReflectionUtils.convertBean2MapIgnoreNullVal(dto, new String[]{"serialVersionUID"});
        String verifySign = helper.getYuansferVerifySign(params, YUANSFER_TOKEN);  //verifySign
        params.put("verifySign", verifySign);

        String url = TEST_URL + "/appTransaction/v2/securepay-reference-query";
        String ret = HttpClientUtils.post(url, null, params);
        System.out.println(ret);
    }

    public static YuansferSecurepayQueryDto paramSetting() {
        YuansferSecurepayQueryDto dto = new YuansferSecurepayQueryDto();

        dto.setMerchantNo("200043");                                                //The merchant NO.
        dto.setStoreNo("300014");                                                   //The store NO.
        dto.setReference("20180126162433");
        return dto;
    }
}


func query(t *table) {
    req := yuan.Query{
        MerchantNo: "200043", //customer The merchant NO.
        StoreNo:    "300014",
        Currency:   "USD",
        Reference:  "original sequence No.", //sequence number of customer system
        Terminal:   "ONLINE",
    }

    //TO CALL VERIFYSIGN
    resp, err := req.PostToYuansfer(yuansferToken)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(resp)
}

Example Response


{
    "result":{
    "reference": "test20180801006",
    "transactionId": "297553569604475564",
    "amount": "2.00",
    "refundInfo":[
        {
            "refundTransactionId": "297553569604658581",
            "refundAmount": "1.50"
        },
        {
            "refundTransactionId": "297553569604680588",
            "refundAmount": "0.50"
        }
    ],
    "currency": "CNY",
    "status": "success"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}

{
    "result":{
    "reference": "test20180801006",
    "transactionId": "297553569604475564",
    "amount": "2.00",
    "refundInfo":[
        {
            "refundTransactionId": "297553569604658581",
            "refundAmount": "1.50"
        },
        {
            "refundTransactionId": "297553569604680588",
            "refundAmount": "0.50"
        }
    ],
    "currency": "CNY",
    "status": "success"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "result":{
    "reference": "test20180801006",
    "transactionId": "297553569604475564",
    "amount": "2.00",
    "refundInfo":[
        {
            "refundTransactionId": "297553569604658581",
            "refundAmount": "1.50"
        },
        {
            "refundTransactionId": "297553569604680588",
            "refundAmount": "0.50"
        }
    ],
    "currency": "CNY",
    "status": "success"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "result":{
    "reference": "test20180801006",
    "transactionId": "297553569604475564",
    "amount": "2.00",
    "refundInfo":[
        {
            "refundTransactionId": "297553569604658581",
            "refundAmount": "1.50"
        },
        {
            "refundTransactionId": "297553569604680588",
            "refundAmount": "0.50"
        }
    ],
    "currency": "CNY",
    "status": "success"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}

Use the securepay-reference-query() API to get transaction details by ID of the transaction in the merchant’s system.

HTTP Request

POST https://mapi.yuansfer.com/appTransaction/v2/securepay-reference-query

Request Parameters

Parameter Type Description
merchantNo

required

string The ID of the merchant.
storeNo

required

string The ID of the store.
reference

required

string The ID of the transaction in the merchant’s system.
verifySign

required

string The parameter signature.

Response

Parameter Type Description
result object The transaction details.
ret_msg string The response return message.
ret_code string The response return code. For more details, see here.

result object

Parameter Type Description
reference string The ID of the transaction in the merchant’s system.
transactionId string The ID of the transaction in the Yuansfer system.
amount decimal The transaction amount.
status string The status of the transaction.
currency string The three-character currency code that identifies the currency.
The possible values are: “USD”.
refundInfo array The array of refundInfo object.

refundInfo object

Parameter Type Description
refundTransactionId string The ID of the refund transaction in the Yuansfer system.
refundAmount string The refund amount.

exchangerate()

Endpoint

POST https://mapi.yuansfer.com/appTransaction/v2/exchangerate
POST https://mapi.yuansfer.com/appTransaction/v2/exchangerate
POST https://mapi.yuansfer.com/appTransaction/v2/exchangerate
POST https://mapi.yuansfer.com/appTransaction/v2/exchangerate

Example Request

curl "https://mapi.yuansfer.com/appTransaction/v2/exchangerate" \
-d "storeNo=300014" \
-d "merchantNo=200043" \
-d "date=yyyyMMdd" \
-d "vendor=alipay" \
-d "verifySign=verifySign"
<?php
function exchangerate()
{
    $url = 'https://mapi.yuansfer.com/appTransaction/v2/exchangerate';
    $token = '5cbfb079f15b150122261c8537086d77a';

    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'date' => '20180620',
        'currency' => 'USD',
        'vendor' => 'alipay'
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
    echo "\n";

    $ch = curl_init($url);
    curl_setopt_array($ch, array(
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($params),
    ));

    $result = curl_exec($ch);
    curl_exec($ch);

    echo $result;
    echo "\n";
    return json_decode($result, true);
}

exchangerate();
?>
public class SecurepayExchangeTest {
    public static final String TEST_URL = "https://mapi.yuansfer.yunkeguan.com";            //Testing domain
    public static final String PROD_URL = "https://mapi.yuansfer.com";                      //Production domain
    public static final String YUANSFER_TOKEN = "5cbfb079f15b150122261c8537086d77a";

    public static void main(String[] args) {
        YuansferVerifySignHelper helper = new YuansferVerifySignHelper();

        YuansferSecurepayExchangeDto dto = paramSetting();
        Map<String, Object> params = ReflectionUtils.convertBean2MapIgnoreNullVal(dto, new String[]{"serialVersionUID"});
        String verifySign = helper.getYuansferVerifySign(params, YUANSFER_TOKEN);
        params.put("verifySign", verifySign);

        String url = TEST_URL + "/appTransaction/v2/exchangerate";
        String ret = HttpClientUtils.post(url, null, params);
        System.out.println(ret);
    }

    public static YuansferSecurepayExchangeDto paramSetting() {
        YuansferSecurepayExchangeDto dto = new YuansferSecurepayExchangeDto();

        dto.setMerchantNo("200043");                                                //The merchant NO.
        dto.setStoreNo("300014");                                                   //The store NO.
        dto.setDate("20180128");
        dto.setCurrency("USD");
        dto.setVendor("alipay");
        return dto;
    }
}




Example Response

{
    "exchangerate": "6.594300",
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "exchangerate": "6.594300",
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "exchangerate": "6.594300",
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "exchangerate": "6.594300",
    "ret_msg": "query success ",
    "ret_code": "000100"
}

Use the exchangerate() API to get exchange rate between two currencies on certain date.

HTTP Request

POST https://mapi.yuansfer.com/appTransaction/v2/exchangerate

Request Parameters

Parameter Type Description
merchantNo

required

string The ID of the merchant.
storeNo

required

string The ID of the store.
date

required

Date The date issued.
Format : “YYYYMMDD”.
currency

required

enum The three-character currency code that identifies the currency.
The possible values are: “USD”.
vendor

required

enum The payment method.
The possible values are: “alipay”, “wechatpay”, “unionpay”.
verifySign

required

string The parameter signature.

Response

Parameter Type Description
exchangerate decimal The exchange rate between CNY and USD .
ret_msg string The response return message.
ret_code string The response return code. For more details, see here.

In-Store Payments API

Use the In-Store Payments API to easily and securely accept Chinese payments in your store.
There are two types of payment solutions in Yuansfer, Barcode/QR Code Payment and Transaction QR Code Payment solution.

Barcode/QR Code Payment

The Barcode/QR Code payment is an offline instant payment solution offered by Yuansfer for the in-store checkout. This payment solution enables merchants to collect money by scanning the barcode/QR code that is shown on a customer’s Yuansfer wallet app. The barcode/QR code payment solution is also known as “merchant-scan solution”. Pos workflow 1. A customer selects goods and merchant’s system requests to create transaction to the Yuansfer system.
2. The Yuansfer system returns transaction ID to the merchant’s system.
3. The customer presents the barcode or QR code on their Alipay app or WeChat Pay app for checkout.
4. The merchant’s system sends pay request with the transaction ID and barcode or QR code from the customer.
5. The Yuansfer system sends the payment result to the Merchant’s system.
6. The Merchant’s system shows the payment result to the customer.

Transaction QR Code Payment

The Transaction QR Code payment is an offline instant payment solution offered by Yuansfer for the in-store checkout. This payment solution is making use of the dynamically produced QR code to represent a transaction. In this payment solution, the customer does not need to input the transaction amount, but scan the generated QR code to complete the payment. The transaction QR code payment solution is also known as “customer-scan solution”. Trans qrcode flow 1. A customer selects goods and merchant’s system requests to create a transaction QR code to the Yuansfer system.
2. The Yuansfer system returns the QR code and the merchant shows this QR code to the customer.
3. The customer scans the QR code by using Alipay app or WeChat Pay app to checkout.
4. The Yuansfer system sends the payment result to the merchant’s system when the result is the success.

add()

Endpoint

POST https://mapi.yuansfer.com/app-data-search/v2/add
POST https://mapi.yuansfer.com/app-data-search/v2/add
POST https://mapi.yuansfer.com/app-data-search/v2/add
POST https://mapi.yuansfer.com/app-data-search/v2/add

Example Request

curl "https://mapi.yuansfer.com/app-data-search/v2/add" \
-d "storeNo=300014" \
-d "merchantNo=200043" \
-d "amount=0.01" \
-d "verifySign=verifySign"
<?php
function transAdd()
{
    $url = 'https://mapi.yuansfer.yunkeguan.com/app-data-search/v2/add';
    $token = '59600f2a9ad644c6a9570233560cc94e';

    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'vendor' => 'alipay',
        'amount' => '0.01'
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
    echo "\n";

    $ch = curl_init($url);
    curl_setopt_array($ch, array(
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($params),
    ));

    $result = curl_exec($ch);
    curl_exec($ch);

    echo $result;
    echo "\n";
    return json_decode($result, true);
}

transAdd();
?>
//add
public static String transactionAdd() {
    String url = DOMAIN_URL + TRANSACTION_ADD;
    Map<String, Object> params = new TreeMap<String, Object>();
    params.put("merchantNo", MERCHANT_NO);
    params.put("storeNo", STORE_NO);
    if (StringUtils.isNotEmpty(STORE_ADMIN_NO)) {
        params.put("storeAdminNo", STORE_ADMIN_NO);
    }

    params.put("amount", "0.01");
    String verifySign = verifySignHelper.getYuansferVerifySign(params, YUANSFER_TOKEN);
    params.put("verifySign", verifySign);
    String ret = HttpClientUtils.post(url, null, params);
    System.out.println("---transaction add----");
    System.out.println(ret);
    JSONObject retInfo = (JSONObject)JSONValue.parse(ret);
    JSONObject transaction = (JSONObject)retInfo.get("transaction");
    String transactionNo = transaction.get("transactionNo").toString();
    return transactionNo;
}

Example Response


{
    "ret_msg": "add success ",
    "ret_code": "000100",
    "transaction":{
        "amount": 0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": null,
        "paymentTime": null,
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "init",
        "transactionType": "payment"
    }
}

{
    "ret_msg": "add success ",
    "ret_code": "000100",
    "transaction":{
        "amount": 0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": null,
        "paymentTime": null,
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "init",
        "transactionType": "payment"
    }
}
{
    "ret_msg": "add success ",
    "ret_code": "000100",
    "transaction":{
        "amount": 0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": null,
        "paymentTime": null,
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "init",
        "transactionType": "payment"
    }
}
{
    "ret_msg": "add success ",
    "ret_code": "000100",
    "transaction":{
        "amount": 0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": null,
        "paymentTime": null,
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "init",
        "transactionType": "payment"
    }
}

Use the add() API to initiate a Barcode/QR Code Payment request and create transaction order.

HTTP Request

POST https://mapi.yuansfer.com/app-data-search/v2/add

Request Parameters

Parameter Type Description
merchantNo

required

string The ID of the merchant.
storeNo

required

string The ID of the store.
storeAdminNo

optional

string The ID of the store admin.
amount

required

decimal The transaction amount.
currency

required

enum The three-character currency code that identifies the currency.
The possible values are: “USD”.
verifySign

required

string The parameter signature.

Response

Parameter Type Description
transaction object The transaction object.
ret_msg string The response return message.
ret_code string The response return code. For more details, see here.

pay()

Endpoint

POST https://mapi.yuansfer.com/app-data-search/v2/pay
POST https://mapi.yuansfer.com/app-data-search/v2/pay
POST https://mapi.yuansfer.com/app-data-search/v2/pay
POST https://mapi.yuansfer.com/app-data-search/v2/pay

Example Request

curl "https://mapi.yuansfer.com/app-data-search/v2/pay" \
-d "storeNo=300014" \
-d "merchantNo=200043" \
-d "transactionNo=transactionNo" \
-d "paymentBarcode=paymentBarcode" \
-d "vendor=alipay" \
-d "verifySign=verifySign"
<?php
function transPay()
{
    $url = 'https://mapi.yuansfer.yunkeguan.com/app-data-search/v2/pay';
    $token = '59600f2a9ad644c6a9570233560cc94e';

    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'transactionNo' => '297553565108438359',
        'vendor' => 'alipay',
        'amount' => '0.01',
        'paymentBarcode' => '280526696410694666'
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
    echo "\n";

    $ch = curl_init($url);
    curl_setopt_array($ch, array(
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($params),
    ));

    $result = curl_exec($ch);
    curl_exec($ch);

    echo $result;
    echo "\n";
    return json_decode($result, true);
}

transPay();
?>
//pay
public static void transactionPay(String transactionNo) {
    String url = DOMAIN_URL + TRANSACTION_PAY;
    Map<String, Object> params = new TreeMap<String, Object>();
    params.put("merchantNo", MERCHANT_NO);
    params.put("storeNo", STORE_NO);
    if (StringUtils.isNotEmpty(STORE_ADMIN_NO)) {
        params.put("storeAdminNo", STORE_ADMIN_NO);
    }

    params.put("transactionNo", transactionNo);
    params.put("paymentBarcode", "286754322648217439");
    params.put("vendor", "alipay");
    String verifySign = verifySignHelper.getYuansferVerifySign(params, YUANSFER_TOKEN);
    params.put("verifySign", verifySign);
    String ret = HttpClientUtils.post(url, null, params);
    System.out.println("---transaction pay----");
    System.out.println(ret);
}

Example Response


{
    "ret_msg": "pay success ",
    "ret_code": "000100",
    "transaction":{
        "amount": 0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": null,
        "paymentTime": "2018-02-16 18:17:57",
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "success",
        "transactionType": "payment"
    }
}

{
    "ret_msg": "pay success ",
    "ret_code": "000100",
    "transaction":{
        "amount": 0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": null,
        "paymentTime": "2018-02-16 18:17:57",
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "success",
        "transactionType": "payment"
    }
}
{
    "ret_msg": "pay success ",
    "ret_code": "000100",
    "transaction":{
        "amount": 0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": null,
        "paymentTime": "2018-02-16 18:17:57",
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "success",
        "transactionType": "payment"
    }
}
{
    "ret_msg": "pay success ",
    "ret_code": "000100",
    "transaction":{
        "amount": 0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": null,
        "paymentTime": "2018-02-16 18:17:57",
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "success",
        "transactionType": "payment"
    }
}

Use the pay() API to place an order in the Barcode/QR Code Payment.

HTTP Request

POST https://mapi.yuansfer.com/app-data-search/v2/pay

Request Parameters

Parameter Type Description
merchantNo

required

string The ID of the merchant.
storeNo

required

string The ID of the store.
storeAdminNo

optional

string The ID of the store admin.
transactionNo

required

string The ID of the transaction in the Yuansfer system.
paymentBarcode

required

string The payment barcode from the customer.
vendor

required

enum The payment method.
The possible values are: “alipay”, “wechatpay”, “unionpay”.
verifySign

required

string The parameter signature.

Response

Parameter Type Description
transaction object The transaction object.
ret_msg string The response return message.
ret_code string The response return code. For more details, see here.

create-trans-qrcode()

Endpoint

POST https://mapi.yuansfer.com/app-data-search/v2/create-trans-qrcode
POST https://mapi.yuansfer.com/app-data-search/v2/create-trans-qrcode
POST https://mapi.yuansfer.com/app-data-search/v2/create-trans-qrcode
POST https://mapi.yuansfer.com/app-data-search/v2/create-trans-qrcode

Example Request

curl "https://mapi.yuansfer.com/app-data-search/v2/create-trans-qrcode" \
-d "storeNo=300014" \
-d "merchantNo=200043" \
-d "currency=USD" \
-d "reference=reference" \
-d "vendor=alipay" \
-d "ipnUrl=IPN URL" \
-d "amount=0.01" \
-d "verifySign=verifySign"
<?php
function transQrcode()
{
    $url = 'https://mapi.yuansfer.yunkeguan.com/app-data-search/v2/create-trans-qrcode';
    $token = '59600f2a9ad644c6a9570233560cc94e';

    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'vendor' => 'alipay',
        'amount' => '0.01',
        'ipnUrl' => 'https://nengjtian.s1.natapp.cc/login/test',
        'reference' => 'test2018061901',
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
    echo "\n";

    $ch = curl_init($url);
    curl_setopt_array($ch, array(
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($params),
    ));

    $result = curl_exec($ch);
    curl_exec($ch);

    echo $result;
    echo "\n";
    return json_decode($result, true);
}

transQrcode();
?>

public static void transQrcode() {
    String url = DOMAIN_URL + TRANS_QRCODE;
    Map<String, Object> params = new TreeMap<String, Object>();
    params.put("merchantNo", MERCHANT_NO);
    params.put("storeNo", STORE_NO);
    if (StringUtils.isNotEmpty(STORE_ADMIN_NO)) {
        params.put("storeAdminNo", STORE_ADMIN_NO);
    }

    params.put("vendor", "alipay");
    params.put("amount", "0.01");
    params.put("ipnUrl", "https://nengjtian.s1.natapp.cc/login/test");
    params.put("reference", "testabc100");
    String verifySign = verifySignHelper.getYuansferVerifySign(params, YUANSFER_TOKEN);
    params.put("verifySign", verifySign);
    String ret = HttpClientUtils.post(url, null, params);
    System.out.println("---trans-qrcode-create ----");
    System.out.println(ret);
}

Example Response


{
    "amount":"0.01",
    "reference":"testabc1001",
    "deepLink":"url1",
    "transactionNo":"297553556919345525",
    "ret_code":"000100",
    "timeout":"120",
    "qrcodeUrl":"url2"
}

{
    "amount":"0.01",
    "reference":"testabc1001",
    "deepLink":"url1",
    "transactionNo":"297553556919345525",
    "ret_code":"000100",
    "timeout":"120",
    "qrcodeUrl":"url2"
}
{
    "amount":"0.01",
    "reference":"testabc1001",
    "deepLink":"url1",
    "transactionNo":"297553556919345525",
    "ret_code":"000100",
    "timeout":"120",
    "qrcodeUrl":"url2"
}
{
    "amount":"0.01",
    "reference":"testabc1001",
    "deepLink":"url1",
    "transactionNo":"297553556919345525",
    "ret_code":"000100",
    "timeout":"120",
    "qrcodeUrl":"url2"
}

Use the create-trans-qrcode() API to create transaction and get QR code for customers to scan to pay in Transaction QR Code Payment. Customers scan this QR code by using Alipay app or WeChat Pay app to checkout.

HTTP Request

POST https://mapi.yuansfer.com/app-data-search/v2/create-trans-qrcode

Request Parameters

Parameter Type Description
merchantNo

required

string The ID of the merchant.
storeNo

required

string The ID of the store.
storeAdminNo

optional

string The ID of the store admin.
currency

required

enum The three-character currency code that identifies the currency.
The possible values are: “USD”.
vendor

required

enum The payment method.
The possible values are: “alipay”, “wechatpay”. (“unionpay”not supported yet)
reference

required

string The ID of the transaction in the merchant’s system.
amount

required

decimal The transaction amount.
ipnUrl

optional

string The Instant Payment Notification Handler url. IPN url must be secure.
For more details, see here.
For a list of parameters, see here.
needQrcode

optional

string The possible values are: true or false. Default value is true.
If this parameter is true, the Yuansfer system will help to create the QR code picture.
If this parameter is false, the Yuansfer system will not create QR Code picture.
verifySign

required

string The parameter signature.

Response

Parameter Type Description
transactionNo string The ID of the transaction.
amount decimal The transaction amount.
timeout integer The timeout in minute.
reference string The ID of the transaction in the merchant’s system.
deepLink string The deep link url.
qrcodeUrl string The url of the transaction QR code.
ret_msg string The response return message.
ret_code string The response return code. For more details, see here.

reverse()

Endpoint

POST https://mapi.yuansfer.com/app-data-search/v2/reverse

Example Request

curl "https://mapi.yuansfer.com/app-data-search/v2/reverse" \
-d "storeNo=300014" \
-d "merchantNo=200043" \
-d "transactionNo=transactionNo" \
-d "verifySign=verifySign"

<?php
function transReverse()
{
    $url = 'https://mapi.yuansfer.yunkeguan.com/app-data-search/v2/reverse';
    $token = '59600f2a9ad644c6a9570233560cc94e';

    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'transactionNo' => '297553565108438359'
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
    echo "\n";

    $ch = curl_init($url);
    curl_setopt_array($ch, array(
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($params),
    ));

    $result = curl_exec($ch);
    curl_exec($ch);

    echo $result;
    echo "\n";
    return json_decode($result, true);
}

transReverse();
?>
//reverse
public static void transactionReverse(String transactionNo) {
    String url = DOMAIN_URL + TRANSACTION_REVERSE;
    Map<String, Object> params = new TreeMap<String, Object>();
    params.put("merchantNo", MERCHANT_NO);
    params.put("storeNo", STORE_NO);
    if (StringUtils.isNotEmpty(STORE_ADMIN_NO)) {
        params.put("storeAdminNo", STORE_ADMIN_NO);
    }

    params.put("transactionNo", transactionNo);
    String verifySign = verifySignHelper.getYuansferVerifySign(params, YUANSFER_TOKEN);
    params.put("verifySign", verifySign);
    String ret = HttpClientUtils.post(url, null, params);
    System.out.println("---transaction reverse----");
    System.out.println(ret);
}

Example Response


{
    "ret_msg": "reverse success ",
    "ret_code": "000100",
    "transaction":{
        "amount": 0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": null,
        "paymentTime": "2018-02-16 18:17:57",
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "reversed",
        "transactionType": "payment"
    }
}

{
    "ret_msg": "reverse success ",
    "ret_code": "000100",
    "transaction":{
        "amount": 0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": null,
        "paymentTime": "2018-02-16 18:17:57",
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "reversed",
        "transactionType": "payment"
    }
}
{
    "ret_msg": "reverse success ",
    "ret_code": "000100",
    "transaction":{
        "amount": 0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": null,
        "paymentTime": "2018-02-16 18:17:57",
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "reversed",
        "transactionType": "payment"
    }
}
{
    "ret_msg": "reverse success ",
    "ret_code": "000100",
    "transaction":{
        "amount": 0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": null,
        "paymentTime": "2018-02-16 18:17:57",
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "reversed",
        "transactionType": "payment"
    }
}

Use the reverse() API to cancel a transaction when the PAY API call did NOT return a clear result.
If the payment result of that trasaction is failure, the Yuansfer system will cancel the transaction.
If the payment result of that transaction is success, the Yuansfer system will refund the amount of the transaction.

HTTP Request

POST https://mapi.yuansfer.com/app-data-search/v2/reverse

Request Parameters

Parameter Type Description
merchantNo

required

string The ID of the merchant.
storeNo

required

string The ID of the store.
storeAdminNo

optional

string The ID of the store admin.
transactionNo

optional

string The ID of the transaction in the Yuansfer system.
Either transactionNo or reference is required.
reference

optional

string The ID of the transaction in the merchant’s system.
Either transactionNo or reference is required.
verifySign

required

string The parameter signature.

Response

Parameter Type Description
transaction object The transaction object.
ret_msg string The response return message.
ret_code string The response return code. For more details, see here.

refund()

Endpoint

POST https://mapi.yuansfer.com/app-data-search/v2/refund

The return info of transaction-refund API

curl "https://mapi.yuansfer.com/app-data-search/v2/refund" \
-d "storeNo=300014" \
-d "merchantNo=200043" \
-d "transactionNo=transactionNo" \
-d "refundAmount=refundAmount" \
-d "verifySign=verifySign"
<?php
function transRefund()
{
    $url = 'https://mapi.yuansfer.yunkeguan.com/app-data-search/v2/refund';
    $token = '59600f2a9ad644c6a9570233560cc94e';

    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'transactionNo' => '297553565108438359',
        'refundAmount' => '0.01'
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
    echo "\n";

    $ch = curl_init($url);
    curl_setopt_array($ch, array(
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($params),
    ));

    $result = curl_exec($ch);
    curl_exec($ch);

    echo $result;
    echo "\n";
    return json_decode($result, true);
}

transRefund();
?>
//refund
public static void transactionRefund(String transactionNo) {
    String url = DOMAIN_URL + TRANSACTION_REFUND;
    Map<String, Object> params = new TreeMap<String, Object>();
    params.put("merchantNo", MERCHANT_NO);
    params.put("storeNo", STORE_NO);
    if (StringUtils.isNotEmpty(STORE_ADMIN_NO)) {
        params.put("storeAdminNo", STORE_ADMIN_NO);
    }

    params.put("transactionNo", transactionNo);
    params.put("refundAmount", "0.01");
    String verifySign = verifySignHelper.getYuansferVerifySign(params, YUANSFER_TOKEN);
    params.put("verifySign", verifySign);
    String ret = HttpClientUtils.post(url, null, params);
    System.out.println("---transaction refund----");
    System.out.println(ret);
}

Example Response

{
    "ret_msg": "refund success ",
    "ret_code": "000100",
    "refundTransaction":{
        "amount": -0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": "297553554508274471",
        "paymentTime": "2018-02-16 18:17:57",
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "success",
        "transactionType": "refund"
    }
}
{
    "ret_msg": "refund success ",
    "ret_code": "000100",
    "refundTransaction":{
        "amount": -0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": "297553554508274471",
        "paymentTime": "2018-02-16 18:17:57",
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "success",
        "transactionType": "refund"
    }
}
{
    "ret_msg": "refund success ",
    "ret_code": "000100",
    "refundTransaction":{
        "amount": -0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": "297553554508274471",
        "paymentTime": "2018-02-16 18:17:57",
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "success",
        "transactionType": "refund"
    }
}
{
    "ret_msg": "refund success ",
    "ret_code": "000100",
    "refundTransaction":{
        "amount": -0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": "297553554508274471",
        "paymentTime": "2018-02-16 18:17:57",
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "success",
        "transactionType": "refund"
    }
}

Use the refund() API to refund an existing payment. Alipay and WeChat Pay will refund the payment according to their refund policy after the refund request is accepted successfully.
A refund can be partial and a transaction can have multiple refunds as long as the total refund amount is no greater than the original The transaction amount.

HTTP Request

POST https://mapi.yuansfer.com/app-data-search/v2/refund

Request Parameters

Parameter Type Description
merchantNo

required

string The ID of the merchant.
storeNo

required

string The ID of the store.
storeAdminNo

optional

string The ID of the store admin.
transactionNo

optional

string The ID of the transaction in the Yuansfer system.
Either transactionNo or reference is required.
reference

optional

string The ID of the transaction in the merchant’s system.
Either transactionNo or reference is required.
verifySign

required

string The parameter signature.

Response

Parameter Type Description
refundTransaction object The transaction object.
ret_msg string The response return message.
ret_code string The response return code. For more details, see here.

detail()

Endpoint

POST https://mapi.yuansfer.com/app-data-search/v2/detail
POST https://mapi.yuansfer.com/app-data-search/v2/detail
POST https://mapi.yuansfer.com/app-data-search/v2/detail
POST https://mapi.yuansfer.com/app-data-search/v2/detail

Example Request

curl "https://mapi.yuansfer.com/app-data-search/v2/detail" \
-d "storeNo=300014" \
-d "merchantNo=200043" \
-d "transactionNo=transactionNo" \
-d "verifySign=verifySign"
<?php
function transDetail()
{
    $url = 'https://mapi.yuansfer.yunkeguan.com/app-data-search/v2/detail';
    $token = '59600f2a9ad644c6a9570233560cc94e';

    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'transactionNo' => '297553565108438359'
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
    echo "\n";

    $ch = curl_init($url);
    curl_setopt_array($ch, array(
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($params),
    ));

    $result = curl_exec($ch);
    curl_exec($ch);

    echo $result;
    echo "\n";
    return json_decode($result, true);
}

transDetail();
?>
//transaction detail
public static void transactionDetail(String transactionNo) {
    String url = DOMAIN_URL + TRANSACTION_DETAIL;
    Map<String, Object> params = new TreeMap<String, Object>();
    params.put("merchantNo", MERCHANT_NO);
    params.put("storeNo", STORE_NO);
    if (StringUtils.isNotEmpty(STORE_ADMIN_NO)) {
        params.put("storeAdminNo", STORE_ADMIN_NO);
    }

    params.put("transactionNo", transactionNo);
    String verifySign = verifySignHelper.getYuansferVerifySign(params, YUANSFER_TOKEN);
    params.put("verifySign", verifySign);
    String ret = HttpClientUtils.post(url, null, params);
    System.out.println("---transaction detail----");
    System.out.println(ret);
}

Example Response


{
    "ret_msg": "query success ",
    "ret_code": "000100",
    "transaction":{
        "amount": 0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": null,
        "paymentTime": "2018-02-16 18:17:57",
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "success",
        "transactionType": "payment"
    }
}

{
    "ret_msg": "query success ",
    "ret_code": "000100",
    "transaction":{
        "amount": 0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": null,
        "paymentTime": "2018-02-16 18:17:57",
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "success",
        "transactionType": "payment"
    }
}
{
    "ret_msg": "query success ",
    "ret_code": "000100",
    "transaction":{
        "amount": 0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": null,
        "paymentTime": "2018-02-16 18:17:57",
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "success",
        "transactionType": "payment"
    }
}
{
    "ret_msg": "query success ",
    "ret_code": "000100",
    "transaction":{
        "amount": 0.01,
        "createTime": "2018-02-16 18:17:57",
        "currency": "USD",
        "exchangeRate": null,
        "merchantNo": "200043",
        "originalTransactionNo": null,
        "paymentTime": "2018-02-16 18:17:57",
        "refundAmount": 0,
        "storeAdminNo": "3000140001",
        "storeNo": "300014",
        "transactionNo": "297553554508274472",
        "transactionStatus": "success",
        "transactionType": "payment"
    }
}

Use the detail() API to get details of transaction.

HTTP Request

POST https://mapi.yuansfer.com/app-data-search/v2/detail

Request Parameters

Parameter Required Type Description
merchantNo

required

string The ID of the merchant.
storeNo

required

string The ID of the store.
storeAdminNo

optional

string The ID of the store admin.
transactionNo

optional

string The ID of the transaction in the Yuansfer system.
Either transactionNo or reference is required.
reference

optional

string The ID of the transaction in the merchant’s system.
Either transactionNo or reference is required.
verifySign

required

string The parameter signature.

Response

Parameter Type Description
transaction object The transaction object.
ret_msg string The response return message.
ret_code string The response return code. For more details, see here.

WeChat Mini-Program Payments API

The Yuansfer also provides WeChat Mini-Program Payments API.

WeChat Mini-Program Payment authority open process:
1. The main body of WeChat Mini-Program Payment should be American company.
2. To provide links to WeChat Mini-Program Payment, as well as the appid.
3. Yuansfer submitted to WeChat official team for verification.
4. WeChat opens the payment authority, pays according to the development document docking small program.

See official documents of WeChat Mini-Program Payments.

prepay()

Use the prepay() API to process WeChat payment.

Example Request:

curl "https://mapi.yuansfer.com/micropay/v2/prepay" \
-d amount="1.00" \
-d storeNo="300014" \
-d currency="USD" \
-d merchantNo="200043" \
-d ipnUrl="https://wx.yuansfer.yunkeguan.com/wx" \
-d reference="seq_1525922323" \
-d description="testDescription"\
-d note="testNote"\
-d openid="***"\
-d vendor="wechatpay" \
-d verifySign="4f0cc35728849e4b4aa4a176f4a5edac"
/<?php
function microprepay()
{
    $url = 'https://mapi.yuansfer.com/micropay/v2/prepay';
    $token = '5cbfb079f15b150122261c8537086d77a';

    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'amount' => '0.01',
        'currency' => 'USD',
        'vendor' => 'wechatpay',
        'ipnUrl' => 'https://nengjtian.s1.natapp.cc/login/test',        
        'reference' => 'test2018070101',
        'description' => 'test_description',
        'note' => 'test_note',
        'openid' => '***'
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
    echo "\n";

    $ch = curl_init($url);
    curl_setopt_array($ch, array(
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($params),
    ));

    $result = curl_exec($ch);
    curl_exec($ch);

    echo $result;
    echo "\n";
    return json_decode($result, true);
}

microprepay();
?>
/**
 * prepay test
 * @author zhoukai
 *
 */
public class MicropayTest {

    public static final String TEST_URL = "https://mapi.yuansfer.yunkeguan.com";            //testing domain
    public static final String PROD_URL = "https://mapi.yuansfer.com";                      //production domain
    public static final String YUANSFER_TOKEN = "5c5fe30183be69fceff8174358d4b8ae";


    public static void main(String[] args) {
        YuansferVerifySignHelper helper = new YuansferVerifySignHelper();

        AppMircopayDto dto = paramSetting();
        Map<String, Object> params = ReflectionUtils.convertBean2MapIgnoreNullVal(dto, new String[]{"serialVersionUID"});
        String verifySign = helper.getYuansferVerifySign(params, YUANSFER_TOKEN); 
        params.put("verifySign", verifySign);

        String url = TEST_URL + "/micropay/v2/prepay";
        String ret = HttpClientUtils.post(url, null, params);
        System.out.println(ret);
    }

    public static AppMircopayDto paramSetting() {
        AppMircopayDto dto = new AppMircopayDto();
        /**
         * merchantNo,storeNo is necessory, and they are provided by Yuansfer
         */
        dto.setMerchantNo("200043");                                                //The Merchant NO.
        dto.setStoreNo("300014");                                                   //The Store NO.

        /**
         * transaction infomation is necessory
         */
        dto.setAmount("0.01");                                                      //The amount, unit "division"
        dto.setCurrency("USD");                                                     //currency, "USD" or "CAD"
        dto.setIpnUrl("https://nengjtian.s1.natapp.cc/login/test");                 //Asynchronous callback address
        dto.setReference("9091023122");                                             //order NO. of client's system
        dto.setOpenid("***");                                                       //wechat openid
        dto.setVendor("wechatpay");                                                 //"wechatpay" 

        /**
         * note,desription are optional 
         */
        dto.setDescription("test-description");                                     //description
        dto.setNote("test-note");                                                   //note

        return dto;
    }
}
func mciropay(t *table) {
    req := yuan.Securepay{
        MerchantNo:  "200043", //customer The merchant NO.
        StoreNo:     "300014",
        Currency:    "USD",
        Amount:      "0.01",
        Vendor:      "wechatpay",
        Reference:   fmt.Sprintf("demo_%d", time.Now().Unix()), //sequence number of customer system
        IpnUrl:      "https://customer-ipn",        //internet accessible 
        Description: "description",
        Note:        "note",
        Openid:      "***",
    }
    resp, err := req.PostToYuansfer(yuansferToken)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(resp)
}

Example Response:


{
    "ret_msg": "prepay success",
    "ret_code": "000100",
    "result": {
        "timeStamp": "1510341967363",
        "nonceStr": "a611bda03d544b9f941393c48c2e517f",
        "package": "prepay_id=wx201711110326070ccf2a7f060678638664",
        "signType": "MD5",
        "paySign": "09E5BE5B9D93080E3B7DD05C8F41049E"
    }
}

{
    "ret_msg": "prepay success",
    "ret_code": "000100",
    "result": {
        "timeStamp": "1510341967363",
        "nonceStr": "a611bda03d544b9f941393c48c2e517f",
        "package": "prepay_id=wx201711110326070ccf2a7f060678638664",
        "signType": "MD5",
        "paySign": "09E5BE5B9D93080E3B7DD05C8F41049E"
    }
}
{
    "ret_msg": "prepay success",
    "ret_code": "000100",
    "result": {
        "timeStamp": "1510341967363",
        "nonceStr": "a611bda03d544b9f941393c48c2e517f",
        "package": "prepay_id=wx201711110326070ccf2a7f060678638664",
        "signType": "MD5",
        "paySign": "09E5BE5B9D93080E3B7DD05C8F41049E"
    }
}
{
    "ret_msg": "prepay success",
    "ret_code": "000100",
    "result": {
        "timeStamp": "1510341967363",
        "nonceStr": "a611bda03d544b9f941393c48c2e517f",
        "package": "prepay_id=wx201711110326070ccf2a7f060678638664",
        "signType": "MD5",
        "paySign": "09E5BE5B9D93080E3B7DD05C8F41049E"
    }
}

HTTP Request

POST https://mapi.yuansfer.com/micropay/v2/prepay

Request Parameters

Parameter Type Description
merchantNo

required

string The ID of the merchant.
storeNo

required

String The ID of the store.
amount

optional

decimal The transaction amount.
Either amount or rmbAmount is required.
rmbAmount

optional

decimal The transaction amount in RMB.
Either amount or rmbAmount is required.
currency

required

enum The three-character currency code that identifies the currency.
The possible values are: “USD”.
vendor

required

enum wechatpay
ipnUrl

required

String The Instant Payment Notification Handler url. IPN url must be secure.
For more details, see here.
For a list of parameters, see here.
openid

required

string openid from WeChat.
reference

required

string The ID of the transaction in the merchant’s system.
description

optional

string The description of the transaction which will be displayed on the invoice.
note

optional

string The payment note.
verifySign

required

string The parameter signature.

Response

Parameter Type Description
result object The result object.
ret_msg string The response return message.
ret_code string The response return code. For more details, see here.

result object

Parameter Type Description
timeStamp string The timestamp.
nonceStr string A random string.
package string prepay_id infomaition.
signType string The signature type.
paySign string The signature.

refund()

Example Request:

curl "https://mapi.yuansfer.com/micropay/v2/refund" \
-d "amount=0.01" \
-d "storeNo=300014" \
-d "merchantNo=200043" \
-d "reference=origin_reference" \
-d "verifySign=verifySign"
<?php
function micropayRefund()
{
    $url = 'https://mapi.yuansfer.com/micropay/v2/refund';
    $token = '5cbfb079f15b150122261c8537086d77a';

    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'amount' => '0.01',
        'reference' => 'test2018070101'
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
    echo "\n";

    $ch = curl_init($url);
    curl_setopt_array($ch, array(
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($params),
    ));

    $result = curl_exec($ch);
    curl_exec($ch);

    echo $result;
    echo "\n";
    return json_decode($result, true);
}

micropayRefund();
?>
public class MicropayRefundTest {
    public static final String TEST_URL = "https://mapi.yuansfer.yunkeguan.com";            //testing domain
    public static final String PROD_URL = "https://mapi.yuansfer.com";                      //production domain
    public static final String YUANSFER_TOKEN = "5c5fe30183be69fceff8174358d4b8ae";


    public static void main(String[] args) {
        YuansferSecurepayRefundDto refundDto = new YuansferSecurepayRefundDto();
        YuansferVerifySignHelper verifyHelper = new YuansferVerifySignHelper();
        refundDto.setAmount("0.01");
        refundDto.setCurrency("USD");
        refundDto.setMerchantNo("200043");
        refundDto.setStoreNo("300014");
        refundDto.setReference("9091023122");

        Map<String, Object> params = ReflectionUtils.convertBean2MapIgnoreNullVal(refundDto, new String[]{"serialVersionUID"});
        String verifySign = verifyHelper.getYuansferVerifySign(params, YUANSFER_TOKEN);
        refundDto.setVerifySign(verifySign);
        params.put("verifySign", verifySign);

        String url = TEST_URL + "/micropay/v2/refund";
        String ret = HttpClientUtils.post(url, null, params);
        JSON json = JSON.parseObject(ret);
        System.out.println(json);
    }
}
func refund(t *table) {
    req := yuan.Refund{
        MerchantNo:       "200043", //customer The merchant NO.
        StoreNo:          "300014",
        Currency:         "USD",
        Reference:        "original sequence No.", //sequence number of customer system
        Amount:           "0.01",
    }

    resp, err := req.PostToYuansfer(yuansferToken)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(resp)
}

Example Response

{
    "result":{
        "amount": "0.01",
        "status": "success",
        "currency": "CNY",
        "reference": "44444",
        "refundAmount": "0.01",
        "refundTransactionId": "297245675773380538",
        "oldTransactionId": "297245675773319174"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "result":{
        "amount": "0.01",
        "status": "success",
        "currency": "CNY",
        "reference": "44444",
        "refundAmount": "0.01",
        "refundTransactionId": "297245675773380538",
        "oldTransactionId": "297245675773319174"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "result":{
        "amount": "0.01",
        "status": "success",
        "currency": "CNY",
        "reference": "44444",
        "refundAmount": "0.01",
        "refundTransactionId": "297245675773380538",
        "oldTransactionId": "297245675773319174"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "result":{
        "amount": "0.01",
        "status": "success",
        "currency": "CNY",
        "reference": "44444",
        "refundAmount": "0.01",
        "refundTransactionId": "297245675773380538",
        "oldTransactionId": "297245675773319174"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}

Use the refund API to refund the WeChat Mini-Program payment.

HTTP Request

POST https://mapi.yuansfer.com/micropay/v2/refund

Request Parameters

Parameter Type Description
merchantNo

required

string The ID of the merchant.
storeNo

required

String The ID of the store.
amount

optional

decimal The transaction amount.
Either amount or rmbAmount is required.
rmbAmount

optional

decimal The transaction amount in RMB.
Either amount or rmbAmount is required.
reference

required

string The ID of the transaction in the merchant’s system.
verifySign

required

string The parameter signature.

Response

Parameter Type Description
result object The result object.
ret_msg string The response return message.
ret_code string The response return code. For more details, see here.

result object

Parameter Type Description
amount decimal The transaction amount.
refundAmount decimal The transaction refund amount.
currency string The three-character currency code that identifies the currency.
The possible values are: “USD”.
status enum The state of the refund.
reference string The ID of the transaction in the merchant’s system.
refundTransactionId string The ID of the refund transaction in the Yuansfer system.
oldTransactionId string The ID of the transaction in the Yuansfer system which the refund transaction is based on.

reference-query()

Http Request:

curl "https://mapi.yuansfer.com/micropay/v2/reference-query" \
-d "storeNo=300014" \
-d "merchantNo=200043" \
-d "reference=origin_reference" \
-d "verifySign=verifySign"
<?php
function micropayReferenceQuery()
{
    $url = 'https://mapi.yuansfer.com/micropay/v2/reference-query';
    $token = '5cbfb079f15b150122261c8537086d77a';

    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'reference' => 'test2018070101'
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
    echo "\n";

    $ch = curl_init($url);
    curl_setopt_array($ch, array(
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($params),
    ));

    $result = curl_exec($ch);
    curl_exec($ch);

    echo $result;
    echo "\n";
    return json_decode($result, true);
}

microReferenceQuery();
?>
public class MircopayReferenceQueryTest {
    public static final String TEST_URL = "https://mapi.yuansfer.yunkeguan.com";            //testing domain
    public static final String PROD_URL = "https://mapi.yuansfer.com";                      //production domain
    public static final String YUANSFER_TOKEN = "5cbfb079f15b150122261c8537086d77a";

    public static void main(String[] args) {
        YuansferVerifySignHelper helper = new YuansferVerifySignHelper();

        YuansferSecurepayQueryDto dto = paramSetting();
        Map<String, Object> params = ReflectionUtils.convertBean2MapIgnoreNullVal(dto, new String[]{"serialVersionUID"});
        String verifySign = helper.getYuansferVerifySign(params, YUANSFER_TOKEN);//得到verifySign
        params.put("verifySign", verifySign);

        String url = TEST_URL + "/micropay/v2/reference-query";
        String ret = HttpClientUtils.post(url, null, params);
        System.out.println(ret);
    }

    public static YuansferSecurepayQueryDto paramSetting() {
        YuansferSecurepayQueryDto dto = new YuansferSecurepayQueryDto();

        dto.setMerchantNo("200043");                                                //The merchant NO.
        dto.setStoreNo("300014");                                                   //The store NO.
        dto.setReference("20180126162433");
        return dto;
    }
}


func query(t *table) {
    req := yuan.Query{
        MerchantNo: "200043", //customer The merchant NO.
        StoreNo:    "300014",
        Currency:   "USD",
        Reference:  "original sequence No.", //sequence number of customer system
        Terminal:   "ONLINE",
    }

    //TO CALL VERIFYSIGN
    resp, err := req.PostToYuansfer(yuansferToken)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(resp)
}

Response:


{
    "result":{
    "reference": "test20180801006",
    "transactionId": "297553569604475564",
    "amount": "2.00",
    "refundInfo":[
        {
            "refundTransactionId": "297553569604658581",
            "refundAmount": "1.50"
        },
        {
            "refundTransactionId": "297553569604680588",
            "refundAmount": "0.50"
        }
    ],
    "currency": "CNY",
    "status": "success"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}

{
    "result":{
    "reference": "test20180801006",
    "transactionId": "297553569604475564",
    "amount": "2.00",
    "refundInfo":[
        {
            "refundTransactionId": "297553569604658581",
            "refundAmount": "1.50"
        },
        {
            "refundTransactionId": "297553569604680588",
            "refundAmount": "0.50"
        }
    ],
    "currency": "CNY",
    "status": "success"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "result":{
    "reference": "test20180801006",
    "transactionId": "297553569604475564",
    "amount": "2.00",
    "refundInfo":[
        {
            "refundTransactionId": "297553569604658581",
            "refundAmount": "1.50"
        },
        {
            "refundTransactionId": "297553569604680588",
            "refundAmount": "0.50"
        }
    ],
    "currency": "CNY",
    "status": "success"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "result":{
    "reference": "test20180801006",
    "transactionId": "297553569604475564",
    "amount": "2.00",
    "refundInfo":[
        {
            "refundTransactionId": "297553569604658581",
            "refundAmount": "1.50"
        },
        {
            "refundTransactionId": "297553569604680588",
            "refundAmount": "0.50"
        }
    ],
    "currency": "CNY",
    "status": "success"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}

Use the reference-query() API to get transaction details by ID of the transaction in the merchant’s system in WeChat Mini-Program payment.

HTTP Request

POST https://mapi.yuansfer.com/micropay/v2/reference-query

Request Parameters

Parameter Type Description
merchantNo

required

string The ID of the merchant.
storeNo

required

String The ID of the store.
reference

required

string The ID of the transaction in the merchant’s system.
verifySign

required

string The parameter signature.

Response

Parameter Type Description
result object The result object.
ret_msg string The response return message.
ret_code string The response return code. For more details, see here.

result object

Parameter Type Description
reference string The ID of the transaction in the merchant’s system.
transactionId string The ID of the transaction in the Yuansfer system.
amount decimal The transaction amount.
status string The status of the transaction.
currency string The three-character currency code that identifies the currency.
The possible values are: “USD”.
refundInfo array The array of refundInfo object.

refundInfo object

Parameter Type Description
refundTransactionId string The ID of the refund transaction in the Yuansfer system.
refundAmount string The refund amount.

Data Search API

trans-list()

Endpoint

POST https://mapi.yuansfer.com/app-data-search/v2/trans-list
POST https://mapi.yuansfer.com/app-data-search/v2/trans-list
POST https://mapi.yuansfer.com/app-data-search/v2/trans-list
POST https://mapi.yuansfer.com/app-data-search/v2/trans-list

Example Request

curl "https://mapi.yuansfer.com/app-data-search/v2/trans-list" \
-d "storeNo=300014" \
-d "merchantNo=200043" \
-d "startDate=startDate" \
-d "endDate=endDate" \
-d "verifySign=verifySign"
<?php
function transList()
{
    $url = 'https://mapi.yuansfer.yunkeguan.com/app-data-search/v2/trans-list';
    $token = '59600f2a9ad644c6a9570233560cc94e';

    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'startDate' => '20180619',
        'endDate' => '20180619'
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
    echo "\n";

    $ch = curl_init($url);
    curl_setopt_array($ch, array(
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($params),
    ));

    $result = curl_exec($ch);
    curl_exec($ch);

    echo $result;
    echo "\n";
    return json_decode($result, true);
}

transList();
?>
//transaction list
public static void transactionList(String startDate, String endDate) {
    String url = DOMAIN_URL + TRANSACTION_LIST;
    Map<String, Object> params = new TreeMap<String, Object>();
    params.put("merchantNo", MERCHANT_NO);
    params.put("storeNo", STORE_NO);
    if (StringUtils.isNotEmpty(STORE_ADMIN_NO)) {
        params.put("storeAdminNo", STORE_ADMIN_NO);
    }

    params.put("startDate", startDate);
    params.put("endDate", endDate);
    String verifySign = verifySignHelper.getYuansferVerifySign(params, YUANSFER_TOKEN);
    params.put("verifySign", verifySign);
    String ret = HttpClientUtils.post(url, null, params);
    System.out.println("---transaction list----");
    System.out.println(ret);
}

Example Response


{
    "size": 2,
    "transactions":[
        {
            "amount": -0.01,
            "createTime": "2018-03-02 14:49:38",
            "currency": "USD",
            "exchangeRate": "6.361300",
            "merchantNo": "200043",
            "originalTransactionNo": "297553555705268810",
            "paymentTime": "2018-03-02 14:49:38",
            "refundAmount": 0,
            "storeAdminNo": null,
            "storeNo": "300014",
            "transactionNo": "297553555705374195",
            "transactionStatus": "success",
            "transactionType": "refund",
            "vendor": "wechatpay"
        },
        {
            "amount": 0.01,
            "createTime": "2018-03-02 14:47:52",
            "currency": "USD",
            "exchangeRate": "6.361300",
            "merchantNo": "200043",
            "originalTransactionNo": null,
            "paymentTime": "2018-03-02 14:48:07",
            "refundAmount": 0.01,
            "storeAdminNo": null,
            "storeNo": "300014",
            "transactionNo": "297553555705268810",
            "transactionStatus": "success",
            "transactionType": "payment",
            "vendor": "wechatpay"
        }
    ],
    "ret_msg": "query success ",
    "ret_code": "000100"
}

{
    "size": 2,
    "transactions":[
        {
            "amount": -0.01,
            "createTime": "2018-03-02 14:49:38",
            "currency": "USD",
            "exchangeRate": "6.361300",
            "merchantNo": "200043",
            "originalTransactionNo": "297553555705268810",
            "paymentTime": "2018-03-02 14:49:38",
            "refundAmount": 0,
            "storeAdminNo": null,
            "storeNo": "300014",
            "transactionNo": "297553555705374195",
            "transactionStatus": "success",
            "transactionType": "refund",
            "vendor": "wechatpay"
        },
        {
            "amount": 0.01,
            "createTime": "2018-03-02 14:47:52",
            "currency": "USD",
            "exchangeRate": "6.361300",
            "merchantNo": "200043",
            "originalTransactionNo": null,
            "paymentTime": "2018-03-02 14:48:07",
            "refundAmount": 0.01,
            "storeAdminNo": null,
            "storeNo": "300014",
            "transactionNo": "297553555705268810",
            "transactionStatus": "success",
            "transactionType": "payment",
            "vendor": "wechatpay"
        }
    ],
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "size": 2,
    "transactions":[
        {
            "amount": -0.01,
            "createTime": "2018-03-02 14:49:38",
            "currency": "USD",
            "exchangeRate": "6.361300",
            "merchantNo": "200043",
            "originalTransactionNo": "297553555705268810",
            "paymentTime": "2018-03-02 14:49:38",
            "refundAmount": 0,
            "storeAdminNo": null,
            "storeNo": "300014",
            "transactionNo": "297553555705374195",
            "transactionStatus": "success",
            "transactionType": "refund",
            "vendor": "wechatpay"
        },
        {
            "amount": 0.01,
            "createTime": "2018-03-02 14:47:52",
            "currency": "USD",
            "exchangeRate": "6.361300",
            "merchantNo": "200043",
            "originalTransactionNo": null,
            "paymentTime": "2018-03-02 14:48:07",
            "refundAmount": 0.01,
            "storeAdminNo": null,
            "storeNo": "300014",
            "transactionNo": "297553555705268810",
            "transactionStatus": "success",
            "transactionType": "payment",
            "vendor": "wechatpay"
        }
    ],
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "size": 2,
    "transactions":[
        {
            "amount": -0.01,
            "createTime": "2018-03-02 14:49:38",
            "currency": "USD",
            "exchangeRate": "6.361300",
            "merchantNo": "200043",
            "originalTransactionNo": "297553555705268810",
            "paymentTime": "2018-03-02 14:49:38",
            "refundAmount": 0,
            "storeAdminNo": null,
            "storeNo": "300014",
            "transactionNo": "297553555705374195",
            "transactionStatus": "success",
            "transactionType": "refund",
            "vendor": "wechatpay"
        },
        {
            "amount": 0.01,
            "createTime": "2018-03-02 14:47:52",
            "currency": "USD",
            "exchangeRate": "6.361300",
            "merchantNo": "200043",
            "originalTransactionNo": null,
            "paymentTime": "2018-03-02 14:48:07",
            "refundAmount": 0.01,
            "storeAdminNo": null,
            "storeNo": "300014",
            "transactionNo": "297553555705268810",
            "transactionStatus": "success",
            "transactionType": "payment",
            "vendor": "wechatpay"
        }
    ],
    "ret_msg": "query success ",
    "ret_code": "000100"
}

Use trans-list() API to get all transaction details for time period.

HTTP Request

POST https://mapi.yuansfer.com/app-data-search/v2/trans-list

Request Parameters

Parameter Type Description
merchantNo

required

string The ID of the merchant.
storeNo

required

string The ID of the store.
storeAdminNo

optional

string The ID of the store admin.
startDate

required

string The start date of time period.
Format : “YYYYMMDD”.
endDate

required

string The end date of time period.
endDate cannot be 15 days greater than startDate.
Format : “YYYYMMDD”.
verifySign

required

string The parameter signature.

Response

Parameter Type Description
transactions array The array of the transaction object.
size integer The size of transactions.
ret_msg string The response return message.
ret_code string The response return code. For more details, see here.

settle-list()

Endpoint

POST https://mapi.yuansfer.com/app-data-search/v2/settle-list
POST https://mapi.yuansfer.com/app-data-search/v2/settle-list
POST https://mapi.yuansfer.com/app-data-search/v2/settle-list
POST https://mapi.yuansfer.com/app-data-search/v2/settle-list

Example Request

curl "https://mapi.yuansfer.com/app-data-search/v2/settle-list" \
-d "storeNo=300014" \
-d "merchantNo=200043" \
-d "startDate=startDate" \
-d "endDate=endDate" \
-d "verifySign=verifySign"
<?php
function settleList()
{
    $url = 'https://mapi.yuansfer.yunkeguan.com/app-data-search/v2/settle-list';
    $token = '59600f2a9ad644c6a9570233560cc94e';

    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'startDate' => '20171201',
        'endDate' => '20171210'
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
    echo "\n";

    $ch = curl_init($url);
    curl_setopt_array($ch, array(
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($params),
    ));

    $result = curl_exec($ch);
    curl_exec($ch);

    echo $result;
    echo "\n";
    return json_decode($result, true);
}

settleList();
?>
//settlement list
public static void settleList(String startDate, String endDate) {
    String url = DOMAIN_URL + SETTLE_LIST;
    Map<String, Object> params = new TreeMap<String, Object>();
    params.put("merchantNo", MERCHANT_NO);
    params.put("storeNo", STORE_NO);
    if (StringUtils.isNotEmpty(STORE_ADMIN_NO)) {
        params.put("storeAdminNo", STORE_ADMIN_NO);
    }

    params.put("startDate", startDate);
    params.put("endDate", endDate);
    String verifySign = verifySignHelper.getYuansferVerifySign(params, YUANSFER_TOKEN);
    params.put("verifySign", verifySign);
    String ret = HttpClientUtils.post(url, null, params);
    System.out.println("---settle list----");
    System.out.println(ret);
}

Example Response


{
    "settlements": [{
        "amount": 0.01,
        "currency": "USD",
        "exchangeRate": "6.354920",
        "fee": 0.00,
        "merchantNo": "200277",
        "netSettleAmount": 0.01,
        "paymentTime": "2018-03-07 23:43:06",
        "settleAmount": 0.01,
        "settleCurrency": "USD",
        "storeAdminNo": "3004890001",
        "storeNo": "300489",
        "transactionNo": "298068127611181075",
        "transactionType": "payment",
        "vendor","alipay"
    }, {
        "amount": 0.01,
        "currency": "USD",
        "exchangeRate": "6.345900",
        "fee": 0.00,
        "merchantNo": "200277",
        "netSettleAmount": 0.01,
        "paymentTime": "2018-03-07 15:32:55",
        "settleAmount": 0.01,
        "settleCurrency": "USD",
        "storeAdminNo": "3004890001",
        "storeNo": "300489",
        "transactionNo": "298068127581770149",
        "transactionType": "payment",
        "vendor","wechatpay"
    }],
    "size": 2,
    "ret_msg": "query success ",
    "ret_code": "000100"
}

{
    "settlements": [{
        "amount": 0.01,
        "currency": "USD",
        "exchangeRate": "6.354920",
        "fee": 0.00,
        "merchantNo": "200277",
        "netSettleAmount": 0.01,
        "paymentTime": "2018-03-07 23:43:06",
        "settleAmount": 0.01,
        "settleCurrency": "USD",
        "storeAdminNo": "3004890001",
        "storeNo": "300489",
        "transactionNo": "298068127611181075",
        "transactionType": "payment",
        "vendor","alipay"
    }, {
        "amount": 0.01,
        "currency": "USD",
        "exchangeRate": "6.345900",
        "fee": 0.00,
        "merchantNo": "200277",
        "netSettleAmount": 0.01,
        "paymentTime": "2018-03-07 15:32:55",
        "settleAmount": 0.01,
        "settleCurrency": "USD",
        "storeAdminNo": "3004890001",
        "storeNo": "300489",
        "transactionNo": "298068127581770149",
        "transactionType": "payment",
        "vendor","wechatpay"
    }],
    "size": 2,
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "settlements": [{
        "amount": 0.01,
        "currency": "USD",
        "exchangeRate": "6.354920",
        "fee": 0.00,
        "merchantNo": "200277",
        "netSettleAmount": 0.01,
        "paymentTime": "2018-03-07 23:43:06",
        "settleAmount": 0.01,
        "settleCurrency": "USD",
        "storeAdminNo": "3004890001",
        "storeNo": "300489",
        "transactionNo": "298068127611181075",
        "transactionType": "payment",
        "vendor","alipay"
    }, {
        "amount": 0.01,
        "currency": "USD",
        "exchangeRate": "6.345900",
        "fee": 0.00,
        "merchantNo": "200277",
        "netSettleAmount": 0.01,
        "paymentTime": "2018-03-07 15:32:55",
        "settleAmount": 0.01,
        "settleCurrency": "USD",
        "storeAdminNo": "3004890001",
        "storeNo": "300489",
        "transactionNo": "298068127581770149",
        "transactionType": "payment",
        "vendor","wechatpay"
    }],
    "size": 2,
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "settlements": [{
        "amount": 0.01,
        "currency": "USD",
        "exchangeRate": "6.354920",
        "fee": 0.00,
        "merchantNo": "200277",
        "netSettleAmount": 0.01,
        "paymentTime": "2018-03-07 23:43:06",
        "settleAmount": 0.01,
        "settleCurrency": "USD",
        "storeAdminNo": "3004890001",
        "storeNo": "300489",
        "transactionNo": "298068127611181075",
        "transactionType": "payment",
        "vendor","alipay"
    }, {
        "amount": 0.01,
        "currency": "USD",
        "exchangeRate": "6.345900",
        "fee": 0.00,
        "merchantNo": "200277",
        "netSettleAmount": 0.01,
        "paymentTime": "2018-03-07 15:32:55",
        "settleAmount": 0.01,
        "settleCurrency": "USD",
        "storeAdminNo": "3004890001",
        "storeNo": "300489",
        "transactionNo": "298068127581770149",
        "transactionType": "payment",
        "vendor","wechatpay"
    }],
    "size": 2,
    "ret_msg": "query success ",
    "ret_code": "000100"
}

Use the settle-list() API to get all settlements details for time period.

HTTP Request

POST https://mapi.yuansfer.com/app-data-search/v2/settle-list

Request Parameters

Parameter Type Description
merchantNo

required

string The ID of the merchant.
storeNo

required

string The ID of the store.
storeAdminNo

optional

string The ID of the store admin.
startDate

required

string The start date of time period.
Format : “YYYYMMDD”.
endDate

required

string The end date of time period.
endDate cannot be 15 days greater than startDate.
Format : “YYYYMMDD”.
verifySign

required

string The parameter signature.

Response

Parameter Type Description
settlements array The settlement object.
size integer The size of settlements.
ret_msg string The response return message.
ret_code string The response return code. For more details, see here.

settlement object

Parameter Type Description
merchantNo string The ID of the merchant.
storeNo string The ID of the store.
storeAdminNo string The ID of the store admin.
transactionNo string The ID of the transaction in the Yuansfer system.
transactionType string The transaction type.
The possible values are : “payment”, “refund”, “void”.
amount decimal The transaction amount.
currency string The three-character currency code that identifies the currency.
The possible values are: “USD”.
settleAmount decimal The settlement amount.
settleCurrency string The settlement currency code.
fee decimal The transaction fee.
netSettleAmount string The net settlement amount. (settleAmount - fee)
paymentTime string The date and time when the payment was processed.
Format : “YYYYMMDDHHMMSS”.
exchangeRate decimal The exchange rate between CNY and USD .
vendor string The payment method.
The possible values are: “alipay”, “wechatpay”.

withdrawal-list()

Endpoint

POST https://mapi.yuansfer.com/app-data-search/v2/withdrawal-list
POST https://mapi.yuansfer.com/app-data-search/v2/withdrawal-list
POST https://mapi.yuansfer.com/app-data-search/v2/withdrawal-list
POST https://mapi.yuansfer.com/app-data-search/v2/withdrawal-list

Example Request

curl "https://mapi.yuansfer.com/app-data-search/v2/withdrawal-list" \
-d "storeNo=300014" \
-d "merchantNo=200043" \
-d "startDate=startDate" \
-d "endDate=endDate" \
-d "verifySign=verifySign"
<?php
function withdrawalList()
{
    $url = 'https://mapi.yuansfer.yunkeguan.com/app-data-search/v2/withdrawal-list';
    $token = '59600f2a9ad644c6a9570233560cc94e';

    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'startDate' => '20171201',
        'endDate' => '20171210'
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
    echo "\n";

    $ch = curl_init($url);
    curl_setopt_array($ch, array(
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($params),
    ));

    $result = curl_exec($ch);
    curl_exec($ch);

    echo $result;
    echo "\n";
    return json_decode($result, true);
}

withdrawalList();
?>
//withdrawal list
public static void withdrawalList(String startDate, String endDate) {
    String url = DOMAIN_URL + WITHDRAWAL_LIST;
    Map<String, Object> params = new TreeMap<String, Object>();
    params.put("merchantNo", MERCHANT_NO);
    params.put("storeNo", STORE_NO);
    if (StringUtils.isNotEmpty(STORE_ADMIN_NO)) {
        params.put("storeAdminNo", STORE_ADMIN_NO);
    }

    params.put("startDate", startDate);
    params.put("endDate", endDate);
    String verifySign = verifySignHelper.getYuansferVerifySign(params, YUANSFER_TOKEN);
    params.put("verifySign", verifySign);
    String ret = HttpClientUtils.post(url, null, params);
    System.out.println("---withdrawal list----");
    System.out.println(ret);
}

Example Response


{
    "size": 1,
    "ret_msg": "query success ",
    "ret_code": "000100",
    "withdrawals": [{
        "actualAppropriation": 53.72,
        "bankSettlementFee": 0.3,
        "currency": "USD",
        "date": "20180307",
        "details": [{
            "paymentTime": "20180305230715",
            "transactionAmount": 0.01,
            "transactionCurrency": "USD",
            "transactionFee": 0.00,
            "transactionNo": "298068127436229571",
            "transactionType": "payment",
            "transactionWithdrawalAmount": 0.01,
            "vendor": "alipay"
        }, {
            "paymentTime": "20180306204828",
            "transactionAmount": 20.00,
            "transactionCurrency": "USD",
            "transactionFee": 0.36,
            "transactionNo": "298068127514235706",
            "transactionType": "payment",
            "transactionWithdrawalAmount": 19.64,
            "vendor": "alipay"
        }],
        "merchantNo": "200277",
        "salesAmount": 55.01,
        "status": "completed",
        "withdrawalAmount": 54.02,
        "yuansferProcessingFee": 0.99
    } 
    ]
}

{
    "size": 1,
    "ret_msg": "query success ",
    "ret_code": "000100",
    "withdrawals": [{
        "actualAppropriation": 53.72,
        "bankSettlementFee": 0.3,
        "currency": "USD",
        "date": "20180307",
        "details": [{
            "paymentTime": "20180305230715",
            "transactionAmount": 0.01,
            "transactionCurrency": "USD",
            "transactionFee": 0.00,
            "transactionNo": "298068127436229571",
            "transactionType": "payment",
            "transactionWithdrawalAmount": 0.01,
            "vendor": "alipay"
        }, {
            "paymentTime": "20180306204828",
            "transactionAmount": 20.00,
            "transactionCurrency": "USD",
            "transactionFee": 0.36,
            "transactionNo": "298068127514235706",
            "transactionType": "payment",
            "transactionWithdrawalAmount": 19.64,
            "vendor": "alipay"
        }],
        "merchantNo": "200277",
        "salesAmount": 55.01,
        "status": "completed",
        "withdrawalAmount": 54.02,
        "yuansferProcessingFee": 0.99
    } 
    ]
}
{
    "size": 1,
    "ret_msg": "query success ",
    "ret_code": "000100",
    "withdrawals": [{
        "actualAppropriation": 53.72,
        "bankSettlementFee": 0.3,
        "currency": "USD",
        "date": "20180307",
        "details": [{
            "paymentTime": "20180305230715",
            "transactionAmount": 0.01,
            "transactionCurrency": "USD",
            "transactionFee": 0.00,
            "transactionNo": "298068127436229571",
            "transactionType": "payment",
            "transactionWithdrawalAmount": 0.01,
            "vendor": "alipay"
        }, {
            "paymentTime": "20180306204828",
            "transactionAmount": 20.00,
            "transactionCurrency": "USD",
            "transactionFee": 0.36,
            "transactionNo": "298068127514235706",
            "transactionType": "payment",
            "transactionWithdrawalAmount": 19.64,
            "vendor": "alipay"
        }],
        "merchantNo": "200277",
        "salesAmount": 55.01,
        "status": "completed",
        "withdrawalAmount": 54.02,
        "yuansferProcessingFee": 0.99
    } 
    ]
}
{
    "size": 1,
    "ret_msg": "query success ",
    "ret_code": "000100",
    "withdrawals": [{
        "actualAppropriation": 53.72,
        "bankSettlementFee": 0.3,
        "currency": "USD",
        "date": "20180307",
        "details": [{
            "paymentTime": "20180305230715",
            "transactionAmount": 0.01,
            "transactionCurrency": "USD",
            "transactionFee": 0.00,
            "transactionNo": "298068127436229571",
            "transactionType": "payment",
            "transactionWithdrawalAmount": 0.01,
            "vendor": "alipay"
        }, {
            "paymentTime": "20180306204828",
            "transactionAmount": 20.00,
            "transactionCurrency": "USD",
            "transactionFee": 0.36,
            "transactionNo": "298068127514235706",
            "transactionType": "payment",
            "transactionWithdrawalAmount": 19.64,
            "vendor": "alipay"
        }],
        "merchantNo": "200277",
        "salesAmount": 55.01,
        "status": "completed",
        "withdrawalAmount": 54.02,
        "yuansferProcessingFee": 0.99
    } 
    ]
}

Use the withdrawal-list() API to get all withdrawal details for time period.
Note: All date format is YYYYMMDD. endDate cannot be 15 days greater than startDate.

HTTP Request

POST https://mapi.yuansfer.com/app-data-search/v2/withdrawal-list

Request Parameters

Parameter Type Description
merchantNo

required

string The ID of the merchant.
storeNo

required

string The ID of the store.
storeAdminNo

optional

string The ID of the store admin.
startDate

required

string The start date of time period.
Format : “YYYYMMDD”.
endDate

required

string The end date of time period.
Format : “YYYYMMDD”.
verifySign

required

string The parameter signature.

Response

Parameter Type Description
withdrawals array The array of the withdrawal object.
size integer The size of withdrawals.
ret_msg string The response return message.
ret_code string The response return code. For more details, see here.

withdrawal object

Parameter Type Description
merchantNo string The ID of the merchant.
salesAmount string The total transaction amount.
yuansferProcessingFee string The Yuansfer processing fee.
withdrawalAmount string The withdrawal amount.
bankSettlementFee string The bank settlement fee.
actualAppropriation string The actual appropriation.
status string The status of the withdrawal.
currency string The three-character currency code that identifies the currency.
The possible values are: “USD”.
date string The withdrawal date.
details array The array of the detail object.

detail object

Parameter Type Description
transactionNo The ID of the transaction.
transactionType The transaction type.
The possible values are : “payment”, “refund”, “void”.
transactionAmount The transaction amount.
transactionFee The transaction processing fee.
transactionWithdrawalAmount The transaction withdrawal amount.
transactionCurrency The transaction currency code.
The possible values are: “USD”.
paymentTime The date and time when the payment was processed.
Format : “YYYYMMDDHHMMSS”.
vendor The payment method.
The possible values are: “alipay”, “wechatpay”.

data-status()

Endpoint

curl "https://mapi.yuansfer.com/app-data-search/v2/data-status" \
-d "storeNo=300014" \
-d "merchantNo=200043" \
-d "paymentDate=20180520" \
-d "verifySign=verifySign"
<?php
function dataStatus()
{
    $url = 'https://mapi.yuansfer.yunkeguan.com/app-data-search/v2/data-status';
    $token = '59600f2a9ad644c6a9570233560cc94e';

    $params = [
        'merchantNo' => '200043',
        'storeNo' => '300014',
        'paymentDate' => '20180619'
    ];

    ksort($params, SORT_STRING);
    $str = '';
    foreach ($params as $k => $v) {
        $str .= $k . '=' . $v . '&';
    }
    $params['verifySign'] = md5($str . md5($token));

    echo 'verifySign:', $params['verifySign'];
    echo "\n";

    $ch = curl_init($url);
    curl_setopt_array($ch, array(
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER => false,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($params),
    ));

    $result = curl_exec($ch);
    curl_exec($ch);

    echo $result;
    echo "\n";
    return json_decode($result, true);
}

dataStatus();
?>
//data status
public static void dataStatus(String paymentDate) {
    String url = DOMAIN_URL + DATA_STATUS;
    Map<String, Object> params = new TreeMap<String, Object>();
    params.put("merchantNo", MERCHANT_NO);
    params.put("storeNo", STORE_NO);
    if (StringUtils.isNotEmpty(STORE_ADMIN_NO)) {
        params.put("storeAdminNo", STORE_ADMIN_NO);
    }

    params.put("paymentDate", paymentDate);
    String verifySign = verifySignHelper.getYuansferVerifySign(params, YUANSFER_TOKEN);
    params.put("verifySign", verifySign);
    String ret = HttpClientUtils.post(url, null, params);
    System.out.println("---data status----");
    System.out.println(ret);
}

Example Response


{
    "result": {
        "merchantNo": "200043",
        "message": "NO_TRANSACTION",
        "paymentDate": "20180520",
        "status": "00",
        "storeNo": "300014"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}

{
    "result": {
        "merchantNo": "200043",
        "message": "NO_TRANSACTION",
        "paymentDate": "20180520",
        "status": "00",
        "storeNo": "300014"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "result": {
        "merchantNo": "200043",
        "message": "NO_TRANSACTION",
        "paymentDate": "20180520",
        "status": "00",
        "storeNo": "300014"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}
{
    "result": {
        "merchantNo": "200043",
        "message": "NO_TRANSACTION",
        "paymentDate": "20180520",
        "status": "00",
        "storeNo": "300014"
    },
    "ret_msg": "query success ",
    "ret_code": "000100"
}

Use the data-status() API to get settlement status on certain date.

HTTP Request

POST https://mapi.yuansfer.com/app-data-search/v2/data-status

Request Parameters

Parameter Type Description
merchantNo

required

string The ID of the merchant.
storeNo

required

string The ID of the store.
storeAdminNo

optional

string The ID of the store admin.
paymentDate

required

string The date when you want to get settlement status.
Format : “YYYYMMDD”.
verifySign

required

string The parameter signature.

Response

Parameter Type Description
result object The result object.
ret_msg string The response return message.
ret_code string The response return code. For more details, see here.

result object

Parameter Type Description
merchantNo string The ID of the merchant.
storeNo string The ID of the store.
paymentDate string The payment date
status string The status code of settlement, see the table below.
message string The description, see the table below.

Mappings of status and message

status message
“00” “NO_TRANSACTION”
“10” “NO_SETTLED”
“11” “PARTLY_SETTLED”
“12” “FULLY_SETTLED”

Common Object Definition

transaction object

Parameter Type Description
transactionNo string The ID of the transaction in the Yuansfer system.
originalTransactionNo string The ID of the original transaction in the Yuansfer system.
merchantNo string The ID of the merchant.
storeNo string The ID of the store.
storeAdminNo string The ID of the store admin.
amount decimal The transaction amount.
refundAmount decimal The refund amount.
voidAmount decimal The void or cancel amount.
transactionType string The transaction type.
The possible values are : “payment”, “refund”, “void”.
transactionStatus string The status of the transaction.
currency string The three-character currency code that identifies the currency.
The possible values are: “USD”.
createTime string The date and time when the transaction was created.
Format : “yyyy-MM-dd HH:mm:ss”.
paymentTime string The date and time when the payment was processed.
Format : “yyyy-MM-dd HH:mm:ss”.
exchangeRate decimal The exchange rate between CNY and USD .
vendor string The payment method.
The possible values are: “alipay”, “wechatpay”.

Notes

Response return code

The Yuansfer APIs return the following codes in ret_code parameter :

Return Code Meaning
000000 System Error
000010 API Version Error
000020 Parameter Null Error
000021 Parameter No Related Infomation
000022 Parameters Not Match
000023 Parameter Value Error
000030 No Rights
000040 Transaction Status Error
000080 Supplier System’s Error
000100 Success

Note : The return code “000100” represents success while the return code “000000” represents failure.

Transaction status

Status Meaning
init A new transaction is created, but not sent to the payment channel.
dealing Dealing with the payment.
success The transaction has been successfully processed.
failed The transaction has been failed.
pending Waiting for the payment confirmation.
closed The payment channel was setup, but the customer didn’t continue to complete payment action and automatically closed after a certain period.

Instant Payment Notification

The merchants create an IPN listener page on their website and then specify the URL of the listener page in the request body. Yuansfer API then sends notifications of all transaction-related events to that url. When customers pay for goods or services, API sends a secure FORM POST containing payment information(IPN messages) to the URL. The IPN listener detects and processes IPN messages using the merchant backend processes. The IPN listener page contains a custom script or program that waits for the messages, validates success status, and then passes them to various backend applications for processing. IPN is not synchronized with actions on your website. Internet connectivity is not always 100% reliable and IPN messages can be lost or delayed. The IPN service automatically resends messages until the listener acknowledges them. The service resends messages for up to 8 times in 2 hours.

Callback Parameters

When the merchant’s system receives callback from the Yuansfer system, it is recommended that the merchant’s system validates the parameters for the callback information by using the verifySign, so as to avoid the data being tampered.

Yuansfer returns follow parameters in callbacks(including IPN).

Parameter Type Description
yuansferId object The ID of transaction in the Yuansfer system.
status enum The status of transaction.
amount string The transaction amount.
time string The date and time when the transaction was created.
Format : “YYMMDDHHMMSS”.
reference string The ID of transaction in the merchant’s system.
note string The payment note.
verifySign string The parameter signature.

Yuansfer Timezone

The Yuansfer timezone is UTC +8.

Demo of Online Payments API:

Demo of In-Store Payments API:

Sandbox Environment

To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no “switch” for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test mode credentials never hit the banking networks and incur no cost.

Online Payments API

Parameter Value
merchantNo 200043
storeNo 300014
yuansferToken 5cbfb079f15b150122261c8537086d77a
Parameter Value
Card Number 6226388000000095
CVV 248
EXP 12/2019
Phone 18100000000
Verification Code 111111
Parameter Value
Account douyufua@alitest.com
Captcha Code 8888
Login Password 111111
Payment Password on Cashier Page 111111

In-Store Payments API

Parameter Value
merchantNo 200043
storeNo 300014
storeAdminNo 3000140001
yuansferToken 59600f2a9ad644c6a9570233560cc94e

Pay Treasure Sandbox Apk

Download APK from here