# API 2.0 (Current)

# Overview

TripLink APIs are based on HTTPS protocol, the user should make POST requests following the instructions, see APIs.

The request body and response body of all APIs are in JSON format and UTF-8 encoded. The user should include Content-Type: application/json in request header.

The requests and responses of all APIs contain several public parameters which are located in request header and response header, see Public Parameters.

The requests and responses of all APIs are encrypted and signed, see Encryption, Signature.

Environment	URL
TEST	`https://compass.uat.ctripqa.com/compass/api`
PROD (domestic)	`https://compass.ctrip.com/compass/api`
PROD (overseas)	`https://compass.triplinkintl.com/compass/api`

WARNING

PROD (domestic) will stop service on 2023/2/20, please change to PROD (overseas) as soon as possible. Please access the service by URL directly and do not use IP whitelist.

# Public Parameters

# Request header

Name	Required	Description	Comment	Sample
`customerId`	`Y`	customer ID	Pre-configured.	`ASR3F1B4Z5`
`service`	`Y`	API name	See APIs.	`createCard`
`version`	`Y`	API version	Current version `2.0`.	`2.0`
`requestId`	`Y`	request ID	Must be unique for each request, `UUID` is recommended.	`472f37e3-a803-47ed-b9b6-32632895b466`
`timestamp`	`Y`	request timestamp	UNIX timestamp (milliseconds).	`1642747436113`
`sign`	`Y`	request signature	See Signature.	`_Ue0BiWsCOxbYD39Ldd` (partial data)

# Response header

Name	Description	Comment	Sample
`customerId`	customer ID	Same as Request header.	`ASR3F1B4Z5`
`service`	API name	Same as Request header.	`createCard`
`version`	API version	Same as Request header.	`2.0`
`requestId`	request ID	Same as Request header.	`472f37e3-a803-47ed-b9b6-32632895b466`
`timestamp`	response timestamp	UNIX timestamp (milliseconds).	`1642747437393`
`code`	response code	Enumerated type, `3` digits, see response code drop-down list.	`200` (code other than `200` means API call failed)
`message`	response code details	See response code drop-down list.	`succeed`
`sign`	response signature	See Signature.	`WO8waUZ30bYlKp-_s9m` (partial data)

response code

code	message	Comment
`200`	succeed	Succeed.
`400`	payload decrypt failed	Decrypt payload failed.
`403`	the ip is not whitelisted	Request IP not in whitelist
`405`	unsupported method	Request method not supported. (only support `POST`)
`406`	too many requests	Too many requests.
`407`	verify sign failed	Verify sign failed.
`417`	the parameter is null or invalid	Required request header is empty.
`500`	(not fixed)	System error.

# APIs

Name	Method	Request service header
Create Card	`POST`	`createCard`
Update Card	`POST`	`updateCard`
Recharge Card	`POST`	`rechargeCard`
Withdraw Card	`POST`	`withdrawCard`
Suspend Card	`POST`	`suspendCard`
Unsuspend Card	`POST`	`unSuspendCard`
Close Card	`POST`	`closeCard`
Query Card	`POST`	`queryCardDetail`
Query Account Credit	`POST`	`queryCustomerCredit`
Query Authorization Transactions	`POST`	`queryAuthTransactionByPage`
Query Settlement Transactions	`POST`	`settlementTransactionQuery`
Initiate Account Withdrawal	`POST`	`payoutCreate`
Query Account Withdrawal	`POST`	`payoutQuery`
FX Quote	`POST`	`fxQuote`
FX Create Order	`POST`	`fxCreate`
FX Query Order	`POST`	`fxQuery`

# Encryption

To ensure data security, TripLink will encrypt every requests and responses.

The user and TripLink should use the symmetric encryption algorithm AES/ECB/PKCS5Padding to encrypt and decrypt both Request body and Response body, the result is encoded by Base64.

The user should provide 128 bits AES key (Base64 encoded) to TripLink in advance, see Preparation.

# Request body

For the meaning of each properties in original request body, please refer to each API description below.

User: Encrypts the original request body with AES key and encodes with Base64. Makes the result as the value of payload property in actual request body. Sends out the actual request body.

TripLink: Decodes the payload property of received actual request body with Base64 and decrypts with AES key. The result is the original request body.

# Response body

For the meaning of each properties in original response body, please refer to each API description below.

TripLink: Encrypts the original response body with AES key and encodes with Base64. Makes the result as the value of payload property in actual response body. Sends out the actual response body.

User: Decodes the payload property of received actual response body with Base64 and decrypts with AES key. The result is the original response body.

Java Utilities example

import javax.crypto.Cipher;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

import static java.nio.charset.StandardCharsets.UTF_8;

public class AesUtils {

    private static final Base64.Encoder ENCODER = Base64.getEncoder();
    private static final Base64.Decoder DECODER = Base64.getDecoder();

    /**
     * replace your aesKey
     */
    private static String aesKey = "amJPkH98aHGXskiH91r0dw==";


    /**
     * example for get encrypted payload
     */
    public static void main(String[] args) throws Exception {
        // replace your request payload
        String payload = "{\"requestId\":\"7ca6f405-acb4-4dd1-b35e-2b741b595e98\",\"customerId\":\"CSR9372F4E8ADG85\",\"cardLogId\":\"85a934fafb02cd5f27h53d2764bd884075c123fc87a04a3ddf919c710f281234\"}";

        // encrypt payload
        String encryptPayload = aesEncrypt(newAesKey(aesKey), payload);

        // print result
        System.out.println(encryptPayload);
    }

    public static String aesEncrypt(SecretKey key, String plaintext) throws Exception {
        Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5Padding");
        cipher.init(Cipher.ENCRYPT_MODE, key);
        byte[] cipherBytes = cipher.doFinal(plaintext.getBytes(UTF_8));
        return new String(ENCODER.encode(cipherBytes), UTF_8);
    }

    public static String aesDecrypt(SecretKey key, String ciphertext) throws Exception {
        Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5Padding");
        cipher.init(Cipher.DECRYPT_MODE, key);
        byte[] cipherBytes = DECODER.decode(ciphertext.getBytes(UTF_8));
        return new String(cipher.doFinal(cipherBytes), UTF_8);
    }

    public static SecretKey newAesKey(String keyStr) {
        return new SecretKeySpec(DECODER.decode(keyStr.getBytes(UTF_8)), "AES");
    }

    public static String toAesKeyStr(SecretKey key) {
        return new String(ENCODER.encode(key.getEncoded()), UTF_8);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

C# Utilities example

using System;
using System.Security.Cryptography;
using System.Text;

public class AesUtils {
    private static readonly Base64Encoder ENCODER = new Base64Encoder();
    private static readonly Base64Decoder DECODER = new Base64Decoder();

    /**
     * replace your aesKey
     */
    private static string aesKey = "amJPkH98aHGXskiH91r0dw==";

    /**
     * example for get encrypted payload
     */
    public static void Main(string[] args) {
        // replace your request payload
        string payload = "{\"requestId\":\"7ca6f405-acb4-4dd1-b35e-2b741b595e98\",\"customerId\":\"CSR9372F4E8ADG85\",\"cardLogId\":\"85a934fafb02cd5f27h53d2764bd884075c123fc87a04a3ddf919c710f281234\"}";

        // encrypt payload
        string encryptPayload = AesEncrypt(NewAesKey(aesKey), payload);

        // print result
        Console.WriteLine(encryptPayload);
    }

    public static string AesEncrypt(byte[] key, string plaintext) {
        using(Aes aes = Aes.Create()) {
            aes.Key = key;
            aes.Mode = CipherMode.ECB;
            aes.Padding = PaddingMode.PKCS7;

            ICryptoTransform encryptor = aes.CreateEncryptor(aes.Key, aes.IV);
            byte[] plainBytes = Encoding.UTF8.GetBytes(plaintext);
            byte[] cipherBytes = encryptor.TransformFinalBlock(plainBytes, 0, plainBytes.Length);
            return ENCODER.Encode(cipherBytes);
        }
    }

    public static string AesDecrypt(byte[] key, string ciphertext) {
        using(Aes aes = Aes.Create()) {
            aes.Key = key;
            aes.Mode = CipherMode.ECB;
            aes.Padding = PaddingMode.PKCS7;

            ICryptoTransform decryptor = aes.CreateDecryptor(aes.Key, aes.IV);
            byte[] cipherBytes = DECODER.Decode(ciphertext);
            byte[] plainBytes = decryptor.TransformFinalBlock(cipherBytes, 0, cipherBytes.Length);
            return Encoding.UTF8.GetString(plainBytes);
        }
    }

    public static byte[] NewAesKey(string keyStr) {
        return DECODER.Decode(keyStr);
    }

    public static string ToAesKeyStr(byte[] key) {
        return ENCODER.Encode(key);
    }
}

public class Base64Encoder {
    public string Encode(byte[] data) {
        return Convert.ToBase64String(data);
    }
}

public class Base64Decoder {
    public byte[] Decode(string data) {
        return Convert.FromBase64String(data);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

PHP Utilities example

<?php declare(strict_types=1);

class AesUtils {

    public static function aesEncrypt(string $keyStr, string $plaintext): string {
        return base64_encode(openssl_encrypt($plaintext, 'AES-128-ECB', base64_decode($keyStr), OPENSSL_RAW_DATA));
    }

    public static function aesDecrypt(string $keyStr, string $ciphertext): string {
        return openssl_decrypt(base64_decode($ciphertext), 'AES-128-ECB', base64_decode($keyStr), OPENSSL_RAW_DATA);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12

# Signature

To ensure safe API calls, TripLink will authenticate each request and response using signature.

TripLink uses the signature algorithm SHA256withRSA to sign both Request string to be signed and Response string to be signed. The signature result is encoded by Base64, located in sign property of request header and response header.

The user will be assigned 2048 bits RSA public key T (Base64 encoded). The user should also provide 2048 bits RSA public key U (Base64 encoded) to TripLink in advance, see Preparation.

The entire request and response process involves 2 RSA keys: The public key T and private key T which belongs to TripLink, the public key U and private key U which belongs to user. The public keys are used for verifying the signature and the private keys are used for generating the signature.

# Request string to be signed

All the properties are concatenated by | symbol in the following order.

customerId|service|version|requestId|timestamp|payload

User: Generates the signature on request string to be signed with private key U and encodes with Base64. Makes the result as the value of sign property in request header.

TripLink: Decodes the sign property of received request header with Base64 and verifies with public key U.

# Response string to be signed

All the properties are concatenated by | symbol in the following order.

customerId|service|version|requestId|timestamp|code|message|payload

TripLink: Generates the signature on response string to be signed with private key T and encodes with Base64. Makes the result as the value of sign property in response header.

User: Decodes the sign property of received response header with Base64 and verifies with public key T.

Java Utilities example

import org.apache.commons.lang3.StringUtils;
import java.security.KeyFactory;
import java.security.PrivateKey;
import java.security.PublicKey;
import java.security.Signature;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;

import static java.nio.charset.StandardCharsets.UTF_8;

public class RsaUtils {

    private static final Base64.Encoder ENCODER = Base64.getEncoder();
    private static final Base64.Decoder DECODER = Base64.getDecoder();

    /**
     * replace your private rsaKey
     */
    private static String rsaPrivateKey = "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCoyUMgQDCtymWE" +
            "83IGbrbYgrIWK++QzQBsUIypci1hPNEzSuc9X34ICpsFbtyp9RSYX4Es+nNrKE2I" +
            "SLdtTsQescPQHSwl6OW7fzk/jmaZpCFXznU+vgrnvhDMIGTvQTN2M3hdfgMGvF3B" +
            "DsDvep8ZQ84YWIjJdLGvlXvJ/OjyGQDOKoclMfi3gVkI0izlZUDdBGgHUpGAlMpK" +
            "A8yp28GCURioMrsr7CtSjmVP0lPsPrP5sI6Vk0qAlxt6GGVTDghZI3flixuiEpFL" +
            "vOyLJjw7TkTCUvFcWsLn15F45TA2AGUzzWHcMdwiUKJEQBy0FlFoFET7GjnQkimC" +
            "UU0QZJQ7AgMBAAECggEAAOXFFhxRRfNQE+NphVA8Z61WPhjwtq/oYysQfGwvgpdc" +
            "s22gCisCVA+eYGqFAOBdQiwr1y3jxDucIe/lDc8/6rveQzKMhA0Xf6Y/Cy/6KrH9" +
            "PWbLJ9DB5RaVJ0i60KzjlarTZoffgz8oLnkiHIPl6a/7HhUGcS/OLBVa6amPIY5v" +
            "QmY14gVHh8K2FdZLBL3F2i7djAwBIlqT2EgQdxKoq0RMsvKmqlLePLfBytAu6RxT" +
            "hC0vqANPJoPZVz8rV8ixsWINmJ2jx9A+xaGTHYAC6MdcM7sButDhJccIX2H6Zyem" +
            "bl0KhfGmrerKZTmeqI/JjsJyaGsXV+h4qAyDpXwcJQKBgQDloiinUDrZZUMnU9af" +
            "DacDZ4AWluefmnTvpO3JRKS8wYGYSSE0Aee4CnHTyNv7FFsGorQJgMFGHFNvHFQ1" +
            "pk1+tuOgqycVPec6EzLgBPJC/1dMRRPk9JDXMpIM8dYkQ93phvfLqSKOCagGHOdR" +
            "PMpk1LBhMUVmvHijFzX2+wMExwKBgQC8Ko9wvbT5GAiu6rIz1PVDvD5dQbv7jXPR" +
            "Mu0QJlFJH5gQ5rVBZdxfBIjpQe4aMDtdot3KWkNjpgJm4OGA4T9E5OpHIIHZ+9cr" +
            "PLEq9Evp9llrBEFICVC+DI3DZWC9+6Ussrs5p1y2Wyjuai6kZnDuvroUXpV1a6aE" +
            "MydQNSWY7QKBgQC4ppOgLsCTrXy5dA4h6d2BvElgYMoyKgab6XiYHo2FhujJ5ww/" +
            "AMUu1Z9AWMSjenPTuyOgfJtt4DsrHpGMboTkPvZ9bQNJbnSv215Oi0uvmhm9p9Je" +
            "ilap5O1SYWj70mLwdOpvJzs1Egi9maJcTdDGEc0e6nrPKQCszG5FgwSjYwKBgG8f" +
            "N0yeS/Ta863Q3mJrvlg9IBtUyZ4aAC6oQ4XJCzIC3XwFsz8m14iple0iyWlf2H9I" +
            "wnBQ9AEyNbLp1WKWIxYdlhlhIi5IYt6e3gX+9aH6oP3pKmBPWAaURVgCU6p+pSIL" +
            "fzPiGYd7uGVsAZWHBeSIcD29SchpRZJG302nxUdVAoGAQYSVYM7TMeTuQgDAXUD5" +
            "g4ulLpZKiq910M7DufQ4tgrZOwT44I1ihDXh0s2BKg8+PLJPT1ldgH/Dtglwosv1" +
            "peD0Lep3zSwrTXpyMstdCW16bl96FOKGP8H8c2zXXG7e39E6D9rPSKDt5TtGVScS" +
            "PYsWAsMHzfsX2F4aUJNUuN0=";


    /**
     * example for get encrypted sign
     */
    public static void main(String[] args) throws Exception {
        // request head params
        String customerId = "CSR9372F4E8ADG85";
        String service = "queryCard";
        String version = "2.0";
        String requestId = "7ca6f405-acb4-4dd1-b35e-2b741b595e98";
        long timestamp = 1741846955993L;

        // payload after aesKey encryption, refer to AesUtils
        String payload = "A/R7OP/qWzmIGDwfs0I3c8XmOfwRshvO1NaHDUIaq0yZAnqptgt7WiEXXF6Cg6LgbQ8+p5M6eikXuBLeTe+zxmkjF1Mc/nrnjyVwqwd7/WsWhYJ4YCEGAjjbGO8hftwZsVEufCRwIrL+wxbp8d7cD3AwVxuHr1+mkr2Rb+ox9j4qB5Z3dkUUpNnaMdIxqtMkXZjydoe9A8sAgYEmK28TTkUf/pYGWv7Wj0KtBkX4rMU=";

        // generate sign
        String sign = buildRequestSignContent(customerId, service, version, requestId, timestamp, payload);

        // encrypt sign
        String encryptSign = rsaSign(newRsaPrivateKey(rsaPrivateKey), sign);

        // print result
        System.out.println(encryptSign);
    }

    public static String rsaSign(PrivateKey privateKey, String content) throws Exception {
        Signature signer = Signature.getInstance("SHA256withRSA");
        signer.initSign(privateKey);
        signer.update(content.getBytes(UTF_8));
        return new String(ENCODER.encode(signer.sign()), UTF_8);
    }

    public static boolean rsaVerify(PublicKey publicKey, String content, String signature) throws Exception {
        Signature signer = Signature.getInstance("SHA256withRSA");
        signer.initVerify(publicKey);
        signer.update(content.getBytes(UTF_8));
        return signer.verify(DECODER.decode(signature.getBytes(UTF_8)));
    }

    public static PrivateKey newRsaPrivateKey(String privateKeyStr) throws Exception {
        byte[] bytes = DECODER.decode(privateKeyStr.getBytes(UTF_8));
        KeyFactory keyFactory = KeyFactory.getInstance("RSA");
        return keyFactory.generatePrivate(new PKCS8EncodedKeySpec(bytes));
    }

    public static PublicKey newRsaPublicKey(String publicKeyStr) throws Exception {
        byte[] bytes = DECODER.decode(publicKeyStr.getBytes(UTF_8));
        KeyFactory keyFactory = KeyFactory.getInstance("RSA");
        return keyFactory.generatePublic(new X509EncodedKeySpec(bytes));
    }

    public static String toRsaPrivateKeyStr(PrivateKey privateKey) {
        return new String(ENCODER.encode(privateKey.getEncoded()), UTF_8);
    }

    public static String toRsaPublicKeyStr(PublicKey publicKey) {
        return new String(ENCODER.encode(publicKey.getEncoded()), UTF_8);
    }

    private static String buildRequestSignContent(String customerId, String service, String version, String requestNo, long timestamp, String payload) {
        StringBuilder builder = new StringBuilder();
        if (StringUtils.isNotBlank(customerId)) {
            builder.append(customerId).append("|");
        }
        if (StringUtils.isNotBlank(service)) {
            builder.append(service).append("|");
        }
        if (StringUtils.isNotBlank(version)) {
            builder.append(version).append("|");
        }
        if (StringUtils.isNotBlank(requestNo)) {
            builder.append(requestNo).append("|");
        }
        if (0 != timestamp) {
            builder.append(timestamp).append("|");
        }
        if (StringUtils.isNotBlank(payload)) {
            builder.append(payload);
        }
        return builder.toString();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

C# Utilities example

using System;
using System.Security.Cryptography;
using System.Text;

public class RsaUtils {
    private static readonly Base64Encoder ENCODER = new Base64Encoder();
    private static readonly Base64Decoder DECODER = new Base64Decoder();

    /**
     * replace your private rsaKey
     */
    private static string rsaPrivateKey = "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCoyUMgQDCtymWE" +
        "83IGbrbYgrIWK++QzQBsUIypci1hPNEzSuc9X34ICpsFbtyp9RSYX4Es+nNrKE2I" +
        "SLdtTsQescPQHSwl6OW7fzk/jmaZpCFXznU+vgrnvhDMIGTvQTN2M3hdfgMGvF3B" +
        "DsDvep8ZQ84YWIjJdLGvlXvJ/OjyGQDOKoclMfi3gVkI0izlZUDdBGgHUpGAlMpK" +
        "A8yp28GCURioMrsr7CtSjmVP0lPsPrP5sI6Vk0qAlxt6GGVTDghZI3flixuiEpFL" +
        "vOyLJjw7TkTCUvFcWsLn15F45TA2AGUzzWHcMdwiUKJEQBy0FlFoFET7GjnQkimC" +
        "UU0QZJQ7AgMBAAECggEAAOXFFhxRRfNQE+NphVA8Z61WPhjwtq/oYysQfGwvgpdc" +
        "s22gCisCVA+eYGqFAOBdQiwr1y3jxDucIe/lDc8/6rveQzKMhA0Xf6Y/Cy/6KrH9" +
        "PWbLJ9DB5RaVJ0i60KzjlarTZoffgz8oLnkiHIPl6a/7HhUGcS/OLBVa6amPIY5v" +
        "QmY14gVHh8K2FdZLBL3F2i7djAwBIlqT2EgQdxKoq0RMsvKmqlLePLfBytAu6RxT" +
        "hC0vqANPJoPZVz8rV8ixsWINmJ2jx9A+xaGTHYAC6MdcM7sButDhJccIX2H6Zyem" +
        "bl0KhfGmrerKZTmeqI/JjsJyaGsXV+h4qAyDpXwcJQKBgQDloiinUDrZZUMnU9af" +
        "DacDZ4AWluefmnTvpO3JRKS8wYGYSSE0Aee4CnHTyNv7FFsGorQJgMFGHFNvHFQ1" +
        "pk1+tuOgqycVPec6EzLgBPJC/1dMRRPk9JDXMpIM8dYkQ93phvfLqSKOCagGHOdR" +
        "PMpk1LBhMUVmvHijFzX2+wMExwKBgQC8Ko9wvbT5GAiu6rIz1PVDvD5dQbv7jXPR" +
        "Mu0QJlFJH5gQ5rVBZdxfBIjpQe4aMDtdot3KWkNjpgJm4OGA4T9E5OpHIIHZ+9cr" +
        "PLEq9Evp9llrBEFICVC+DI3DZWC9+6Ussrs5p1y2Wyjuai6kZnDuvroUXpV1a6aE" +
        "MydQNSWY7QKBgQC4ppOgLsCTrXy5dA4h6d2BvElgYMoyKgab6XiYHo2FhujJ5ww/" +
        "AMUu1Z9AWMSjenPTuyOgfJtt4DsrHpGMboTkPvZ9bQNJbnSv215Oi0uvmhm9p9Je" +
        "ilap5O1SYWj70mLwdOpvJzs1Egi9maJcTdDGEc0e6nrPKQCszG5FgwSjYwKBgG8f" +
        "N0yeS/Ta863Q3mJrvlg9IBtUyZ4aAC6oQ4XJCzIC3XwFsz8m14iple0iyWlf2H9I" +
        "wnBQ9AEyNbLp1WKWIxYdlhlhIi5IYt6e3gX+9aH6oP3pKmBPWAaURVgCU6p+pSIL" +
        "fzPiGYd7uGVsAZWHBeSIcD29SchpRZJG302nxUdVAoGAQYSVYM7TMeTuQgDAXUD5" +
        "g4ulLpZKiq910M7DufQ4tgrZOwT44I1ihDXh0s2BKg8+PLJPT1ldgH/Dtglwosv1" +
        "peD0Lep3zSwrTXpyMstdCW16bl96FOKGP8H8c2zXXG7e39E6D9rPSKDt5TtGVScS" +
        "PYsWAsMHzfsX2F4aUJNUuN0=";

    /**
     * example for get encrypted sign
     */
    public static void Main(string[] args) {
        // request head params
        string customerId = "CSR9372F4E8ADG85";
        string service = "queryCard";
        string version = "2.0";
        string requestId = "7ca6f405-acb4-4dd1-b35e-2b741b595e98";
        long timestamp = 1741846955993L;

        // payload after aesKey encryption, refer to AesUtils
        string payload = "A/R7OP/qWzmIGDwfs0I3c8XmOfwRshvO1NaHDUIaq0yZAnqptgt7WiEXXF6Cg6LgbQ8+p5M6eikXuBLeTe+zxmkjF1Mc/nrnjyVwqwd7/WsWhYJ4YCEGAjjbGO8hftwZsVEufCRwIrL+wxbp8d7cD3AwVxuHr1+mkr2Rb+ox9j4qB5Z3dkUUpNnaMdIxqtMkXZjydoe9A8sAgYEmK28TTkUf/pYGWv7Wj0KtBkX4rMU=";

        // generate sign
        string sign = BuildRequestSignContent(customerId, service, version, requestId, timestamp, payload);

        // encrypt sign
        string encryptSign = RsaSign(NewRsaPrivateKey(rsaPrivateKey), sign);

        // print result
        Console.WriteLine(encryptSign);
    }

    public static string RsaSign(RSA privateKey, string content) {
        byte[] dataBytes = Encoding.UTF8.GetBytes(content);
        byte[] signatureBytes = privateKey.SignData(dataBytes, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);
        return ENCODER.Encode(signatureBytes);
    }

    public static bool RsaVerify(RSA publicKey, string content, string signature) {
        byte[] dataBytes = Encoding.UTF8.GetBytes(content);
        byte[] signatureBytes = DECODER.Decode(signature);
        return publicKey.VerifyData(dataBytes, signatureBytes, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);
    }

    public static RSA NewRsaPrivateKey(string privateKeyStr) {
        byte[] privateKeyBytes = DECODER.Decode(privateKeyStr);
        RSA rsa = RSA.Create();
        rsa.ImportPkcs8PrivateKey(privateKeyBytes, out _);
        return rsa;
    }

    public static RSA NewRsaPublicKey(string publicKeyStr) {
        byte[] publicKeyBytes = DECODER.Decode(publicKeyStr);
        RSA rsa = RSA.Create();
        rsa.ImportSubjectPublicKeyInfo(publicKeyBytes, out _);
        return rsa;
    }

    public static string ToRsaPrivateKeyStr(RSA privateKey) {
        byte[] privateKeyBytes = privateKey.ExportPkcs8PrivateKey();
        return ENCODER.Encode(privateKeyBytes);
    }

    public static string ToRsaPublicKeyStr(RSA publicKey) {
        byte[] publicKeyBytes = publicKey.ExportSubjectPublicKeyInfo();
        return ENCODER.Encode(publicKeyBytes);
    }

    private static string BuildRequestSignContent(string customerId, string service, string version, string requestNo, long timestamp, string payload) {
        StringBuilder builder = new StringBuilder();
        if (!string.IsNullOrEmpty(customerId)) {
            builder.Append(customerId).Append("|");
        }
        if (!string.IsNullOrEmpty(service)) {
            builder.Append(service).Append("|");
        }
        if (!string.IsNullOrEmpty(version)) {
            builder.Append(version).Append("|");
        }
        if (!string.IsNullOrEmpty(requestNo)) {
            builder.Append(requestNo).Append("|");
        }
        if (timestamp != 0) {
            builder.Append(timestamp).Append("|");
        }
        if (!string.IsNullOrEmpty(payload)) {
            builder.Append(payload);
        }
        return builder.ToString();
    }
}

public class Base64Encoder {
    public string Encode(byte[] data) {
        return Convert.ToBase64String(data);
    }
}

public class Base64Decoder {
    public byte[] Decode(string data) {
        return Convert.FromBase64String(data);
    }
}

PHP Utilities example

<?php declare(strict_types=1);

class RsaUtils {

    public static function rsaSign(string $privateKeyStr, string $content): string {
        openssl_sign($content, $signature, self::pemFormat($privateKeyStr, 'PRIVATE KEY'), OPENSSL_ALGO_SHA256);
        return base64_encode($signature);
    }

    public static function rsaVerify(string $publicKeyStr, string $content, string $signature): bool {
        return openssl_verify($content, base64_decode($signature), self::pemFormat($publicKeyStr, 'PUBLIC KEY'), OPENSSL_ALGO_SHA256) === 1;
    }

    private static function pemFormat(string $keyStr, string $label): string {
        return "-----BEGIN {$label}-----\n" . chunk_split($keyStr, 64) . "-----END {$label}-----\n";
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Create Card

# Request body

Name	Type	Required	Description	Comment
`requestId`	`String`	`Y`	request ID	Same as Request header.
`customerId`	`String`	`Y`	customer ID	Same as Request header.
`cardCurrencyCode`	`String`	`N`	card currency code	Default same as settlement currency code. ISO 4217 currency code, `3` digits.
`settlementCurrencyCode`	`String`	`Y`	settlement currency code	ISO 4217 currency code, `3` digits.
`activeDate`	`String`	`Y`	effective date	Format `yyyy-MM-dd`.
`inactiveDate`	`String`	`Y`	expiration date	Format `yyyy-MM-dd`.
`cardLimit`	`Number`	`Y`	credit limit	Decimal, matching card currency.
`minAuthAmount`	`Number`	`Y`	lower limit of single authorized transaction	Decimal, matching card currency. (Not take effect on Prepaid card)
`maxAuthAmount`	`Number`	`Y`	upper limit of single authorized transaction	Decimal, matching card currency. (Not take effect on Prepaid card)
`maxAuthTimes`	`Number`	`Y`	maximum authorized transaction times	Integer. `1`: one time card, `-1`: no limit.
`cardCloseUsage`	`Number`	`N`	auto close threshold percentage	Integer, between `0` and `100`, default `0`. When the settled credit / credit limit per cent larger than or equal to this value, the card will be auto closed. Special value `0`: the card will not be auto closed. (Not take effect on Prepaid card)
`supportedMccGroup`	`String`	`Y`	accepted MCC group	Accepted Merchant Category Code group, defined by TripLink. Transaction requests which are not belong to this group will be rejected.
`supportedMid`	`String`	`N`	accepted merchant ID	Transaction requests which are not from this merchant will be rejected.
`supportedAcquirerId`	`String`	`N`	accepted acquirer ID	Transaction requests which are not from this acquirer will be rejected.
`multipleCurrencyCard`	`Boolean`	`N`	whether allow transactions not in card currency	Default `true`.
`allow3ds`	`Boolean`	`N`	whether allow 3DS	Default `true`. (Only take effect on Hong Kong MasterCard)
`cardProductCode`	`String`	`Y`	card product code	Enumerated type Allowed values: `C02`, `C03`, `C05`.
`cardType`	`String`	`Y`	card brand	Enumerated type, default `GWTTP`. Allowed values: `GWTTP`, `MCO`, `USDVCC` etc.
`cardLabel`	`String`	`Y`	card association	Enumerated type, default `MasterCard`. Allowed values: `MasterCard`, `VISA`.
`cardBin`	`String`	`N`	IIN code	The Issuer Identification Number, defined by TripLink.
`quoteId`	`String`	`N`	quote ID	The quote ID returned by FX Quote. If valid, exchange at this rate; If invalid, exchange at the real-time rate. (Only take effect on card product code `C05`)
`timeZone`	`String`	`N`	card time zone	The time zone of the card effective and expiration date, format example: China Standard Time `GMT+08:00` Eastern Standard Time `GMT-05:00` The default value can be configurated at Merchant System/Setting/VAN Default Configuration
`userReferenceMap`	`Object`	`N`	user defined properties	`String` key-value pair, including `20` optional keys. Between `useRef1Txt` and `useRef20Txt`.

request body sample

{
  "requestId": "1ac60d08-0e15-47da-a341-7287dd46ff39",
  "customerId": "CSR47284A93E35E4",
  "cardCurrencyCode": "840",
  "settlementCurrencyCode": "840",
  "activeDate": "2022-01-01",
  "inactiveDate": "2024-06-01",
  "cardLimit": 1000.12,
  "minAuthAmount": 3.45,
  "maxAuthAmount": 500.67,
  "maxAuthTimes": -1,
  "cardCloseUsage": 40,
  "supportedMccGroup": "ecom",
  "multipleCurrencyCard": true,
  "cardBin":"522981",
  "cardType": "GWTTP",
  "cardLabel": "MasterCard",
  "userReferenceMap": {
    "useRef1Txt": "anything"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# Response body

Name	Type	Description	Comment
`returnCode`	`String`	result code	Enumerated type, `6` digits, see result code drop-down list. (code other than `000000` means request failed)
`errorMessage`	`String`	result code description	See result code drop-down list.
`cardLogId`	`String`	card ID	TripLink card ID.
`cardNum`	`String`	card number	`16` digits card number.
`cardExpirationDate`	`String`	expiration date	Format `yyMM`.
`cvv2`	`String`	CVV2	Card Verification Value.
`cardType`	`String`	card brand
`cardLabel`	`String`	card association

result code

returnCode	errorMessage
`000000`	Success
`100000`	Input parameter is incorrect (not fixed)
`100001`	Reduplicative requestid
`200002`	Both MCC, MCC groups and [acquirerId,merchantId] are all empty
`200003`	Customer info not find
`200007`	Global parameter not find
`200008`	InactiveDate must be greater than activeDate
`200013`	Not find the mapping between the cardCurrency and settlementCurrency
`200014`	AcquirerId/mid must not be empty
`200022`	Not find active pan number config
`200029`	Card exists pending request
`200036`	card bin not support
`200037`	InactiveDate must submit
`200038`	cardCloseUsage not be null
`200040`	Invalid global parameter (indate)
`200043`	mcc group is empty
`200044`	mcc group all is not supported
`200048`	Card issuer failed (not fixed)
`200060`	Card issuer parameter error (not fixed)
`201000`	Card available balance exceeds the maximum limit
`300004`	mcc link channel group is empty
`300005`	Trading is risky
`9XXXXX`	System error (not fixed)

response body sample

{
  "returnCode": "000000",
  "errorMessage": "Success",
  "cardLogId": "9448b6a7b3bcb22f99c1bedd246aba092c7932fd5e7f3042607bf58bc7cc3d83",
  "cardNum": "5229811460053354",
  "cardExpirationDate": "2406",
  "cvv2": "123",
  "cardType": "GWTTP",
  "cardLabel": "MasterCard"
}

1
2
3
4
5
6
7
8
9
10

# SDK Sample

Java SDK

public void testCreateCard() {
    HttpClient<CallHttpResponse> httpClient = new TripLinkHttpClient();
    TripLinkBizImplV2 tripLinkCore = new TripLinkBizImplV2(CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY, AES_KEY, BASE_URL, httpClient);
    TripLinkApiImplV2 tripLinkApi = new TripLinkApiImplV2(tripLinkCore);

    CardCreateRequest request = new CardCreateRequest();
    request.setRequestId(UUID.randomUUID().toString());
    request.setCustomerId(CUSTOMER_ID);
    request.setCardCurrencyCode("840");
    request.setSettlementCurrencyCode("840");
    request.setActiveDate("2022-01-01");
    request.setInactiveDate("2024-06-01");
    request.setCardLimit(BigDecimal.valueOf(1000.12));
    request.setMinAuthAmount(BigDecimal.valueOf(3.45));
    request.setMaxAuthAmount(BigDecimal.valueOf(500.67));
    request.setMaxAuthTimes(-1);
    request.setCardCloseUsage(40);
    request.setSupportedMccGroup("ecom");
    request.setMultipleCurrencyCard(true);
    request.setCardBin("522981");
    request.setCardType("GWTTP");
    request.setCardLabel("MasterCard");
    Map<String, String> userReference = new HashMap<>();
    userReference.put("useRef1Txt", "anything");
    request.setUserReferenceMap(userReference);

    CardCreateResponse response = tripLinkApi.create(request);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

PHP SDK

public function testCreateCard(): void {
    $httpClient = new GuzzleHttpClient();
    $customer = new Customer(CUSTOMER_ID, AES_KEY, CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY);
    $tripLinkAgent = new SimpleTripLinkAgent(BASE_URL, $customer, $httpClient);

    $request = new CreateCardRequest(uniqid(), CUSTOMER_ID);
    $request->setCardCurrencyCode('840');
    $request->setSettlementCurrencyCode('840');
    $request->setActiveDate('2022-01-01');
    $request->setInactiveDate('2024-06-01');
    $request->setCardLimit(1000.12);
    $request->setMinAuthAmount(3.45);
    $request->setMaxAuthAmount(500.67);
    $request->setMaxAuthTimes(-1);
    $request->setCardCloseUsage(40);
    $request->setSupportedMccGroup('ecom');
    $request->setMultipleCurrencyCard(true);
    $request->setCardBin('522981');
    $request->setCardType('GWTTP');
    $request->setCardLabel('MasterCard');
    $userReference = new UserReference();
    $userReference->setUseRef1Txt('anything');
    $request->setUserReferenceMap($userReference);

    $response = $tripLinkAgent->createCard($request);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# Update Card

# Request body

Name	Type	Required	Description	Comment
`requestId`	`String`	`Y`	request ID	Same as Request header.
`customerId`	`String`	`Y`	customer ID	Same as Request header.
`cardLogId`	`String`	`Y`	card ID	TripLink card ID.
`activeDate`	`String`	`N`	effective date	Format `yyyy-MM-dd`.
`inactiveDate`	`String`	`N`	expiration date	Format `yyyy-MM-dd`.
`cardLimit`	`Number`	`N`	credit limit	Decimal, matching card currency. (Not take effect on Prepaid card)
`minAuthAmount`	`Number`	`N`	lower limit of single authorized transaction	Decimal, matching card currency. (Not take effect on Prepaid card)
`maxAuthAmount`	`Number`	`N`	upper limit of single authorized transaction	Decimal, matching card currency. (Not take effect on Prepaid card)
`cardCloseUsage`	`Number`	`N`	auto cancel threshold percentage	Integer, between `0` and `100`, default `0`. When the settled credit / credit limit per cent larger than or equal to this value, the card will be auto closed. Special value `0`: the card will not be auto closed. (Not take effect on Prepaid card)
`supportedMccGroup`	`String`	`N`	accepted MCC group	Accepted Merchant Category Code group, defined by TripLink. Transaction requests which are not belong to this group will be rejected.
`supportedMid`	`String`	`N`	accepted merchant ID	Transaction requests which are not from this merchant will be rejected.
`supportedAcquirerId`	`String`	`N`	accepted acquirer ID	Transaction requests which are not from this acquirer will be rejected.
`multipleCurrencyCard`	`Boolean`	`N`	whether allow transactions not in card currency
`allow3ds`	`Boolean`	`N`	whether allow 3DS	(Only take effect on Hong Kong MasterCard)
`timeZone`	`String`	`N`	card time zone	The time zone of the card effective and expiration date, format example: China Standard Time `GMT+08:00` Eastern Standard Time `GMT-05:00` The default value can be configurated at Merchant System/Setting/VAN Default Configuration
`userReferenceMap`	`Object`	`N`	user defined properties	`String` key-value pair, including `20` optional keys. Between `useRef1Txt` and `useRef20Txt`.

request body sample

{
  "requestId": "15b77002-748d-4c89-b6a3-1fa0a25adf3b",
  "customerId": "CSR47284A93E35E4",
  "cardLogId": "9f289daa62ac6e941f918634de3f91a142eea82c09ac27783ea7c2d9c07f8ec3",
  "cardLimit": 2000.12,
  "multipleCurrencyCard": false
}

1
2
3
4
5
6
7

# Response body

Name	Type	Description	Comment
`returnCode`	`String`	result code	Enumerated type, `6` digits, see result code drop-down list. (code other than `000000` means request failed)
`errorMessage`	`String`	result code description	See result code drop-down list.
`cardLogId`	`String`	card ID	TripLink card ID.
`cardNum`	`String`	card number	`16` digits card number.
`cardExpirationDate`	`String`	expiration date	Format `yyMM`.
`cvv2`	`String`	CVV2	Card Verification Value.
`userReferenceMap`	`Object`	user defined properties	`String` key-value pair, including `20` optional keys. Between `useRef1Txt` and `useRef20Txt`.

result code

returnCode	errorMessage
`000000`	Success
`100000`	Input parameter is incorrect (not fixed)
`100001`	Reduplicative requestid
`200001`	ActiveDate must be greater than current date (not fixed)
`200003`	Customer info not find
`200007`	Global parameter not find
`200009`	Effective mccGroup not find
`200014`	AcquirerId/mid must not be empty
`200015`	Not find card
`200016`	Card status is clop or clos
`200019`	Update card limit is less than the amount of used card
`200029`	Card exists pending request
`200032`	Not find customer global setting
`200036`	card bin not support
`200048`	Card issuer failed (not fixed)
`200060`	Card issuer parameter error (not fixed)
`201000`	Card available balance exceeds the maximum limit
`300004`	mcc link channel group is empty
`300005`	Trading is risky
`9XXXXX`	System error (not fixed)

response body sample

{
  "returnCode": "000000",
  "errorMessage": "Success",
  "cardLogId": "9f289daa62ac6e941f918634de3f91a142eea82c09ac27783ea7c2d9c07f8ec3",
  "cardNum": "5395933355051253",
  "cardExpirationDate": "2406",
  "cvv2": "123",
  "userReferenceMap": {
    "useRef1Txt": "anything"
  }
}

1
2
3
4
5
6
7
8
9
10
11

# SDK Sample

Java SDK

public void testUpdateCard() {
    HttpClient<CallHttpResponse> httpClient = new TripLinkHttpClient();
    TripLinkBizImplV2 tripLinkCore = new TripLinkBizImplV2(CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY, AES_KEY, BASE_URL, httpClient);
    TripLinkApiImplV2 tripLinkApi = new TripLinkApiImplV2(tripLinkCore);

    CardUpdateRequest request = new CardUpdateRequest();
    request.setRequestId(UUID.randomUUID().toString());
    request.setCustomerId(CUSTOMER_ID);
    request.setCardLogId(CARD_LOG_ID);
    request.setCardLimit(BigDecimal.valueOf(2000.12));
    request.setMultipleCurrencyCard(false);

    CardUpdateResponse response = tripLinkApi.update(request);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

PHP SDK

public function testUpdateCard(): void {
    $httpClient = new GuzzleHttpClient();
    $customer = new Customer(CUSTOMER_ID, AES_KEY, CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY);
    $tripLinkAgent = new SimpleTripLinkAgent(BASE_URL, $customer, $httpClient);

    $request = new UpdateCardRequest(uniqid(), CUSTOMER_ID);
    $request->setCardLogId(CARD_LOG_ID);
    $request->setCardLimit(2000.12);
    $request->setMultipleCurrencyCard(false);

    $response = $tripLinkAgent->updateCard($request);
}

1
2
3
4
5
6
7
8
9
10
11
12

# Recharge Card

# Request body

Name	Type	Required	Description	Comment
`requestId`	`String`	`Y`	request ID	Same as Request header.
`customerId`	`String`	`Y`	customer ID	Same as Request header.
`cardLogId`	`String`	`Y`	card ID	TripLink card ID.
`rechargeAmount`	`Number`	`Y`	recharge amount	Decimal, matching card currency.

request body sample

{
  "requestId": "9340c297-e8b8-4148-b0b7-3d8aa5fcb487",
  "customerId": "CSR47284A93E35E4",
  "cardLogId": "9261267e66b808e9a2f62fe54e516192677236b943aa2dee1836284b369768d7",
  "rechargeAmount": 100.12
}

1
2
3
4
5
6

# Response body

Name	Type	Description	Comment
`returnCode`	`String`	result code	Enumerated type, `6` digits, see result code drop-down list. (code other than `000000` means request failed)
`errorMessage`	`String`	result code description	See result code drop-down list.

result code

returnCode	errorMessage
`000000`	Success
`100000`	Input parameter is incorrect (not fixed)
`200003`	Customer info not find
`200015`	Not find card
`200016`	Card status is clop or clos
`201000`	Card available balance exceeds the maximum limit
`300003`	Call JPM gateway error
`300004`	mcc link channel group is empty
`9XXXXX`	System error (not fixed)

response body sample

{
  "returnCode": "000000",
  "errorMessage": "Success"
}

1
2
3
4

# SDK Sample

Java SDK

public void testRechargeCard() {
    HttpClient<CallHttpResponse> httpClient = new TripLinkHttpClient();
    TripLinkBizImplV2 tripLinkCore = new TripLinkBizImplV2(CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY, AES_KEY, BASE_URL, httpClient);
    TripLinkApiImplV2 tripLinkApi = new TripLinkApiImplV2(tripLinkCore);

    CardRechargeRequest request = new CardRechargeRequest();
    request.setRequestId(UUID.randomUUID().toString());
    request.setCustomerId(CUSTOMER_ID);
    request.setCardLogId(CARD_LOG_ID);
    request.setRechargeAmount(BigDecimal.valueOf(100.12));

    CardRechargeResponse response = tripLinkApi.recharge(request);
}

1
2
3
4
5
6
7
8
9
10
11
12
13

PHP SDK

public function testRechargeCard(): void {
    $httpClient = new GuzzleHttpClient();
    $customer = new Customer(CUSTOMER_ID, AES_KEY, CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY);
    $tripLinkAgent = new SimpleTripLinkAgent(BASE_URL, $customer, $httpClient);

    $request = new RechargeCardRequest(uniqid(), CUSTOMER_ID);
    $request->setCardLogId(CARD_LOG_ID);
    $request->setRechargeAmount(100.12);

    $response = $tripLinkAgent->rechargeCard($request);
}

1
2
3
4
5
6
7
8
9
10
11

# Withdraw Card

# Request body

Name	Type	Required	Description	Comment
`requestId`	`String`	`Y`	request ID	Same as Request header.
`customerId`	`String`	`Y`	customer ID	Same as Request header.
`cardLogId`	`String`	`Y`	card ID	TripLink card ID.
`withdrawAmount`	`Number`	`Y`	withdraw amount	Decimal, matching card currency.

request body sample

{
  "requestId": "8f26c686-6275-4271-aa6d-a0a6a4df441e",
  "customerId": "CSR47284A93E35E4",
  "cardLogId": "9261267e66b808e9a2f62fe54e516192677236b943aa2dee1836284b369768d7",
  "withdrawAmount": 80.12
}

1
2
3
4
5
6

# Response body

Name	Type	Description	Comment
`returnCode`	`String`	result code	Enumerated type, `6` digits, see result code drop-down list. (code other than `000000` means request failed)
`errorMessage`	`String`	result code description	See result code drop-down list.

result code

returnCode	errorMessage
`000000`	Success
`100000`	Input parameter is incorrect (not fixed)
`200003`	Customer info not find
`200015`	Not find card
`200016`	Card status is clop or clos
`200019`	Update card limit is less than the amount of used card
`200029`	Card exists pending request
`200048`	card issuer failed
`300004`	mcc link channel group is empty
`9XXXXX`	System error (not fixed)

response body sample

{
  "returnCode": "000000",
  "errorMessage": "Success"
}

1
2
3
4

# SDK Sample

Java SDK

public void testWithdrawCard() {
    HttpClient<CallHttpResponse> httpClient = new TripLinkHttpClient();
    TripLinkBizImplV2 tripLinkCore = new TripLinkBizImplV2(CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY, AES_KEY, BASE_URL, httpClient);
    TripLinkApiImplV2 tripLinkApi = new TripLinkApiImplV2(tripLinkCore);

    CardWithdrawRequest request = new CardWithdrawRequest();
    request.setRequestId(UUID.randomUUID().toString());
    request.setCustomerId(CUSTOMER_ID);
    request.setCardLogId(CARD_LOG_ID);
    request.setWithdrawAmount(BigDecimal.valueOf(80.12));

    CardWithdrawResponse response = tripLinkApi.withdraw(request);
}

1
2
3
4
5
6
7
8
9
10
11
12
13

PHP SDK

public function testWithdrawCard(): void {
    $httpClient = new GuzzleHttpClient();
    $customer = new Customer(CUSTOMER_ID, AES_KEY, CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY);
    $tripLinkAgent = new SimpleTripLinkAgent(BASE_URL, $customer, $httpClient);

    $request = new WithdrawCardRequest(uniqid(), CUSTOMER_ID);
    $request->setCardLogId(CARD_LOG_ID);
    $request->setWithdrawAmount(80.12);

    $response = $tripLinkAgent->withdrawCard($request);
}

1
2
3
4
5
6
7
8
9
10
11

# Suspend Card

# Request body

Name	Type	Required	Description	Comment
`requestId`	`String`	`Y`	request ID	Same as Request header.
`customerId`	`String`	`Y`	customer ID	Same as Request header.
`cardLogId`	`String`	`Y`	card ID	TripLink card ID.

request body sample

{
  "requestId": "7d451d22-fab3-471e-acfa-efd7aa3a1db9",
  "customerId": "CSR47284A93E35E4",
  "cardLogId": "f05c9c6670a956150aa346e671d6d9fe757cbe178d555a763631be75e61fee07"
}

1
2
3
4
5

# Response body

Name	Type	Description	Comment
`returnCode`	`String`	result code	Enumerated type, `6` digits, see result code drop-down list. (code other than `000000` means request failed)
`errorMessage`	`String`	result code description	See result code drop-down list.

result code

returnCode	errorMessage
`000000`	Success
`100000`	Input parameter is incorrect (not fixed)
`200003`	Customer info not find
`200015`	Not find card
`200016`	Card status is clop or clos
`300006`	Not support suspend the card
`9XXXXX`	System error (not fixed)

response body sample

{
  "returnCode": "000000",
  "errorMessage": "Success"
}

1
2
3
4

# SDK Sample

Java SDK

public void testSuspendCard() {
    HttpClient<CallHttpResponse> httpClient = new TripLinkHttpClient();
    TripLinkBizImplV2 tripLinkCore = new TripLinkBizImplV2(CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY, AES_KEY, BASE_URL, httpClient);
    TripLinkApiImplV2 tripLinkApi = new TripLinkApiImplV2(tripLinkCore);

    CardSuspendRequest request = new CardSuspendRequest();
    request.setRequestId(UUID.randomUUID().toString());
    request.setCustomerId(CUSTOMER_ID);
    request.setCardLogId(CARD_LOG_ID);

    CardSuspendResponse response = tripLinkApi.suspend(request);
}

1
2
3
4
5
6
7
8
9
10
11
12

PHP SDK

public function testSuspendCard(): void {
    $httpClient = new GuzzleHttpClient();
    $customer = new Customer(CUSTOMER_ID, AES_KEY, CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY);
    $tripLinkAgent = new SimpleTripLinkAgent(BASE_URL, $customer, $httpClient);

    $request = new SuspendCardRequest(uniqid(), CUSTOMER_ID);
    $request->setCardLogId(CARD_LOG_ID);

    $response = $tripLinkAgent->suspendCard($request);
}

1
2
3
4
5
6
7
8
9
10

# Unsuspend Card

# Request body

Name	Type	Required	Description	Comment
`requestId`	`String`	`Y`	request ID	Same as Request header.
`customerId`	`String`	`Y`	customer ID	Same as Request header.
`cardLogId`	`String`	`Y`	card ID	TripLink card ID.

request body sample

{
  "requestId": "7d451d22-fab3-471e-acfa-efd7aa3a1db9",
  "customerId": "CSR47284A93E35E4",
  "cardLogId": "f05c9c6670a956150aa346e671d6d9fe757cbe178d555a763631be75e61fee07"
}

1
2
3
4
5

# Response body

Name	Type	Description	Comment
`returnCode`	`String`	result code	Enumerated type, `6` digits, see result code drop-down list. (code other than `000000` means request failed)
`errorMessage`	`String`	result code description	See result code drop-down list.

result code

returnCode	errorMessage
`000000`	Success
`100000`	Input parameter is incorrect (not fixed)
`200003`	Customer info not find
`200015`	Not find card
`200016`	Card status is clop or clos
`300006`	Not support unsuspend the card
`9XXXXX`	System error (not fixed)

response body sample

{
  "returnCode": "000000",
  "errorMessage": "Success"
}

1
2
3
4

# SDK Sample

Java SDK

public void testUnsuspendCard() {
    HttpClient<CallHttpResponse> httpClient = new TripLinkHttpClient();
    TripLinkBizImplV2 tripLinkCore = new TripLinkBizImplV2(CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY, AES_KEY, BASE_URL, httpClient);
    TripLinkApiImplV2 tripLinkApi = new TripLinkApiImplV2(tripLinkCore);

    CardUnsuspendRequest request = new CardUnsuspendRequest();
    request.setRequestId(UUID.randomUUID().toString());
    request.setCustomerId(CUSTOMER_ID);
    request.setCardLogId(CARD_LOG_ID);

    CardUnsuspendResponse response = tripLinkApi.unsuspend(request);
}

1
2
3
4
5
6
7
8
9
10
11
12

PHP SDK

public function testUnsuspendCard(): void {
    $httpClient = new GuzzleHttpClient();
    $customer = new Customer(CUSTOMER_ID, AES_KEY, CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY);
    $tripLinkAgent = new SimpleTripLinkAgent(BASE_URL, $customer, $httpClient);

    $request = new UnsuspendCardRequest(uniqid(), CUSTOMER_ID);
    $request->setCardLogId(CARD_LOG_ID);

    $response = $tripLinkAgent->unsuspendCard($request);
}

1
2
3
4
5
6
7
8
9
10

# Close Card

# Request body

Name	Type	Required	Description	Comment
`requestId`	`String`	`Y`	request ID	Same as Request header.
`customerId`	`String`	`Y`	customer ID	Same as Request header.
`cardLogId`	`String`	`Y`	card ID	TripLink card ID.

request body sample

{
  "requestId": "7d451d22-fab3-471e-acfa-efd7aa3a1db9",
  "customerId": "CSR47284A93E35E4",
  "cardLogId": "f05c9c6670a956150aa346e671d6d9fe757cbe178d555a763631be75e61fee07"
}

1
2
3
4
5

# Response body

Name	Type	Description	Comment
`returnCode`	`String`	result code	Enumerated type, `6` digits, see result code drop-down list. (code other than `000000` means request failed)
`errorMessage`	`String`	result code description	See result code drop-down list.

result code

returnCode	errorMessage
`000000`	Success
`100000`	Input parameter is incorrect (not fixed)
`200003`	Customer info not find
`200015`	Not find card
`200016`	Card status is clop or clos
`200025`	card status pre cancel not allow
`200051`	card cancel exception
`200053`	Incorrect card status
`300005`	Trading is risky
`9XXXXX`	System error (not fixed)

response body sample

{
  "returnCode": "000000",
  "errorMessage": "Success"
}

1
2
3
4

# SDK Sample

Java SDK

public void testCloseCard() {
    HttpClient<CallHttpResponse> httpClient = new TripLinkHttpClient();
    TripLinkBizImplV2 tripLinkCore = new TripLinkBizImplV2(CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY, AES_KEY, BASE_URL, httpClient);
    TripLinkApiImplV2 tripLinkApi = new TripLinkApiImplV2(tripLinkCore);

    CardCancelRequest request = new CardCancelRequest();
    request.setRequestId(UUID.randomUUID().toString());
    request.setCustomerId(CUSTOMER_ID);
    request.setCardLogId(CARD_LOG_ID);

    CardCancelResponse response = tripLinkApi.close(request);
}

1
2
3
4
5
6
7
8
9
10
11
12

PHP SDK

public function testCloseCard(): void {
    $httpClient = new GuzzleHttpClient();
    $customer = new Customer(CUSTOMER_ID, AES_KEY, CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY);
    $tripLinkAgent = new SimpleTripLinkAgent(BASE_URL, $customer, $httpClient);

    $request = new CloseCardRequest(uniqid(), CUSTOMER_ID);
    $request->setCardLogId(CARD_LOG_ID);

    $response = $tripLinkAgent->closeCard($request);
}

1
2
3
4
5
6
7
8
9
10

# Query Card

# Request body

Name	Type	Required	Description	Comment
`requestId`	`String`	`Y`	request ID	Same as Request header.
`customerId`	`String`	`Y`	customer ID	Same as Request header.
`cardLogId`	`String`	`Y`	card ID	TripLink card ID.

request body sample

{
  "requestId": "5148d00e-d98f-4ccc-a5ef-acd1ff53d37e",
  "customerId": "CSR47284A93E35E4",
  "cardLogId": "0b51f2edf394d3875fa3c284186e5022236a59bc31dda6b3aba7dbe2982bc91a"
}

1
2
3
4
5

# Response body

Name	Type	Description	Comment
`returnCode`	`String`	result code	Enumerated type, `6` digits, see result code drop-down list. (code other than `000000` means request failed)
`errorMessage`	`String`	result code description	See result code drop-down list.
`customerId`	`String`	customer ID	Same as Request header.
`cardLogId`	`String`	card ID	TripLink card ID.
`cardCurrencyCode`	`String`	card currency code	ISO 4217 currency code, `3` digits.
`settlementCurrencyCode`	`String`	settlement currency code	ISO 4217 currency code, `3` digits.
`activeDate`	`String`	effective date	Format `yyyy-MM-dd`.
`inactiveDate`	`String`	expiration date	Format `yyyy-MM-dd`.
`cardLimit`	`Number`	credit limit	Decimal, matching card currency.
`minAuthAmount`	`Number`	lower limit of single authorized transaction	Decimal, matching card currency. (Not take effect on Prepaid card)
`maxAuthAmount`	`Number`	upper limit of single authorized transaction	Decimal, matching card currency. (Not take effect on Prepaid card)
`maxAuthTimes`	`Number`	maximum authorized transaction times	Integer. `1`: one time card, `-1`: no limit.
`cardCloseUsage`	`Number`	auto cancel threshold percentage	Integer, between `0` and `100`, default `0`. When the settled credit / credit limit per cent larger than or equal to this value, the card will be auto closed. Special value `0`: the card will not be auto closed. (Not take effect on Prepaid card)
`supportedMccGroup`	`String`	accepted MCC group	Accepted Merchant Category Code group, defined by TripLink. Transaction requests which are not belong to this group will be rejected.
`supportedMid`	`String`	accepted merchant ID	Transaction requests which are not from this merchant will be rejected.
`supportedAcquirerId`	`String`	accepted acquirer ID	Transaction requests which are not from this acquirer will be rejected.
`multipleCurrencyCard`	`Boolean`	whether allow transactions not in card currency
`allow3ds`	`Boolean`	whether allow 3DS	Only take effect on Hong Kong MasterCard
`applyTime`	`String`	apply date	Format `yyyy-MM-dd`.
`status`	`String`	card status	`NORM`: Normal, `SUSP`: Suspended, `CLOP`: Pre-Canceled, `CLOS`: Canceled.
`cardNum`	`String`	card number	`16` digits card number.
`cardExpirationDate`	`String`	expiration date	Format `yyMM`.
`cvv2`	`String`	CVV2	Card Verification Value.
`availableBalance`	`Number`	available balance	Decimal, matching card currency.
`authorizeAmount`	`Number`	authorized amount	Decimal, matching card currency.
`settlementAmount`	`Number`	settled amount	Decimal, matching card currency.
`cardType`	`String`	card brand	Enumerated type. Allowed values: `GWTTP`, `MCO`, `USDVCC` etc.
`cardLabel`	`String`	card association	Enumerated type. Allowed values: `MasterCard`, `VISA`.
`timeZone`	`String`	card time zone	The time zone of the card effective and expiration date, format example: China Standard Time `GMT+08:00` Eastern Standard Time `GMT-05:00` The default value can be configurated at Merchant System/Setting/VAN Default Configuration
`userReferenceMap`	`Object`	user defined properties	`String` key-value pair, including `20` optional keys. Between `useRef1Txt` and `useRef20Txt`.

result code

returnCode	errorMessage
`000000`	Success
`100000`	Input parameter is incorrect (not fixed)
`200015`	Not find card
`9XXXXX`	System error (not fixed)

response body sample

{
  "returnCode": "000000",
  "errorMessage": "Success",
  "customerId": "CSR47284A93E35E4",
  "cardLogId": "0b51f2edf394d3875fa3c284186e5022236a59bc31dda6b3aba7dbe2982bc91a",
  "cardCurrencyCode": "840",
  "settlementCurrencyCode": "840",
  "activeDate": "2022-01-01",
  "inactiveDate": "2024-06-01",
  "cardLimit": 1000.12,
  "minAuthAmount": 3.45,
  "maxAuthAmount": 500.67,
  "maxAuthTimes": -1,
  "cardCloseUsage": 40,
  "supportedMccGroup": "ecom",
  "multipleCurrencyCard": true,
  "allow3ds": true,
  "applyTime": "2022-02-17",
  "status": "NORM",
  "cardNum": "5395933355052420",
  "cardExpirationDate": "2406",
  "cvv2": "123",
  "availableBalance": 1000.12,
  "authorizeAmount": 0.00,
  "settlementAmount": 0.00,
  "cardType": "GWTTP",
  "cardLabel": "MasterCard",
  "timeZone": "GMT+08:00",
  "userReferenceMap": {
    "useRef1Txt": "anything"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# SDK Sample

Java SDK

public void testQueryCard() {
    HttpClient<CallHttpResponse> httpClient = new TripLinkHttpClient();
    TripLinkBizImplV2 tripLinkCore = new TripLinkBizImplV2(CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY, AES_KEY, BASE_URL, httpClient);
    TripLinkApiImplV2 tripLinkApi = new TripLinkApiImplV2(tripLinkCore);

    CardDetailQueryRequest request = new CardDetailQueryRequest();
    request.setRequestId(UUID.randomUUID().toString());
    request.setCustomerId(CUSTOMER_ID);
    request.setCardLogId(CARD_LOG_ID);

    CardDetailQueryResponse response = tripLinkApi.queryCard(request);
}

1
2
3
4
5
6
7
8
9
10
11
12

PHP SDK

public function testQueryCard(): void {
    $httpClient = new GuzzleHttpClient();
    $customer = new Customer(CUSTOMER_ID, AES_KEY, CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY);
    $tripLinkAgent = new SimpleTripLinkAgent(BASE_URL, $customer, $httpClient);

    $request = new QueryCardRequest(uniqid(), CUSTOMER_ID);
    $request->setCardLogId(CARD_LOG_ID);

    $response = $tripLinkAgent->queryCard($request);
}

1
2
3
4
5
6
7
8
9
10

# Query Account Credit

# Request body

Name	Type	Required	Description	Comment
`requestId`	`String`	`Y`	request ID	Same as Request header.
`customerId`	`String`	`Y`	customer ID	Same as Request header.

request body sample

{
  "requestId": "3ddf14f6-04b0-4a66-840b-a21cf0c148ee",
  "customerId": "CSR47284A93E35E4"
}

1
2
3
4

# Response body

Name	Type	Description	Comment
`returnCode`	`String`	result code	Enumerated type, `6` digits, see result code drop-down list. (code other than `000000` means request failed)
`errorMessage`	`String`	result code description	See result code drop-down list.
`customerId`	`String`	customer ID	Same as Request header.
`list`	`Array`	account information	See `Account`.

Account

Name	Type	Description	Comment
`accountType`	`String`	account type	`CREDIT`: credit account; `DEBIT`: debit account; `CCP_ACCT`: exchange account.
`accountCurrency`	`String`	account currency	ISO 4217 currency code, `3` digits.
`accountAmount`	`Number`	account amount	Only has value when account type `CREDIT`. Decimal, matching card currency.
`remainAccountAmount`	`Number`	remain account amount	Decimal, matching card currency.

result code

returnCode	errorMessage
`000000`	Success
`100000`	input parameter is incorrect
`200007`	not find the account credit
`9XXXXX`	System error (not fixed)

response body sample

{
  "returnCode": "000000",
  "errorMessage": "success",
  "customerId": "CSR47284A93E35E4",
  "list": [
    {
      "accountType": "DEBIT",
      "accountCurrency": "840",
      "remainAccountAmount": 999967.66
    },
    {
      "accountType": "DEBIT",
      "accountCurrency": "978",
      "remainAccountAmount": 999999.99
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# SDK Sample

Java SDK

public void testQueryAccount() {
    HttpClient<CallHttpResponse> httpClient = new TripLinkHttpClient();
    TripLinkBizImplV2 tripLinkCore = new TripLinkBizImplV2(CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY, AES_KEY, BASE_URL, httpClient);
    TripLinkApiImplV2 tripLinkApi = new TripLinkApiImplV2(tripLinkCore);

    QueryCustomerCreditAmountRequest request = new QueryCustomerCreditAmountRequest();
    request.setRequestId(UUID.randomUUID().toString());
    request.setCustomerId(CUSTOMER_ID);

    QueryCustomerCreditAmountResponse response = tripLinkApi.queryCustomerCreditAmount(request);
}

1
2
3
4
5
6
7
8
9
10
11

PHP SDK

public function testQueryAccount(): void {
    $httpClient = new GuzzleHttpClient();
    $customer = new Customer(CUSTOMER_ID, AES_KEY, CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY);
    $tripLinkAgent = new SimpleTripLinkAgent(BASE_URL, $customer, $httpClient);

    $request = new QueryAccountRequest(uniqid(), CUSTOMER_ID);

    $response = $tripLinkAgent->queryAccount($request);
}

1
2
3
4
5
6
7
8
9

# Query Authorization Transactions

# Request body

Name	Type	Required	Description	Comment
`requestId`	`String`	`Y`	request ID	Same as Request header.
`customerId`	`String`	`Y`	customer ID	Same as Request header.
`cardLogId`	`String`	`Y`	card ID	TripLink card ID.
`orderNo`	`String`	`N`	order number	Order number.
`transactionStatus`	`String`	`N`	transaction status	Enumerated type, allowed values: `1`: Approved, `2`: Declined.
`transactionCode`	`String`	`N`	transaction type	Enumerated type, `4` digits, see authorization type drop-down list.
`transactionStartTime`	`String`	`N`	transaction start time	Format `yyyy-MM-dd HH:mm:ss`.
`transactionEndTime`	`String`	`N`	transaction end time	Format `yyyy-MM-dd HH:mm:ss`.
`pageNo`	`Number`	`N`	page number	Integer, range `[1,100]`, default `1`.
`pageSize`	`Number`	`N`	page size	Integer, range `[1,100]`, default `5`.

request body sample

{
    "requestId":"7fb57ff0-ea70-4099-acf5-eacba55e18ef",
    "customerId":"CSR47284A93E35E4",
    "cardLogId":"c55d99dac26bb334c07879404a93d2c6a96b42f7372f9c04d14034d019203fe4",
    "transactionStartTime":"2022-10-01 03:00:00",
    "transactionEndTime":"2022-10-02 04:00:00",
    "pageNo":1,
    "pageSize":10
}

1
2
3
4
5
6
7
8
9

# Response body

Name	Type	Description	Comment
`returnCode`	`String`	result code	Enumerated type, `6` digits, see result code drop-down list. (code other than `000000` means request failed)
`errorMessage`	`String`	result code description	See result code drop-down list.
`cardLogId`	`String`	card ID	TripLink card ID.
`count`	`Number`	count	Integer, the number of transaction data returned.
`more`	`Boolean`	more data	Whether there are more paginated data under this request condition. `true` means there are more.
`transactionData`	`Array`	authorization transactions	See `AuthTransaction`.

result code

returnCode	errorMessage
`000000`	Success
`100007`	NOT_FIND_CARD
`9XXXXX`	System error (not fixed)

AuthTransaction

Name	Type	Description	Comment
`requestId`	`String`	transaction ID	Globally unique.
`cardLogId`	`String`	card ID	TripLink card ID.
`transactionId`	`String`	transaction relation ID	Authorization and corresponding reversal has same value.
`orderNo`	`String`	order number	Order number.
`transactionCurrencyCode`	`String`	transaction currency code	ISO 4217 currency code, `3` digits.
`transactionAmount`	`Number`	transaction amount	Decimal, matching transaction currency.
`cardCurrencyCode`	`String`	card currency	ISO 4217 currency code, `3` digits.
`cardTransactionAmount`	`Number`	card transaction Amount	Decimal, matching card currency.
`responseCode`	`String`	transaction response code	Enumerated type, `4` digits, see response code drop-down list. (code other than `0000` means authorization reject)
`responseDescription`	`String`	transaction response code description	See response code drop-down list.
`approvalCode`	`String`	authorization code	Random `6` alphanumeric.
`transactionCode`	`String`	transaction type	Enumerated type, `4` digits, see authorization type drop-down list.
`transactionDate`	`String`	transaction time	Format `yyyy-MM-dd HH:mm:ss`.
`localTime`	`String`	transaction local time	Format `yyyy-MM-dd HH:mm:ss`.
`merchantName`	`String`	merchant name
`mcc`	`String`	merchant MCC	`ISO 18245` merchant type, `4` digits.
`merchantCountry`	`String`	merchant country	(unstandardized)
`isoMerchantCountryCode`	`String`	merchant country	ISO 3166 country code, `3` letters. (maybe empty)
`merchantCity`	`String`	merchant city
`merchantId`	`String`	merchant ID
`acquiringBankId`	`String`	acquirer ID
`cardInitialBalance`	`Number`	card opening balance	Decimal, matching card currency.
`cardEndingBalance`	`Number`	card closing balance	Decimal, matching card currency.
`creditTransactionSign`	`String`	credit transaction marker	Enumerated type, allowed values: `0`: Debit, `1`: Credit.
`reversalType`	`String`	reversal type	Only has value when authorization type `6930` or `6940`. `0`: system reversal; `1`: non system reversal.

authorization type

messageType	messageTypeDescription	Transaction Direction
`6810`	Authorization Approval	Debit
`6510`	Auth Refund Approval	Credit
`6930`	Authorization Reversal Approval	Credit
`6940`	Auth Refund Reversal Approval	Debit
`6820`	Authorization Query	Debit

response code (6810 Authorization Approval)

responseCode	responseCodeDescription
`0000`	Authorization Approval
`1002`	High Risk Transaction
`1003`	Invalid Account
`1101`	Abnormal Customer Status
`1102`	Card canceled
`1103`	Authorization Amount Error
`1104`	VAN Amount Limit Error
`1105`	Invalid Expiry Date
`1106`	Transaction Count Over Limit
`1107`	Invalid CVV2
`1108`	VAN Amount Limit Error
`1110`	Trans Currency Not Allowed
`1111`	MCC Error
`1112`	VAN credit limit greater than max Limit
`1113`	VAN credit limit less than min Limit
`1114`	Transaction Date before card activeDate
`1115`	Transaction Date after card inactiveDate
`1116`	Auth Amount greater than available VAN credit limit
`1117`	Auth Amount greater than available account credit limit
`1118`	Limited usage with abnormal card status
`1201`	Authorization already in process, please wait until the last authorization completed
`1203`	Not support 3ds
`2012`	Cardholder cancels identity verification
`2014`	Cardholder fails to complete identity verification within the specified time
`2019`	Cardholder fails to complete identity verification within the specified number of attempts
`2022`	Merchant requests invalid information
`2222`	Authorization decision reject
`2299`	Authorization decision downgrade reject
`3004`	Abnormal Card Scheme Network
`9000`	Unknow Error

response code (6510 Auth Refund Approval)

responseCode	responseCodeDescription
`0000`	Authorization Approval
`1002`	High Risk Transaction
`1003`	Invalid Account
`1101`	Abnormal Customer Status
`1107`	Invalid CVV2
`1110`	Trans Currency Not Allowed
`1111`	MCC Error

response code (6930 Authorization Reversal Approval)

responseCode	responseCodeDescription
`0000`	Authorization Approval
`1002`	High Risk Transaction
`1003`	Invalid Account
`1101`	Abnormal Customer Status
`1105`	Invalid Expiry Date
`2001`	Original Transaction Unmatch
`2002`	Original Transaction Unmatch

response code (6940 Auth Refund Reversal Approval)

responseCode	responseCodeDescription
`0000`	Authorization Approval
`1002`	High Risk Transaction
`1003`	Invalid Account
`2001`	Original Transaction Unmatch
`2002`	Original Transaction Unmatch

response code (6820 Authorization Query)

responseCode	responseCodeDescription
`0000`	Authorization Approval
`1002`	High Risk Transaction
`1003`	Invalid Account
`1102`	Card canceled
`1118`	Limited usage with abnormal card status

response body sample

{
    "returnCode":"000000",
    "errorMessage":"Success",
    "cardLogId":"3d70589dfe5c9a771c520d3382ad67af6a17389128b1c3d7968d33b3f62d0703",
    "count":1,
    "more":true,
    "transactionData":[
        {
            "cardLogId":"3d70589dfe5c9a771c520d3382ad67af6a17389128b1c3d7968d33b3f62d0703",
            "requestId":"63fe1c0b-9030-4d57-82c7-74eec6e4a450",
            "transactionId":"0707110634049997213457",
            "orderNo":"dingdan11",
            "transactionCurrencyCode":"344",
            "transactionAmount":1000,
            "cardCurrencyCode":"840",
            "cardTransactionAmount":127.44,
            "responseCode":"0000",
            "responseDescription":"Authorization Approval",
            "approvalCode":"730704",
            "transactionCode":"6810",
            "transactionDate":"2022-07-07 19:06:34",
            "localTime":"2022-07-07 13:06:34",
            "merchantName":"ALIEXPRESS.COM",
            "mcc":"0015",
            "merchantCountry":"SGP",
            "merchantCity":"Singapore",
            "merchantId":"87846545546",
            "acquiringBankId":"213457",
            "creditTransactionSign":"0",
            "reversalType":"0"
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# SDK Sample

Java SDK

public void testQueryAuthorizationByPage() {
    HttpClient<CallHttpResponse> httpClient = new TripLinkHttpClient();
    TripLinkBizImplV2 tripLinkCore = new TripLinkBizImplV2(CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY, AES_KEY, BASE_URL, httpClient);
    TripLinkApiImplV2 tripLinkApi = new TripLinkApiImplV2(tripLinkCore);

    QueryAuthTransactionByPageRequest request = new QueryAuthTransactionByPageRequest();
    request.setRequestId(UUID.randomUUID().toString());
    request.setCustomerId(CUSTOMER_ID);
    request.setCardLogId(CARD_LOG_ID);
    request.setTransactionStartTime("2022-02-01 03:00:00");
    request.setTransactionEndTime("2022-03-02 04:00:00");

    QueryAuthTransactionByPageResponse response = tripLinkApi.authTransactionQueryByPage(request);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

PHP SDK

public function testQueryAuthorizationByPage(): void {
    $httpClient = new GuzzleHttpClient();
    $customer = new Customer(CUSTOMER_ID, AES_KEY, CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY);
    $tripLinkAgent = new SimpleTripLinkAgent(BASE_URL, $customer, $httpClient);

    $request = new QueryAuthorizationByPageRequest(uniqid(), CUSTOMER_ID);
    $request->setCardLogId(CARD_LOG_ID);
    $request->setTransactionStartTime('2022-02-01 03:00:00');
    $request->setTransactionEndTime('2022-03-02 04:00:00');

    $response = $tripLinkAgent->queryAuthorizationByPage($request);
}

1
2
3
4
5
6
7
8
9
10
11
12

# Query Settlement Transactions

# Request body

Name	Type	Required	Description	Comment
`requestId`	`String`	`Y`	request ID	Same as Request header.
`customerId`	`String`	`Y`	customer ID	Same as Request header.
`cardLogId`	`String`	`Y`	card ID	TripLink card ID.
`settlementStartTime`	`String`	`Y`	settlement start time	Format `yyyy-MM-dd HH:mm:ss`.
`settlementEndTime`	`String`	`Y`	settlement end time	Format `yyyy-MM-dd HH:mm:ss`.
`pageNo`	`Number`	`N`	page number	Integer, range `[1,100]`, default `1`.
`pageSize`	`Number`	`N`	page size	Integer, range `[1,100]`, default `5`.

request body sample

{
  "requestId": "9032aee1-85aa-41e8-bc46-7ff8bb36097d",
  "customerId": "CSR47284A93E35E4",
  "cardLogId": "c55d99dac26bb334c07879404a93d2c6a96b42f7372f9c04d14034d019203fe4",
  "settlementStartTime": "2022-02-01 03:00:00",
  "settlementEndTime": "2022-03-01 04:00:00"
}

1
2
3
4
5
6
7

# Response body

Name	Type	Description	Comment
`returnCode`	`String`	result code	Enumerated type, `6` digits, see result code drop-down list. (code other than `000000` means request failed)
`errorMessage`	`String`	result code description	See result code drop-down list.
`cardLogId`	`String`	card ID	TripLink card ID.
`count`	`Number`	count	Integer, the number of transaction data returned.
`more`	`Boolean`	more data	Whether there are more paginated data under this request condition. `true` means there are more.
`settlementData`	`Array`	settlement transactions	See `SettlementTransaction`.

result code

returnCode	errorMessage
`000000`	Success
`100000`	Input parameter is incorrect
`100007`	NOT_FIND_CARD
`9XXXXX`	System error (not fixed)

SettlementTransaction

Name	Type	Description	Comment
`serialNo`	`String`	transaction ID	Globally unique.
`occurDateTime`	`String`	transaction time	Format `yyyy-MM-dd HH:mm:ss`.
`postingDateTime`	`String`	posting time	Format `yyyy-MM-dd HH:mm:ss`.
`postingSysTime`	`String`	system posting time	Format `yyyy-MM-dd`.
`transactionCode`	`String`	transaction type	Enumerated type, `4` digits, see settlement type drop-down list.
`transactionType`	`String`	transaction code description	See settlement type drop-down list.
`approvalCode`	`String`	authorization code	Random `6` alphanumeric.
`isCredit`	`String`	credit transaction	`DEBT`: Debit, `CRED`: Credit.
`originalTransactionCurrency`	`String`	transaction currency code	ISO 4217 currency code, `3` digits.
`originalTransactionAmount`	`Number`	transaction amount	Decimal, matching transaction currency.
`cardTransactionCurrency`	`String`	card currency	ISO 4217 currency code, `3` digits.
`cardTransactionAmount`	`Number`	card transaction Amount	Decimal, matching card currency.
`accountCurrency`	`String`	settlement currency code	ISO 4217 currency code, `3` digits.
`billAccountAmount`	`Number`	settlement amount	Decimal, matching settlement currency.
`posMerchantID`	`String`	merchant ID
`posMerchantName`	`String`	merchant name
`posMerchantClassCode`	`String`	merchant MCC	`ISO 18245` merchant type, `4` digits.
`posMerchantCountry`	`String`	merchant country	(unstandardized)
`isoMerchantCountryCode`	`String`	merchant country	ISO 3166 country code, `3` letters. (maybe empty)
`posMerchantCity`	`String`	merchant city
`posAcquirerID`	`String`	acquirer ID
`transactionId`	`String`	transaction relation ID	Settlement and corresponding authorization has same value.

settlement type

transactionCode	transactionType	Debit/Credit	Amount Sign
`2010`	Purchase	`DEBT`	Positive
`2110`	Refund	`CRED`	Negative
`4060`	Chargeback Release	`DEBT`	Positive
`4160`	Chargeback	`CRED`	Negative
`4170`	Dispute Claim	`DEBT`	Positive
`4260`	Dispute Refund	`CRED`	Negative

response body sample

# SDK Sample

Java SDK

PHP SDK

# Initiate Account Withdrawal

# Request body

Name	Type	Required	Description	Comment
`requestId`	`String`	`Y`	request ID	Same as Request header.
`customerId`	`String`	`Y`	customer ID	Same as Request header.
`paymentCurrency`	`String`	`Y`	withdrawal currency code	ISO 4217 currency code, `3` digits.
`paymentAmount`	`Number`	`Y`	withdrawal amount	Decimal, matching withdrawal currency.
`beneficiaryAccountNo`	`String`	`Y`	beneficiary account number	The account must be registered at TripLink. Please contact your account manager for details.
`beneficiaryAccountName`	`String`	`Y`	beneficiary account name
`beneficiaryBankName`	`String`	`Y`	beneficiary bank name
`beneficiaryBankCountryCode`	`String`	`Y`	beneficiary bank country	ISO 3166 country code, `2` letters.
`reference`	`String`	`Y`	reference	Will be directly transmitted to the receiving bank, the length should not exceed 90 characters. Only English, numbers, spaces, and some special characters , - ()./ are allowed.
`clientOrderId`	`String`	`N`	client order ID

request body sample

{
  "requestId": "9032aee1-85aa-41e8-bc46-7ff8bb36097d",
  "customerId": "CSR47284A93E35E4",
  "paymentCurrency": "840",
  "paymentAmount": "100.21",
  "beneficiaryAccountNo": "660010011001",
  "beneficiaryAccountName": "Trip company",
  "beneficiaryBankName": "JP Morgan",
  "beneficiaryBankCountryCode": "HK",
  "reference": "payment to xx",
  "clientOrderId": "13211000"
}

1
2
3
4
5
6
7
8
9
10
11
12

# Response body

Name	Type	Description	Comment
`returnCode`	`String`	result code	Enumerated type, `6` digits, see result code drop-down list. (code other than `000000` means request failed)
`errorMessage`	`String`	result code description	See result code drop-down list.
`orderId`	`String`	order ID	Globally unique.
`paymentCurrency`	`String`	withdrawal currency code	ISO 4217 currency code, `3` digits.
`paymentAmount`	`Number`	withdrawal amount	Decimal, matching withdrawal currency.
`acceptTime`	`String`	acceptance time	Format `yyyy-MM-dd HH:mm:ss`.

result code

returnCode	errorMessage
`000000`	Success
`100000`	Input parameter is incorrect
`150016`	RequestId is exists
`9XXXXX`	System error (not fixed)

response body sample

{
  "returnCode": "000000",
  "errorMessage": "Success",
  "orderId": "142303141346210898",
  "paymentCurrency": "840",
  "paymentAmount": "100.21",
  "acceptTime": "2023-03-14 12:00:00"
}

1
2
3
4
5
6
7
8

# SDK Sample

Java SDK

public void testPayoutCreate() {
    HttpClient<CallHttpResponse> httpClient = new TripLinkHttpClient();
    TripLinkBizImplV2 tripLinkCore = new TripLinkBizImplV2(CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY, AES_KEY, BASE_URL, httpClient);
    TripLinkApiImplV2 tripLinkApi = new TripLinkApiImplV2(tripLinkCore);

    PayoutCreateRequest request = new PayoutCreateRequest();
    request.setRequestId(UUID.randomUUID().toString());
    request.setCustomerId("CSR2E54DC4B8A5D4");
    request.setPaymentCurrency("840");
    request.setPaymentAmount(new BigDecimal("100"));
    request.setBeneficiaryAccountNo("12321424");
    request.setBeneficiaryAccountName("trip company");
    request.setBeneficiaryBankName("bank name");
    request.setBeneficiaryBankCountryCode("HK");
    request.setReference("reference123");
    request.setClientOrderId("f334f967102d");
    
    PayoutCreateResponse response = tripLinkApi.payoutCreate(request);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

PHP SDK

# Query Account Withdrawal

# Request body

Name	Type	Required	Description	Comment
`requestId`	`String`	`Y`	request ID	Same as Request header.
`customerId`	`String`	`Y`	customer ID	Same as Request header.
`oriRequestId`	`String`	`Y`	original initiate request ID

:: details request body sample

{
  "requestId": "68519520-66ef-404d-82cc-fa34f967002d",
  "customerId": "CSR47284A93E35E4",
  "oriRequestId": "9032aee1-85aa-41e8-bc46-7ff8bb36097d"
}

1
2
3
4
5

:::

# Response body

Name	Type	Description	Comment
`returnCode`	`String`	result code	Enumerated type, `6` digits, see result code drop-down list. (code other than `000000` means request failed)
`errorMessage`	`String`	result code description	See result code drop-down list.
`orderId`	`String`	order ID	Globally unique.
`status`	`String`	order status	`1`: Processing, `2`: Remitted, `3`: Review Rejection, `4`: Remittance Rejection, `5`: Remittance Exception, `6`: Refunded
`paymentCurrency`	`String`	withdrawal currency code	ISO 4217 currency code, `3` digits.
`paymentAmount`	`Number`	withdrawal amount	Decimal, matching withdrawal currency.
`beneficiaryAccountNo`	`String`	beneficiary account number
`beneficiaryAccountName`	`String`	beneficiary account name
`acceptTime`	`String`	acceptance time	Format `yyyy-MM-dd HH:mm:ss`.
`clientOrderId`	`String`	client order ID

result code

returnCode	errorMessage
`000000`	Success
`100000`	Input parameter is incorrect
`150017`	Order is not exists
`9XXXXX`	System error (not fixed)

response body sample

{
  "returnCode": "000000",
  "errorMessage": "Success",
  "orderId": "142303141346210898",
  "status": 1,
  "paymentCurrency": "840",
  "paymentAmount": "100.21",
  "beneficiaryAccountNo": "1232112",
  "beneficiaryAccountName": "trip company",
  "acceptTime": "2023-03-14 12:00:00",
  "clientOrderId": "clientOrderId"
}

1
2
3
4
5
6
7
8
9
10
11
12

# SDK Sample

Java SDK

public void testPayoutQuery() {
    HttpClient<CallHttpResponse> httpClient = new TripLinkHttpClient();
    TripLinkBizImplV2 tripLinkCore = new TripLinkBizImplV2(CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY, AES_KEY, BASE_URL, httpClient);
    TripLinkApiImplV2 tripLinkApi = new TripLinkApiImplV2(tripLinkCore);

    PayoutQueryRequest request = new PayoutQueryRequest();
    request.setRequestId(UUID.randomUUID().toString());
    request.setCustomerId("CSR2E54DC4B8A5D4");
    request.setOriRequestId("9032aee1-85aa-41e8-bc46-7ff8bb36097d");
    
    PayoutQueryResponse response = tripLinkApi.payoutQuery(request);
}

1
2
3
4
5
6
7
8
9
10
11
12

PHP SDK

# FX Quote

# Request body

Name	Type	Required	Description	Comment
`requestId`	`String`	`Y`	request ID	Same as Request header.
`customerId`	`String`	`Y`	customer ID	Same as Request header.
`sellCurrency`	`String`	`Y`	sell currency	ISO 4217 currency code, `3` digits.
`buyCurrency`	`String`	`Y`	buy currency	ISO 4217 currency code, `3` digits.
`fxDirection`	`Number`	`Y`	trading direction	`0`：Selling, in this case, `fxAmount` is the sell amount; `1`：Buying, in this case, `fxAmount` is the buy amount.
`fxAmount`	`Number`	`Y`	trading amount	Decimal, matching buy or sell currency.

request body sample

{
  "requestId": "3ddf14f6-04b0-4a66-840b-a21cf0c148ee",
  "customerId": "CSR47284A93E35E4",
  "sellCurrency": "156",
  "buyCurrency": "840",
  "fxDirection": 0,
  "fxAmount": 100.00
}

1
2
3
4
5
6
7
8

# Response body

Name	Type	Description	Comment
`returnCode`	`String`	result code	Enumerated type, `6` digits, see result code drop-down list. (code other than `000000` means request failed)
`errorMessage`	`String`	result code description	See result code drop-down list.
`quoteId`	`String`	quote ID	Globally unique.
`sellCurrency`	`String`	sell currency	ISO 4217 currency code, `3` digits.
`sellAmount`	`Number`	sell amount	Decimal, matching sell currency.
`buyCurrency`	`String`	buy currency	ISO 4217 currency code, `3` digits.
`buyAmount`	`Number`	buy amount	Decimal, matching buy currency.
`rate`	`Number`	exchange rate	Decimal.
`expireTime`	`String`	expiration time	Format `yyyy-MM-dd HH:mm:ss` (Time zone `UTC+08:00`).

result code

returnCode	errorMessage
`000000`	Success
`9XXXXX`	System error (not fixed)

response body sample

{
  "returnCode": "000000",
  "errorMessage": "success",
  "quoteId": "f3c41a86e880f2c71de0b5c45d4ae066",
  "sellCurrency": "156",
  "sellAmount": 100.00,
  "buyCurrency": "840",
  "buyAmount": 15.72,
  "rate": 0.15707102,
  "expireTime": "2022-02-25 21:56:51"
}

1
2
3
4
5
6
7
8
9
10
11

# SDK Sample

Java SDK

public void testFxQuote() {
    HttpClient<CallHttpResponse> httpClient = new TripLinkHttpClient();
    TripLinkBizImplV2 tripLinkCore = new TripLinkBizImplV2(CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY, AES_KEY, BASE_URL, httpClient);
    TripLinkApiImplV2 tripLinkApi = new TripLinkApiImplV2(tripLinkCore);

    QuoteRequest request = new QuoteRequest();
    request.setRequestId(UUID.randomUUID().toString());
    request.setCustomerId(CUSTOMER_ID);
    request.setSellCurrency("156");
    request.setBuyCurrency("840");
    request.setFxDirection(0);
    request.setFxAmount(BigDecimal.valueOf(100.00));

    QuoteResponse response = tripLinkApi.quote(request);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

PHP SDK

public function testFxQuote(): void {
    $httpClient = new GuzzleHttpClient();
    $customer = new Customer(CUSTOMER_ID, AES_KEY, CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY);
    $tripLinkAgent = new SimpleTripLinkAgent(BASE_URL, $customer, $httpClient);

    $request = new FxQuoteRequest(uniqid(), CUSTOMER_ID);
    $request->setSellCurrency('156');
    $request->setBuyCurrency('840');
    $request->setFxDirection(0);
    $request->setFxAmount(100.00);

    $response = $tripLinkAgent->fxQuote($request);
}

1
2
3
4
5
6
7
8
9
10
11
12
13

# FX Create Order

# Request body

Name	Type	Required	Description	Comment
`requestId`	`String`	`Y`	request ID	Same as Request header.
`customerId`	`String`	`Y`	customer ID	Same as Request header.
`sellCurrency`	`String`	`Y`	sell currency	ISO 4217 currency code, `3` digits.
`buyCurrency`	`String`	`Y`	buy currency	ISO 4217 currency code, `3` digits.
`fxDirection`	`Number`	`Y`	trading direction	`0`：Selling, in this case, `fxAmount` is the sell amount; `1`：Buying, in this case, `fxAmount` is the buy amount.
`fxAmount`	`Number`	`Y`	trading amount	Decimal, matching buy or sell currency.
`quoteId`	`String`	`N`	quote ID	The quote ID returned by FX Quote. If not provided, exchange at the real-time rate.

request body sample

{
  "requestId": "9032aee1-85aa-41e8-bc46-7ff8bb36097d",
  "customerId": "CSR32384FAC033D4",
  "sellCurrency": "840",
  "buyCurrency": "157",
  "fxDirection": "0",
  "fxAmount": "200.99"
}

1
2
3
4
5
6
7
8

# Response body

Name	Type	Description	Comment
`returnCode`	`String`	result code	Enumerated type, `6` digits, see result code drop-down list. (code other than `000000` means request failed)
`errorMessage`	`String`	result code description	See result code drop-down list.
`orderId`	`String`	order ID	Globally unique.
`acceptTime`	`String`	acceptance time	Format `yyyy-MM-dd HH:mm:ss`.
`sellCurrency`	`String`	sell currency	ISO 4217 currency code, `3` digits.
`sellAmount`	`Number`	sell amount	Decimal, matching sell currency.
`buyCurrency`	`String`	buy currency	ISO 4217 currency code, `3` digits.
`buyAmount`	`Number`	buy amount	Decimal, matching buy currency.
`rate`	`Number`	exchange rate	Decimal.
`quoteId`	`String`	quote ID

result code

returnCode	errorMessage
`000000`	Success
`100000`	Input parameter is incorrect
`100006`	No rate
`100010`	account currency not enough
`100017`	customer product is not support
`120034`	RequestId is exists
`120035`	Fx info not match quote info
`120037`	The exchange amount is not within the limit
`9XXXXX`	System error (not fixed)

response body sample

{
  "returnCode": "000000",
  "errorMessage": "Success",
  "orderId": "646873e2-4d3f-486b-83af-e6a0bc6d464c",
  "acceptTime": "2024-01-08 14:38:17",
  "sellCurrency": "840",
  "sellAmount": "28.08",
  "buyCurrency": "157",
  "buyAmount": "200.99",
  "rate": "7.15711345",
  "quoteId": "ff36346e5c5c4562af194ba44165d759"
}

1
2
3
4
5
6
7
8
9
10
11
12

# SDK Sample

Java SDK

public void testFxCreate() {
    HttpClient<CallHttpResponse> httpClient = new TripLinkHttpClient();
    TripLinkBizImplV2 tripLinkCore = new TripLinkBizImplV2(CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY, AES_KEY, BASE_URL, httpClient);
    TripLinkApiImplV2 tripLinkApi = new TripLinkApiImplV2(tripLinkCore);

    FxCreateRequest request = new FxCreateRequest();
    request.setRequestId(String.valueOf(UUID.randomUUID()));
    request.setCustomerId("CSR2E54DC4B8A5D4");
    request.setSellCurrency("840");
    request.setBuyCurrency("344");
    request.setFxDirection(0);
    request.setFxAmount(new BigDecimal("100.03"));
    
    FxCreateResponse response = tripLinkApi.fxCreate(request);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

PHP SDK

public function testFxCreate(): void {
    $httpClient = new GuzzleHttpClient();
    $customer = new Customer(CUSTOMER_ID, AES_KEY, CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY);
    
    $tripLinkAgent = new SimpleTripLinkAgent(BASE_URL, $customer, $httpClient);
    $request = new FxCreateRequest(uniqid(), CUSTOMER_ID);
    $request->setSellCurrency('840');
    $request->setBuyCurrency('157');
    $request->setFxDirection(0);
    $request->setFxAmount(2.98);
    $request->setQuoteId('');
    
    $response = $tripLinkAgent->fxCreate($request);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# FX Query Order

# Request body

Name	Type	Required	Description	Comment
`requestId`	`String`	`Y`	request ID	Same as Request header.
`customerId`	`String`	`Y`	customer ID	Same as Request header.
`oriRequestId`	`String`	`N`	original initiate request ID	Either `oriRequestId` or `orderId` is required.
`orderId`	`String`	`N`	order ID	Either `oriRequestId` or `orderId` is required.

request body sample

{
  "requestId": "2024010800000001",
  "customerId": "CSR32384FAC033D4",
  "oriRequestId": "9032aee1-85aa-41e8-bc46-7ff8bb360976"
}

1
2
3
4
5

# Response body

Name	Type	Description	Comment
`returnCode`	`String`	result code	Enumerated type, `6` digits, see result code drop-down list. (code other than `000000` means request failed)
`errorMessage`	`String`	result code description	See result code drop-down list.
`orderId`	`String`	order ID	Globally unique.
`status`	`Number`	status	`0`: Processing, `1`: Success, `2`: Failure.
`acceptTime`	`String`	acceptance time	Format `yyyy-MM-dd HH:mm:ss`.
`sellCurrency`	`String`	sell currency	ISO 4217 currency code, `3` digits.
`sellAmount`	`Number`	sell amount	Decimal, matching sell currency.
`buyCurrency`	`String`	buy currency	ISO 4217 currency code, `3` digits.
`buyAmount`	`Number`	buy amount	Decimal, matching buy currency.
`rate`	`Number`	exchange rate	Decimal.
`quoteId`	`String`	quote ID

result code

returnCode	errorMessage
`000000`	Success
`100000`	Input parameter is incorrect
`120036`	Fx order not found
`9XXXXX`	System error (not fixed)

response body sample

{
  "returnCode": "000000",
  "errorMessage": "Success",
  "orderId": "f1f0dded-a130-4bc9-be08-0d9cc9072dc4",
  "status": 1,
  "acceptTime": "2024-01-08 14:39:31",
  "sellCurrency":"840",
  "sellAmount":200.99,
  "buyCurrency":"157",
  "buyAmount":1438.51,
  "rate":7.15711345,
  "quoteId":"94eae20cbbc54c7e89c502a653ce41bc"
}

1
2
3
4
5
6
7
8
9
10
11
12
13

# SDK Sample

Java SDK

public void testFxQuery() {
    HttpClient<CallHttpResponse> httpClient = new TripLinkHttpClient();
    TripLinkBizImplV2 tripLinkCore = new TripLinkBizImplV2(CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY, AES_KEY, BASE_URL, httpClient);
    TripLinkApiImplV2 tripLinkApi = new TripLinkApiImplV2(tripLinkCore);

    FxQueryRequest request = new FxQueryRequest();
    request.setRequestId(String.valueOf(UUID.randomUUID()));
    request.setCustomerId("CSR2E54DC4B8A5D4");
    request.setOriRequestId("testRequest1");
    
    FxQueryResponse response = tripLinkApi.fxQuery(request);
}

1
2
3
4
5
6
7
8
9
10
11
12

PHP SDK

public function testFxQuery(): void {
    $httpClient = new GuzzleHttpClient();
    $customer = new Customer(CUSTOMER_ID, AES_KEY, CUSTOMER_PRIVATE_KEY, TRIPLINK_PUBLIC_KEY);
    
    $tripLinkAgent = new SimpleTripLinkAgent(BASE_URL, $customer, $httpClient);
    $request = new FxQueryRequest(uniqid(), CUSTOMER_ID);
    $request->setOrderId('27f4b30b-3ddc-4736-8c9d-a35d3e73cae7');
    
    $response = $tripLinkAgent->fxQuery($request);
}

1
2
3
4
5
6
7
8
9
10

# Reporting Service

# Report Categories

TripLink provides customers with various dimensional reports. Each report type is located under the SFTP path /production/report/xxx (please contact the TripLink business team to confirm the exact path). Clients can select the desired type and frequency.

Name	Type	Frequency	Filename Format
Settlement Report	`SETTLEMENT_REPORT`	Daily Weekly Monthly	`ST001_2023-02-02.csv` `ST010_2023-02-06.csv` `ST100_2023-02-01.csv`
Cycle Settlement Report	`CYCLE_SETTLEMENT_REPORT`	Billing Cycle	`CST001_2023-02-01.csv`
Billing Report	`BILL_REPORT`	Billing Cycle	`SS001_2023-02-01.csv`
Authorization Report	`AUTHORIZATION_REPORT`	Daily	`VA001_2023-02-01.csv`
Card Issued Report	`CARD_ISSUED_REPORT`	Daily	`OV001_2023-02-01.csv`
Repayment Report	`REPAY_REPORT`	Daily	`VPMT001_2023-02-01.csv`
Dispute Report	`CHARGEBACK_REPORT`	Monthly	`NATC100_2023-02-01.csv`
VCC Charge Report	`VCC_CHARGE_REPORT`	Daily	`TUP001_2023-02-01.csv`
Authorization Fee Report	`AUTH_FEE_REPORT`	Daily	`AF001_2023-02-01.csv`
Funds Detail Report	`FUNDS_DETAIL_REPORT`	Daily	`FU001_2023-02-01.csv`
Exchange Report	`EXCHANGE_REPORT`	Daily	`RFX001_2023-02-01.csv`
Rebate Report	`REBATE_REPORT`	Monthly	`RB100_2023-02-01.csv`
Expense Detail Report	`EXPENSE_DETAIL_REPORT`	Monthly	`EX100_2023-02-01.csv`

# Report Trigger Methods

The customer actively initiates a report request under the Reporting Service menu in TripLink's client portal.
The system automatically initiates reports based on the customer's configured reporting settings.

# Report Delivery Methods

1.Portal Download: Reports generated from active customer requests in the TripLink client portal can be downloaded directly after generation.

2.Email Push: After generation, the report file is sent as an email attachment to the customer's configured recipient address. Note: Email delivery has a size limit (15MB). Files exceeding this size must use SFTP.

3.SFTP Push: Files are delivered to the customer's directory in the format: /production/report/[Report Type]/[Filename]. Example path for the customer has card issued report :/production/report/CARD_ISSUED_REPORT/OV001_2022-06-15.csv

# Report Header Descriptions

1. Settlement Report Header (Including Cycle Settlement Reports)

Header Field	Field Type	Field Description
`VANhistoryID`	`String`	Unique identifier for settlement records
`CardlogID`	`String`	Card record ID, encrypted card number
`ProductCode`	`String`	Card type, product code of the card
`TransID`	`String`	Card record number (short card number)
`ActivityType`	`String`	Transaction type, `Refund` - Refund, `Purchase` - Purchase, `Rebate` - Rebate, `Chargeback` - Chargeback, `ChargebackFee` - Chargeback fee
`IssuedToECN`	`String`	Customer number
`VAN`	`String`	Card number
`TransDate`	`String`	Posting date, prior to cut-off, format `yyyy-MM-dd`
`TransTime`	`String`	Posting time, settlement completion time, format `yyyy-MM-dd HH:mm:ss`
`TransCurr`	`String`	Posting currency, card posting currency, e.g., `USD`, `EUR`, `HKD`
`TransAmt`	`String`	Posting amount, card posting amount (transaction amount converted to card base currency)
`POSAmt`	`String`	Transaction amount
`POSCurr`	`String`	Transaction currency
`ReconciliationAmount`	`String`	Settlement amount
`ReconciliationCurrency`	`String`	Settlement currency
`RequestedDate`	`String`	Card issuance date, format `yyyy-MM-dd`
`RequestedTime`	`String`	Card issuance time, format `yyyy-MM-dd HH:mm:ss`
`LocalTime`	`String`	Transaction time (local transaction time), format `yyyy-MM-dd HH:mm:ss`
`AuthTime`	`String`	Authorization time
`MinAmt`	`String`	Minimum authorization amount for the card
`VANAmt`	`String`	Total issuance amount for the card
`MaxAmt`	`String`	Maximum authorization amount for the card
`ActivationDate`	`String`	Card activation date, format `yyyy-MM-dd`
`AuthAmt`	`String`	Authorization amount
`AuthCurr`	`String`	Authorization currency
`AuthCode`	`String`	Authorization code
`ValidUntil`	`String`	Card expiration date
`MerchID`	`String`	MID, Merchant ID
`MerchCategoryCode`	`String`	MCC, Merchant Category Code
`MerchCategoryName`	`String`	MCC Name, Merchant Category Name
`MerchName`	`String`	Merchant name
`MerchAddress`	`String`	Merchant address
`MerchCity`	`String`	Merchant city
`MerchState`	`String`	Merchant state
`MerchPostCode`	`String`	Merchant postal code
`MerchCountry`	`String`	Merchant country
`CrossBoardType`	`String`	Cross-border type, `international` - International, `domestic` - Domestic
`UserReference1`	`String`	Reserved field 1
`UserReference2`	`String`	Reserved field 2
`UserReference3`	`String`	Reserved field 3
`UserReference4`	`String`	Reserved field 4
`UserReference5`	`String`	Reserved field 5
`UserReference6`	`String`	Reserved field 6
`UserReference7`	`String`	Reserved field 7
`UserReference8`	`String`	Reserved field 8
`NatOrNot`	`String`	Whether it is a Nat transaction, `yes` - Yes, `no` - No
`OrderId`	`String`	Unique transaction ID, same as the OrderId in the authorization report

2. Authorization Report Header

Header Field	Field Type	Field Description
`CardlogID`	`String`	Card record ID, encrypted card number
`ProductCode`	`String`	Card type
`TransID`	`String`	Card record number (short card number)
`Status`	`String`	Card status
`IssuedToECN`	`String`	Customer number
`CardType`	`String`	Card type
`MerchantCategory`	`String`	Merchant category
`VAN`	`String`	Card number
`TransactionProfileCode`	`String`	Transaction code, `6810` - Purchase authorization, `6510` - Refund authorization, `6930` - Purchase authorization reversal, `6940` - Refund authorization reversal, `6820` - Authorization inquiry
`TransactionProfileType`	`String`	Transaction type, `Authorization (Purchase)` - Purchase authorization, `Authorization (Refund)` - Refund authorization, `Authorization Reversal (Purchase)` - Purchase authorization reversal, `Authorization Reversal (Refund)` - Refund authorization reversal, `Authorization Query` - Authorization inquiry
`RequestedTime`	`String`	Card issuance time, format `yyyy-MM-dd HH:mm:ss`
`ActivationDate`	`String`	Activatable date, format `yyyy-MM-dd`
`ExpiryDate`	`String`	Expiration date, format `yyyy-MM-dd`
`VANCurrency`	`String`	Card issuance currency
`MinAmt`	`String`	Minimum transaction amount
`MaxAmt`	`String`	Maximum transaction amount
`AvailableBalance`	`String`	Available balance
`AuthCount`	`String`	Number of authorizations
`VANMode`	`String`	Single-use/Multi-use card, `Singleuse` - Single-use card, `Multiuse` - Multi-use card
`VANhistoryID`	`String`	Authorization serial number
`AuthStatus`	`String`	Authorization status, `success` - Success, `failure` - Failure
`MsgType`	`String`	Message type
`AuthCode`	`String`	Authorization code
`TransTime`	`String`	UTC8 time, format `yyyy-MM-dd HH:mm:ss`
`POSCurr`	`String`	POS transaction currency
`POSAmt`	`String`	POS transaction amount
`MerchID`	`String`	MID
`MerchantName`	`String`	Merchant name
`MerchantCity`	`String`	Merchant city
`MerchantCountry`	`String`	Merchant country
`CrossBoardType`	`String`	Cross-border type, `international` - International, `domestic` - Domestic
`MerchCategoryCode`	`String`	MCC
`MerchCategoryName`	`String`	MCC Name
`UserReference1`	`String`	Reserved field 1
`UserReference2`	`String`	Reserved field 2
`UserReference3`	`String`	Reserved field 3
`UserReference4`	`String`	Reserved field 4
`UserReference5`	`String`	Reserved field 5
`UserReference6`	`String`	Reserved field 6
`UserReference7`	`String`	Reserved field 7
`UserReference8`	`String`	Reserved field 8
`Notes`	`String`	N/A, generally empty
`OrderId`	`String`	Transaction ID

3. Card Issued Report Header

Header Field	Field Type	Field Description
`VAN`	`String`	Card number
`CardlogID`	`String`	Encrypted card number
`ProductCode`	`String`	Card type
`TransID`	`String`	Card record number (short card number)
`RequestedDate`	`String`	Card application date, format `yyyy-MM-dd`
`RequestedTime`	`String`	Card application time, format `yyyy-MM-dd HH:mm:ss`
`VANCurrency`	`String`	Card issuance currency
`VANAmt`	`String`	Card issuance limit
`SettlementCurrency`	`String`	Settlement currency
`ActivationDate`	`String`	Activatable date, format `yyyy-MM-dd`
`ExpiryDate`	`String`	Expiration date, format `yyyy-MM-dd`
`VANMode`	`String`	Card mode, `Singleuse` - Single-use card, `Multiuse` - Multi-use card
`CloseRatio`	`String`	Close ratio percentage
`MinAuthAmt`	`String`	Minimum authorization amount
`MaxAuthAmt`	`String`	Maximum authorization amount
`BookingNumber`	`String`	Booking number
`UserName`	`String`	Card issuance user

4. Repayment Report Header

Header Field	Field Type	Field Description
`VANhistoryID`	`String`	Transaction detail ID
`IssuedToECN`	`String`	Customer ID
`Account`	`String`	Account type
`ActivityType`	`String`	Repayment
`PMTAmount`	`String`	Repayment amount
`PMTCurrency`	`String`	Repayment currency
`TransDate`	`String`	Repayment date
`TransTime`	`String`	Repayment time

5. Chargeback Report Header

Header Field	Field Type	Field Description
`ECN`	`String`	Customer ID
`TransID`	`String`	Card record number (short card number)
`CardlogID`	`String`	Card record ID
`ProductCode`	`String`	Card type
`NATID`	`String`	N/A, generally empty
`MerchantName/Location/MC`	`String`	MCC
`VAN`	`String`	Card number
`Amount`	`String`	Amount
`VANCurrency`	`String`	Card currency
`NetSettled`	`String`	Settlement amount
`SettlementCurrency`	`String`	Settlement currency
`PosAmount`	`String`	Transaction amount
`PosCurrency`	`String`	Transaction currency
`VANAvailableBalance`	`String`	Card balance
`VANIssuedDate`	`String`	Card issuance date, format `yyyy-MM-dd`
`1stPresentmentDate`	`String`	First presentment date, format `yyyy-MM-dd`
`ActionType`	`String`	Transaction type, `Chargeback in transit` - Chargeback in progress, `Small Balance advances` - Small balance advance, `Chargeback Release to Ctrip` - Chargeback release to TripLink, `Chargeback Release to BU` - Chargeback release to customer
`ActionDate`	`String`	Date, format `yyyy-MM-dd`
`TransTime`	`String`	Time, format `yyyy-MM-dd HH:mm:ss`
`ActionBy`	`String`	UID
`ChargebackReason`	`String`	N/A, generally empty
`Notes/Justification`	`String`	N/A, generally empty
`DocumentationFee`	`String`	N/A, generally empty
`MasterCardDocumentationFee`	`String`	N/A, generally empty
`MasterCardDocumentationFee`	`String`	N/A, generally empty

6. VCC Charge Report Header

Header Field	Field Type	Field Description
`Date`	`String`	Date, format `yyyy-MM-dd`
`ClientID`	`String`	Customer ID
`ClientName`	`String`	Customer name
`Top_up_Amount`	`String`	Recharge amount
`Top_up_Currency`	`String`	Recharge currency

7. Authorization Fee Report Header

Header Field	Field Type	Field Description
`Date`	`String`	Date, format `yyyy-MM-dd`
`ClientID`	`String`	Customer ID
`ClientName`	`String`	Customer name
`Auth_Fee`	`String`	Authorization fee
`Auth_Fee_Curr`	`String`	Authorization fee currency
`CardlogID`	`String`	Card ID
`ProductCode`	`String`	Product code
`TransID`	`String`	Transaction ID
`VAN`	`String`	Card number
`TransactionProfileCode`	`String`	Authorization code
`TransactionProfileType`	`String`	Authorization type
`AuthStatus`	`String`	Authorization status
`MsgType`	`String`	Message type
`AuthCode`	`String`	Authorization code
`TransTime`	`String`	Authorization time
`POSCurr`	`String`	Authorization currency
`POSAmt`	`String`	Authorization amount

8. Fund Details Report Header

Header Field	Field Type	Field Description
`Customer_id`	`String`	Customer ID
`Event_time`	`String`	Event time, format `yyyy-MM-dd HH:mm:ss`
`ActivityType`	`String`	Transaction type
`VANhistoryID`	`String`	Serial number, unique
`OrderID`	`String`	Transaction ID
`SettlementState`	`String`	Settlement status (Yes/No)
`TransactionCurrency`	`String`	Transaction currency
`TransactionAmount`	`String`	Transaction amount
`CardlogId`	`String`	Encrypted card number
`VAN`	`String`	Card number
`Currency`	`String`	Currency
`Amount`	`String`	Amount
`BeginBalanceAmount`	`String`	Beginning balance
`EndBalanceAmount`	`String`	Ending balance
`AuthCode`	`String`	Authorization code

9. Exchange Report Header

Header Field	Field Type	Field Description
`CustomerId`	`String`	Customer ID
`CardlogID`	`String`	Encrypted card number
`VAN`	`String`	Card number
`AuthCode`	`String`	Authorization code
`TransTime`	`String`	Authorization time, format `yyyy-MM-dd`
`POSCurr`	`String`	Authorization currency
`POSAmt`	`String`	Authorization amount
`QuotaId`	`String`	Exchange rate inquiry ID
`QuotaIdRate`	`String`	Exchange rate
`FXTime`	`String`	FX time, format `yyyy-MM-dd HH:mm:ss`
`BuyCurr`	`String`	Buy currency
`BuyAmt`	`String`	Buy amount
`SellCurr`	`String`	Sell currency
`SellAmt`	`String`	Sell amount
`Rate`	`String`	Exchange rate (actual transaction rate)

10. Rebate Report

Header Field	Field Type	Field Description
`CardlogID`	`String`	Encrypted card number
`orderid`	`String`	Order ID
`TransID`	`String`	Record ID
`ActivityType`	`String`	Transaction type
`VAN`	`String`	Card number
`TransDate`	`String`	Posting date, format `yyyy-MM-dd`
`TransTime`	`String`	Posting time, format `yyyy-MM-dd HH:mm:ss`
`ReconciliationCurrency`	`String`	Settlement currency
`ReconciliationAmount`	`String`	Settlement amount
`product_code`	`String`	Card type
`crossboard_type`	`String`	Cross-border type, `international` - International, `domestic` - Domestic
`commission_rate`	`String`	Rebate rate
`commission_mcc_group`	`String`	MCC group
`channel`	`String`	Channel
`MerchName`	`String`	Merchant name