NAV
Java

onerway V3.0 openAPI v1.0.0

Welcome to the onerway API Reference Guide.

Base URLs:

Signature

SHA256withRSA

Process

  1. Get private key(privateKey);
  2. ALGORITHM selects SHA256withRSA;
  3. Converts the information to be signed in UTF-8 format;
  4. Signs;
  5. Base64 transcoding.

Data to be signed

Remove all parameters with 'No' in the 'Signature' column and empty values, and sort the remaining parameters based on the ASCII code of the parameter names, and then concatenate the key and value in the way of key=value&key1=value1... (the last parameter does not need &).

For example


1. Private Key

MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQDHaM7clWWlJNS6ZR5ZkxSFeMMFt74YGRmYPr67UHrfc4CzFtN9sctIUqZJVv05sfOgnb0rk1G7wx97/LqxPEGs5chc+Nq9HkNf5VopMifOQ85j1Sv1U031oEGk+Oi4MTAR4ZWlLKBQPyKVb5pCP8aIv15GTIiIwJKS17zY5mQUrXzASTDk54DCG9eN4Lgka9xzwRvaYZvmxLg732GxjI5TE797kA5gxY7GxZ0wxdkWkhcee6xX6WWhAcmdHPUUS0EPcnL5wcc3wP07vO+R/jO1XoaXczb6JRh6ApR3Y5VjSFQApqwe7AIgASGf8aSkBU4K95RfZ3QsBjof2SX/3fkfAgMBAAECggEAf5F3NPqGSj3jsVLbNaa4LCLzcIb5n2T/ULxjPGXiFW1I2kkyB2lkiOIG60gxO2WyXABNcsEOOrY7QBCQRq4rvbZKld/F39Kqe4C4Sz6A5J3QPWG0e39NkmNxW165Uox1GhtcpoyECpI5R6xb3SH7mqQCZaq0dffsTPCjKYdKY0bvKPZrC+o8CqadySVzM6cRytvS+ZBjc03eT5MRHH6if1mIIxg8qPnOa2x7iXkq0UibFETqX+1gKZcQ3L9uIaH68t1UJEhjU7BB6YY76kMfZ/IH48iglXKlpcGMfOA7ST5Y81Si5ltsFuyuQ2BprUQ7zF/CDSHGfOA5v/q/tkZxoQKBgQD2by9lTP9JkZ8MvKJvAVpMS+f4zx8eDUFNM/2FA095en7xL5qyx/dXJMF+n4wSa421JcGqeYWN46+hFbnA+7Gv9r8GWDdb9sOKDhITVj9Qwl8KGQZRQJvtPnTygQE5w7GvS+NL/Rnp19iHZJ4IwAgdp2yD64uOFq0SB3x22d+qBwKBgQDPJlZBvgyuTL3z6YNhB3Skc9JDNs/EFSxP8q+hQn5ltsQeROwKot2I66xe0JoEWRpDrjWD9TpbqOg9rmDtPFG7d4matZCsg6hodSSwx7NyJxkI6JGg+ISLylc9LJz/uBmj5u69KDGBIcWIEnktxumuEipLOTSxyaRLDo2CdV7SKQKBgCkaZGpeDFqF+mRSdjlTnW8KXhem3EbT6SdqW4e7BJ97af7qdMALEFstm0R2chOEcu9a69F2UWtYJawVhpUEph92ZWg2gI1LPFQjgqpNAWSD9vwlLmORBjDs8O6dy8mJtXJKkw/SmGbjhI8Yni9RcEkZ6sSaHf3GFHnkW8MrFd4zAoGARFLwwF5e8F5/iKPMoYREBLnu8Bx0CsixBO2W4Cl+Zy4RIaq58Agn6bFR+TP0mNqKvygGnq+TwAfGEhIiBh2PF7YlvNGGFmCWe12n7Gbx2QTsTPPolJ9jmHf0rki4v9+JFXZl6B4Jtf3dmTP+pAqnqLJ1ILqNltZbSiZSpmTwEYECgYB/2Zv8JZ4poDugvvWY8N5e71ptVYljVcddm+BJ+uGgMUofPqoBvz1/hFnjX80CtqzOcxcg6KM+v71gt9qGbe2+483/Axmrwea50UKLqRVH3IXzTOEJth0betqTmbefYFLETn5RXB6MOJQOdzpvvcP305FmtT/grqqcnaeLbosT4A==


2. Data

{ "key":"value", "key2":"value2", "key1":"value2" }


3. Data to be signed

key=value&key1=value2&key2=value2


4. Sign

RcqXuiVp1JpwJedRGzTpL8M5mUsfeHL29gV9ycaJwmDoNV21AiaQ41au2qiJ8h+jKn/KBMcrJAzHGBTO3CZ0ffGxmqNz9fKhZX+X1MTntH+MhtKTyKR4ZF8kbAtezdVgPfqT69NPQGbWo57R3KP0m4W4n2ZjgkxkcG3yYtBdAgsyxDNoT8W0wH7nK7Y0zp88O8wIMe7kfBnK59J4y0Xz2EwiFX+bNkfRhf3U5WiHIU2TdRbaYsnzndmOkYkVdFAiUH7zoXnEn8ZVqiDZkK4eFG9H1LxU55dStug1hLtwxOKlu5OYFUi4iGAiq0Vlir01eDR1++KAudOdb1gcUyH2rA==

Code example


<dependency> <groupId>commons-codec</groupId> <artifactId>commons-codec</artifactId> <version>1.14</version> </dependency> 



package xxx;

import org.apache.commons.codec.binary.Base64;

import java.nio.charset.StandardCharsets;
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;


public class RSASecureDemo {

  /**
   * signRSA
   *
   * @param privateKey the private key
   * @param toBeSignedData  data to be signed
   * @return sign signature
   */
  public static String signRSA(String privateKey, String toBeSignedData) {
    try {
      byte[] keyBytes = Base64.decodeBase64(privateKey);
      PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(keyBytes);
      KeyFactory keyFactory = KeyFactory.getInstance("RSA");
      PrivateKey priKey = keyFactory.generatePrivate(pkcs8KeySpec);
      Signature signature = Signature.getInstance("SHA256withRSA");
      signature.initSign(priKey);
      signature.update(toBeSignedData.getBytes(StandardCharsets.UTF_8));
      return Base64.encodeBase64String(signature.sign());
    } catch (Exception e) {
      throw new RuntimeException("ras sign failed");
    }
  }


  public static void main(String[] args) {

    String privateKey =//"-----BEGIN PRIVATE KEY-----\n" +
      "MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQDHaM7clWWlJNS6\n" +
        "ZR5ZkxSFeMMFt74YGRmYPr67UHrfc4CzFtN9sctIUqZJVv05sfOgnb0rk1G7wx97\n" +
        "/LqxPEGs5chc+Nq9HkNf5VopMifOQ85j1Sv1U031oEGk+Oi4MTAR4ZWlLKBQPyKV\n" +
        "b5pCP8aIv15GTIiIwJKS17zY5mQUrXzASTDk54DCG9eN4Lgka9xzwRvaYZvmxLg7\n" +
        "32GxjI5TE797kA5gxY7GxZ0wxdkWkhcee6xX6WWhAcmdHPUUS0EPcnL5wcc3wP07\n" +
        "vO+R/jO1XoaXczb6JRh6ApR3Y5VjSFQApqwe7AIgASGf8aSkBU4K95RfZ3QsBjof\n" +
        "2SX/3fkfAgMBAAECggEAf5F3NPqGSj3jsVLbNaa4LCLzcIb5n2T/ULxjPGXiFW1I\n" +
        "2kkyB2lkiOIG60gxO2WyXABNcsEOOrY7QBCQRq4rvbZKld/F39Kqe4C4Sz6A5J3Q\n" +
        "PWG0e39NkmNxW165Uox1GhtcpoyECpI5R6xb3SH7mqQCZaq0dffsTPCjKYdKY0bv\n" +
        "KPZrC+o8CqadySVzM6cRytvS+ZBjc03eT5MRHH6if1mIIxg8qPnOa2x7iXkq0Uib\n" +
        "FETqX+1gKZcQ3L9uIaH68t1UJEhjU7BB6YY76kMfZ/IH48iglXKlpcGMfOA7ST5Y\n" +
        "81Si5ltsFuyuQ2BprUQ7zF/CDSHGfOA5v/q/tkZxoQKBgQD2by9lTP9JkZ8MvKJv\n" +
        "AVpMS+f4zx8eDUFNM/2FA095en7xL5qyx/dXJMF+n4wSa421JcGqeYWN46+hFbnA\n" +
        "+7Gv9r8GWDdb9sOKDhITVj9Qwl8KGQZRQJvtPnTygQE5w7GvS+NL/Rnp19iHZJ4I\n" +
        "wAgdp2yD64uOFq0SB3x22d+qBwKBgQDPJlZBvgyuTL3z6YNhB3Skc9JDNs/EFSxP\n" +
        "8q+hQn5ltsQeROwKot2I66xe0JoEWRpDrjWD9TpbqOg9rmDtPFG7d4matZCsg6ho\n" +
        "dSSwx7NyJxkI6JGg+ISLylc9LJz/uBmj5u69KDGBIcWIEnktxumuEipLOTSxyaRL\n" +
        "Do2CdV7SKQKBgCkaZGpeDFqF+mRSdjlTnW8KXhem3EbT6SdqW4e7BJ97af7qdMAL\n" +
        "EFstm0R2chOEcu9a69F2UWtYJawVhpUEph92ZWg2gI1LPFQjgqpNAWSD9vwlLmOR\n" +
        "BjDs8O6dy8mJtXJKkw/SmGbjhI8Yni9RcEkZ6sSaHf3GFHnkW8MrFd4zAoGARFLw\n" +
        "wF5e8F5/iKPMoYREBLnu8Bx0CsixBO2W4Cl+Zy4RIaq58Agn6bFR+TP0mNqKvygG\n" +
        "nq+TwAfGEhIiBh2PF7YlvNGGFmCWe12n7Gbx2QTsTPPolJ9jmHf0rki4v9+JFXZl\n" +
        "6B4Jtf3dmTP+pAqnqLJ1ILqNltZbSiZSpmTwEYECgYB/2Zv8JZ4poDugvvWY8N5e\n" +
        "71ptVYljVcddm+BJ+uGgMUofPqoBvz1/hFnjX80CtqzOcxcg6KM+v71gt9qGbe2+\n" +
        "483/Axmrwea50UKLqRVH3IXzTOEJth0betqTmbefYFLETn5RXB6MOJQOdzpvvcP3\n" +
        "05FmtT/grqqcnaeLbosT4A==\n"
      //  +"-----END PRIVATE KEY-----"
      ;

    String toBeSignedData = "key=value&key1=value2&key2=value2";
    String sign = signRSA(privateKey, toBeSignedData);
    System.out.println(sign);

  }

}

SHA256

Process

  1. Get the key;
  2. Concatenate the data string to be signed and the key string;
  3. Convert the above string in UTF-8 format;
  4. sha-256 digest;
  5. Convert byte to hexadecimal.

Data to be signed

Remove all parameters with 'No' in the 'Signature' column and empty values, and sort the remaining parameters based on the ASCII code of the parameter names, and then concatenate the values in the way of vaule1vaule2vaule3...;

For example


1. The Key

3b5e10b65bff4172a5b9ca2d2ec00a6e


2. Data

{ "merchantNo":"800135", "test":"dsaaass1dsag", "bizContent":"yesdas1dsa", "as":"12334567", "bc":"098754" }


3. Data to be signed

12334567098754yesdas1dsa800135dsaaass1dsag


4. Sign

0ce84cc90742e79b3af76da6b6909dc158a2e933057562639fe6a5a8e73f5350

Code example


<dependency> <groupId>org.apache.commons</groupId> <artifactId>commons-lang3</artifactId> <version>3.6</version> </dependency>



package xxx;

import org.apache.commons.lang3.StringUtils;

import java.security.MessageDigest;
import java.util.TreeMap;


public class SHA256SecureDemo {

  public static void main(String[] args) throws Exception{
    TreeMap data = new TreeMap();
    data.put("merchantNo","800135");
    data.put("test","yesdas1dsa");
    data.put("bizContent","dsaaass1dsag");
    data.put("as","12334567");
    data.put("bc","098754");

    String toBeSignedData =strcatValueSign(data);
    String key= "3b5e10b65bff4172a5b9ca2d2ec00a6e";
    String sign= signSha256(key,toBeSignedData);
    System.out.println(sign);

  }

  private static String strcatValueSign(TreeMap treeMap) {
    StringBuffer buffer = new StringBuffer();
    treeMap.forEach((k, v) -> {
      if (StringUtils.isNotBlank(v)) {
        buffer.append(v);
      }
    });
    return buffer.toString();
  }


  public static String signSha256(String key, String toBeSignedData){

    String str=toBeSignedData + key;
    MessageDigest messageDigest;
    String encodestr = "";
    try {
      messageDigest = MessageDigest.getInstance("SHA-256");
      messageDigest.update(str.getBytes("UTF-8"));
      encodestr = byte2Hex(messageDigest.digest());
    } catch (Exception e) {
      e.printStackTrace();
    }
    return encodestr;
  }

  /**
   * Convert byte to hexadecimal
   *
   * @param bytes
   * @return
   */
  private static String byte2Hex(byte[] bytes) {
    StringBuffer stringBuffer = new StringBuffer();
    String temp = null;
    for (int i = 0; i < bytes.length; i++) {
      temp = Integer.toHexString(bytes[i] & 0xFF);
      if (temp.length() == 1) {
        stringBuffer.append("0");
      }
      stringBuffer.append(temp);
    }
    return stringBuffer.toString();
  }

}

Signature Verification

SHA256withRSA

Process

  1. Get public key(publicKey);
  2. ALGORITHM selects SHA256withRSA;
  3. Converts the information to be signed in UTF-8 format;
  4. Signature string base64 decoded;
  5. Signature verification.

Data to be signed

Remove all parameters with 'No' in the 'Signature' column and empty values, and sort the remaining parameters based on the ASCII code of the parameter names, and then concatenate the key and value in the way of key=value&key1=value1... (the last parameter does not need &).

For example


1. Public Key

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAx2jO3JVlpSTUumUeWZMUhXjDBbe+GBkZmD6+u1B633OAsxbTfbHLSFKmSVb9ObHzoJ29K5NRu8Mfe/y6sTxBrOXIXPjavR5DX+VaKTInzkPOY9Ur9VNN9aBBpPjouDEwEeGVpSygUD8ilW+aQj/GiL9eRkyIiMCSkte82OZkFK18wEkw5OeAwhvXjeC4JGvcc8Eb2mGb5sS4O99hsYyOUxO/e5AOYMWOxsWdMMXZFpIXHnusV+lloQHJnRz1FEtBD3Jy+cHHN8D9O7zvkf4ztV6Gl3M2+iUYegKUd2OVY0hUAKasHuwCIAEhn/GkpAVOCveUX2d0LAY6H9kl/935HwIDAQAB


2. Data

{ "key":"value", "key2":"value2", "key1":"value2", "sign":"RcqXuiVp1JpwJedRGzTpL8M5mUsfeHL29gV9ycaJwmDoNV21AiaQ41au2qiJ8h+jKn/KBMcrJAzHGBTO3CZ0ffGxmqNz9fKhZX+X1MTntH+MhtKTyKR4ZF8kbAtezdVgPfqT69NPQGbWo57R3KP0m4W4n2ZjgkxkcG3yYtBdAgsyxDNoT8W0wH7nK7Y0zp88O8wIMe7kfBnK59J4y0Xz2EwiFX+bNkfRhf3U5WiHIU2TdRbaYsnzndmOkYkVdFAiUH7zoXnEn8ZVqiDZkK4eFG9H1LxU55dStug1hLtwxOKlu5OYFUi4iGAiq0Vlir01eDR1++KAudOdb1gcUyH2rA==" }


3. Data to be signed

key=value&key1=value2&key2=value2


4. Verify Result

true

Code example


<dependency> <groupId>commons-codec</groupId> <artifactId>commons-codec</artifactId> <version>1.14</version> </dependency> 



package xxx;

import org.apache.commons.codec.binary.Base64;

import java.nio.charset.StandardCharsets;
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;


public class RSASecureDemo {

  /**
   * verifyRSA
   *
   * @param publicKey the public key
   * @param toBeSignedData  data to be signed
   * @param sign   signature
   * @return
   */
  public static boolean verifyRSA(String publicKey, String toBeSignedData, String sign) {
    try {
      byte[] keyBytes = Base64.decodeBase64(publicKey);
      X509EncodedKeySpec keySpec = new X509EncodedKeySpec(keyBytes);
      KeyFactory keyFactory = KeyFactory.getInstance("RSA");
      PublicKey pubKey = keyFactory.generatePublic(keySpec);
      Signature signature = Signature.getInstance("SHA256withRSA");
      signature.initVerify(pubKey);
      signature.update(toBeSignedData.getBytes(StandardCharsets.UTF_8));
      return signature.verify(Base64.decodeBase64(sign));
    } catch (Exception e) {
      throw new RuntimeException("ras verify failed");
    }
  }


  public static void main(String[] args) {


    String publicKey = //"-----BEGIN PUBLIC KEY-----\n" +
      "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAx2jO3JVlpSTUumUeWZMU\n" +
        "hXjDBbe+GBkZmD6+u1B633OAsxbTfbHLSFKmSVb9ObHzoJ29K5NRu8Mfe/y6sTxB\n" +
        "rOXIXPjavR5DX+VaKTInzkPOY9Ur9VNN9aBBpPjouDEwEeGVpSygUD8ilW+aQj/G\n" +
        "iL9eRkyIiMCSkte82OZkFK18wEkw5OeAwhvXjeC4JGvcc8Eb2mGb5sS4O99hsYyO\n" +
        "UxO/e5AOYMWOxsWdMMXZFpIXHnusV+lloQHJnRz1FEtBD3Jy+cHHN8D9O7zvkf4z\n" +
        "tV6Gl3M2+iUYegKUd2OVY0hUAKasHuwCIAEhn/GkpAVOCveUX2d0LAY6H9kl/935\n" +
        "HwIDAQAB\n"
      //+ "-----END PUBLIC KEY-----"
      ;

    String toBeSignedData = "key=value&key1=value2&key2=value2";
    String sign = "RcqXuiVp1JpwJedRGzTpL8M5mUsfeHL29gV9ycaJwmDoNV21AiaQ41au2qiJ8h+jKn/KBMcrJAzHGBTO3CZ0ffGxmqNz9fKhZX+X1MTntH+MhtKTyKR4ZF8kbAtezdVgPfqT69NPQGbWo57R3KP0m4W4n2ZjgkxkcG3yYtBdAgsyxDNoT8W0wH7nK7Y0zp88O8wIMe7kfBnK59J4y0Xz2EwiFX+bNkfRhf3U5WiHIU2TdRbaYsnzndmOkYkVdFAiUH7zoXnEn8ZVqiDZkK4eFG9H1LxU55dStug1hLtwxOKlu5OYFUi4iGAiq0Vlir01eDR1++KAudOdb1gcUyH2rA==";
    boolean b = verifyRSA(publicKey, toBeSignedData, sign);
    System.out.println(b);

  }

}

SHA256

Process

  1. Get the key;
  2. Concatenate the data string to be signed and the key string;
  3. Convert the above string in UTF-8 format;
  4. sha-256 digest;
  5. Convert byte to hexadecimal;
  6. verify the signed.

Data to be signed

Remove all parameters with 'No' in the 'Signature' column and empty values, and sort the remaining parameters based on the ASCII code of the parameter names, and then concatenate the values in the way of vaule1vaule2vaule3...;

For example


1. The Key

3b5e10b65bff4172a5b9ca2d2ec00a6e


2. Data

{ "merchantNo":"800135", "test":"dsaaass1dsag", "bizContent":"yesdas1dsa", "as":"12334567", "bc":"098754", "sign":"0ce84cc90742e79b3af76da6b6909dc158a2e933057562639fe6a5a8e73f5350" }


3. Data to be signed

12334567098754yesdas1dsa800135dsaaass1dsag


4. Verify Result

true

Code example


<dependency> <groupId>org.apache.commons</groupId> <artifactId>commons-lang3</artifactId> <version>3.6</version> </dependency> 



package xxx;

import org.apache.commons.lang3.StringUtils;

import java.security.MessageDigest;
import java.util.TreeMap;


public class SHA256SecureDemo {

  public static void main(String[] args) throws Exception{
    TreeMap data = new TreeMap();
    data.put("merchantNo","800135");
    data.put("test","yesdas1dsa");
    data.put("bizContent","dsaaass1dsag");
    data.put("as","12334567");
    data.put("bc","098754");

    String toBeSignedData =strcatValueSign(data);
    String key= "3b5e10b65bff4172a5b9ca2d2ec00a6e";
    String sign= "0ce84cc90742e79b3af76da6b6909dc158a2e933057562639fe6a5a8e73f5350";
    boolean b = verifySha256(key, toBeSignedData, sign);
    System.out.println(b);

  }

  private static String strcatValueSign(TreeMap treeMap) {
    StringBuffer buffer = new StringBuffer();
    treeMap.forEach((k, v) -> {
      if (StringUtils.isNotBlank(v)) {
        buffer.append(v);
      }
    });
    return buffer.toString();
  }


  public static boolean verifySha256(String key, String toBeSignedData ,String sign){
    String sha256 = signSha256(key , toBeSignedData);
    return sha256.equals(sign);
  }



  public static String signSha256(String key, String toBeSignedData){

    String str=toBeSignedData + key;
    MessageDigest messageDigest;
    String encodestr = "";
    try {
      messageDigest = MessageDigest.getInstance("SHA-256");
      messageDigest.update(str.getBytes("UTF-8"));
      encodestr = byte2Hex(messageDigest.digest());
    } catch (Exception e) {
      e.printStackTrace();
    }
    return encodestr;
  }

  /**
   * Convert byte to hexadecimal
   *
   * @param bytes
   * @return
   */
  private static String byte2Hex(byte[] bytes) {
    StringBuffer stringBuffer = new StringBuffer();
    String temp = null;
    for (int i = 0; i < bytes.length; i++) {
      temp = Integer.toHexString(bytes[i] & 0xFF);
      if (temp.length() == 1) {
        stringBuffer.append("0");
      }
      stringBuffer.append(temp);
    }
    return stringBuffer.toString();
  }

}

JS Cashier

Instructions for JS-SDK

1. Import Js files


Method 1: Import a JS file to the page that needs to call the JS interface,Download link: https://v3-doc.pacypay.com/javascripts/pacypay-v1.0.5.zip
<script src="pacypay.js"></script>


Method 2: Import in the way of import / require import Pacypay from './pacypay.js' or const Pacypay = require('./pacypay.js')

2. Add a div element block with an id of pacypay_checkout to the desired page as a container embedded in the cashier


<div id='pacypay_checkout'></div>

3. Start calling the 'Submit Order' interface, and after success, use the transactionId returned by the interface and the following method to initialize the JS-SDK


new Pacypay(transactionId, options);

Code example
const transactionId = '1544197674849067008'; //current transaction id const pacypay = new Pacypay(transactionId, { locale: 'zh-cn', // en zh-cn ar de es fi fr it ja ko nl no pl pt ru sv th zh-tw environment: 'sandbox', // sandbox, production config: { subProductType: 'DIRECT', // DIRECT- direct payment, TOKEN- binding card and token payment (Must be consistent with the subProductType value in the submitting order interface) checkoutTheme: 'light', // light, dark customCssURL: '', // Custom style link address, after configuring this value, checkoutTheme is invalid variables: { "colorBackground": "black", // Theme background color "colorPrimary": "red", // Accent colors, such as input box highlighting, cursor color "colorText": "white", // Font color "colorDanger": "#FF1493", // Error message color "borderRadius": "2px", // Enter the box angle "fontSizeBase": "16px", // The base font size, which is scaled according to that baseline "fontFamily": "Arial, sans-serif", // Font style }, // If you want to customize all the styles, just configure 'styles'.No need to pass in 'checkoutTheme', 'customCssURL', 'variables'. // For details, please refer to the 'styles' property description styles: { ".pacypay-checkout__button--pay": { // Pay button style "background-color": "red", }, } }, onPaymentCompleted: function (res) { // Callback method after successful payment const txtInfo = res.data; // Return transaction result details const respCode = res.respCode; // Response code const respMsg = res.respMsg; // Response information if(respCode === '20000') { // respCode 为 20000 Indicates that the transaction is normal switch (txtInfo.status) { // Transaction status judgment case 'S': // status 'S' Indicates success // The final payment status is subject to the asynchronous notification result break; case 'R': // status 'R' Indicates that 3DS authentication is required // When the transaction status is 'R', the merchant needs to redirect to the URL to complete some transactions, including 3DS authentication window.location.href = txtInfo.redirectUrl; break; } } else { // Transaction failed } }, onError: function (err) { // Callback method after abnormal payment console.log(err); } });

Field Description

Attributes Type Required Description
transactionId string Yes The transaction ID obtained by the merchant through the interface
options object No See the following options description for details

options

Attributes Type Required Description
locale string No Language, Please refer to LanguageEnum
environment string No Environment type, for example 'sandbox'. The default is'production'
config object No Configuration items, see the following config description for details
onPaymentCompleted function No Request successful completion callback method
onError function No Request exception callback method

config

Attributes Type Required Description
checkoutTheme string No Theme type, 'light', 'dark'
customCssURL string No Supports custom styles for merchants, the custom style link address can be configured here; after configuration, the checkoutTheme value is invalid
variables object No Customize the accent color, See the variables description below
styles object No Custom styles, See the styles description below
showPayButton boolean No The default is true, if it is set to false, please see 4. Supplementary Instructions
buttonSeparation boolean No The default is ture, ture: the card binding and payment buttons are operated separately; False: One step completion of card binding and payment;
displayBillingInformation boolean No The default is ture, true: displays billing information; False: Hides billing information, which needs to be passed in through a custom payment button

variables

Attributes Type Required Description
colorBackground string No Theme background color
colorPrimary string No Accent colors, such as input box highlighting, cursor color
colorText string No Font color
colorDanger string No Error message color
borderRadius string No Enter the box angle
fontSizeBase string No The base font size, which is scaled according to that baseline
fontFamily string No Font style

styles

Attributes Type Required Description
.pacypay-checkout__payment-method object No Cashier payment method container
.pacypay-checkout_payment-method_header object No Title bar
.pacypay-checkout_payment-methodheader_title object No Title block name
.pacypay-checkout_payment-methodimage_wrapper object No Title bar picture container
.pacypay-checkout_payment-method_brands object No The bank card type container on the right side of the title bar
.pacypay-checkout_payment-method_image object No Title bar picture
.pacypay-checkout_payment-method_brand object No The picture of the bank card on the right side of the title bar
.pacypay-checkout_payment-method_name object No Title block title name
.pacypay-checkout_payment-method_details object No Form content container
.pacypay-checkout__field-wrapper object No Form item container
.pacypay-checkout__field object No The picture of the bank card on the right side of the title bar
.pacypay-checkout_payment-method_brand object No Form items
.pacypay-checkout__field--cardNumber object No Form item - card number
.pacypay-checkout__field--expire object No Form item - expiration time
.pacypay-checkout__field--cvv object No Form Item - CVV
.pacypay-checkout__field--lastName object No Form item -name
.pacypay-checkout__label-text object No Form item title
.pacypay-checkout__label-text--require object No Form item titles are required to identify
.pacypay-checkout__input object No Form item input box
.pacypay-checkout__error-text object No Form item error copy
.pacypay-checkout__button object No Button
.pacypay-checkout__button--pay object No Pay button
.pacypay-checkout_button_text object No Button text
.pacypay-checkout__loading object No Button Loading container
.pacypay-checkout__spinner object No Button Loading animation

4. Supplementary Instructions: When showPayButton is false, at the custom payment button, please call the following method to pay


pacypay.submit(); // If the billing information is not displayed when binding the card (displayBillingInformation: false), the billing parameters need to be passed in pacypay.submit({ billingInformation: { "firstName": "ZZ", "lastName": "ZZ", "phone": "188888888888", "email": "shipping@test.com", "postalCode": "888888", "address": "ShippingAddress", "country": "CN", "province": "SH", "city": "SH", "street": "lujiazui", "number": "1", "identityNumber": "110000" } });

5. The following are the payment synchronization response parameters, the merchant needs to process the payment result message (the final payment status is subject to the asynchronous notification)

Name Type Signed Description
respCode String No Response code sourced from Onerway
respMsg String No Response message sourced from Onerway
data Map No Response data. Please refer to TxnInfo json object

TxnInfo

Name Type Signed Description
transactionId String Yes The transaction order number created by Onerway,corresponding to the merchant order number
responseTime String Yes Interface response time, the format is yyyy-MM-dd HH:mm:ss
txnTime String Yes Transaction completion time, the format is yyyy-MM-dd HH:mm:ss
txnTimeZone String Yes Transaction completion time zone, for example: +08:00
orderAmount String Yes The amount of the transaction order
orderCurrency String Yes The currency of the transaction order. Please refer to ISO 4217 Currency Codes
txnAmount String Yes The transaction amount in settlement currency
txnCurrency String Yes The settlement currency. Please refer to ISO 4217 Currency Codes
status String Yes Transaction processing result. Please refer toTxnStatusEnum
redirectUrl String Yes when the transaction status is R, the merchant needs to redirect to this URL to complete part of the transaction, including 3ds verification, local payment cashier and so on
periodValue String No Number of installments
contractId String Yes Subscription contract id , returned when paying for the first subscription
tokenId String Yes Subscription token id , returned when paying for the first subscription
eci String Yes transfer of responsibility
sign String No Signature string.

Submit Order

POST /v1/sdkTxn/doTransaction

Example requests

{
"//": "Submit order for direct payment",
"merchantNo":"800035",
"merchantTxnId":"1654675447527",
"merchantTxnTime":null,
"merchantTxnTimeZone":null,
"productType":"CARD",
"subProductType":"DIRECT",
"txnType":"SALE",
"orderAmount":"22.1",
"orderCurrency":"USD",
"originTransactionId":null,
"risk3dsStrategy":null,
"txnOrderMsg":"{\"returnUrl\":\"https://www.ronhan.com/\",\"products\":\"[{\\\"name\\\":\\\"iphone 11\\\",\\\"price\\\":\\\"5300.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"CNY\\\"},{\\\"name\\\":\\\"macBook\\\",\\\"price\\\":\\\"1234.00\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"}]\",\"transactionIp\":\"127.0.0.1\",\"appId\":1451012088483221504,\"javaEnabled\":false,\"colorDepth\":\"24\",\"screenHeight\":\"1080\",\"screenWidth\":\"1920\",\"timeZoneOffset\":\"-480\",\"accept\":\"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\",\"contentLength\":\"340\",\"language\":null}",
"shippingInformation":"{\"firstName\":\"Shipping\",\"lastName\":\"Name\",\"phone\":\"188888888888\",\"email\":\"taoyun15@gmail.com\",\"postalCode\":\"888888\",\"address\":\"Shipping Address Test\",\"country\":\"CN\",\"province\":\"HB\",\"city\":\"WH\",\"street\":\"833 Cheung Sha Wan Road\",\"number\":\"1\",\"identityNumber\":\"82962612865\"}","billingInformation":"{\"firstName\":\"test\",\"lastName\":\"test\",\"phone\":\"18600000000\",\"email\":\"taoyun15@gmail.com\",\"postalCode\":\"430000\",\"address\":\"Unit 1113, 11/F, Tower 2, Cheung Sha Wan Plaza, 833 Cheung Sha Wan Road, Lai Chi Kok\",\"country\":\"CN\",\"province\":\"HB\",\"city\":\"HK\"}",
"sign":"..."
}


{
"//": "Submit order for token payment",
"merchantNo":"800035",
"merchantTxnId":"1654675447527",
"merchantTxnTime":null,
"merchantTxnTimeZone":null,
"merchantCustId":"custId_1640247522000",
"productType":"CARD",
"subProductType":"TOKEN",
"txnType":"SALE",
"orderAmount":"1.23",
"orderCurrency":"USD",
"originTransactionId":null,
"risk3dsStrategy":null,
"txnOrderMsg":"{\"returnUrl\":\"https://www.ronhan.com/\",\"products\":\"[{\\\"name\\\":\\\"iphone 11\\\",\\\"price\\\":\\\"5300.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"CNY\\\"},{\\\"name\\\":\\\"macBook\\\",\\\"price\\\":\\\"1234.00\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"}]\",\"transactionIp\":\"127.0.0.1\",\"appId\":1451012088483221504,\"javaEnabled\":false,\"colorDepth\":\"24\",\"screenHeight\":\"1080\",\"screenWidth\":\"1920\",\"timeZoneOffset\":\"-480\",\"accept\":\"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\",\"contentLength\":\"340\",\"language\":null}",
"shippingInformation":"{\"firstName\":\"Shipping\",\"lastName\":\"Name\",\"phone\":\"188888888888\",\"email\":\"taoyun15@gmail.com\",\"postalCode\":\"888888\",\"address\":\"Shipping Address Test\",\"country\":\"CN\",\"province\":\"HB\",\"city\":\"WH\",\"street\":\"833 Cheung Sha Wan Road\",\"number\":\"1\",\"identityNumber\":\"82962612865\"}","billingInformation":"{\"firstName\":\"test\",\"lastName\":\"test\",\"phone\":\"18600000000\",\"email\":\"taoyun15@gmail.com\",\"postalCode\":\"430000\",\"address\":\"Unit 1113, 11/F, Tower 2, Cheung Sha Wan Plaza, 833 Cheung Sha Wan Road, Lai Chi Kok\",\"country\":\"CN\",\"province\":\"HB\",\"city\":\"HK\"}",
"sign":"..."
}

Request parameters

Name Type Length Required Signed Description
merchantNo String 20 Yes Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
merchantTxnId String 64 Yes Yes Merchant transaction order number created by the merchant.Different order numbers are regarded as different transactions
merchantTxnTime String / No Yes The time when the merchant transaction order occurred. The format is yyyy-MM-dd HH:mm:ss
merchantTxnTimeZone String 64 No Yes The time zone when the merchant transaction order occurred. For example: +08:00
merchantTxnOriginalId String 128 No Yes Merchant's original order number. Mark the unique order number on the merchant website. Repeatable. The same order can only be paid successfully once
merchantCustId String 50 No Yes Merchant customer id, required when subProductType is TOKEN.
productType String 16 Yes Yes Product Type, Please refer to ProductTypeEnum
subProductType String 16 Yes Yes Sub product type, Please refer to SubProductTypeEnum
txnType String 16 Yes Yes Transaction type, Please refer to TxnTypeEnum
paymentMode String 16 No Yes Payment mode. Please refer to PaymentModeEnum. Default as WEB
osType String 16 No Yes Operating system type. Please refer to OsTypeEnum. Required when paymentMode is not WEB
orderAmount String 19 Yes Yes The amount of the transaction order
orderCurrency String 8 Yes Yes The currency of the transaction order. Please refer to ISO 4217 Currency Codes
originTransactionId String 20 No Yes The original transaction order number sourced from Onerway, often used for reverse transactions such as refunds, to find the corresponding forward transaction order number
risk3dsStrategy String 16 No Yes 3ds risk control strategy. Please refer toRisk3dsStrategyEnum
subscription String / No Yes Subscription information required for subscription payment. The format is json string. Please refer to Subscription object
mpiInfo String / No Yes Mpi information, 3ds verification result set, required when risk3dsStrategy is EXTERNAL. The format is json string. Please refer to MpiInfo object
txnOrderMsg String / No Yes Transaction business information, required except for subscription payment repurchase. The format is json string. Please refer to TxnOrderMsg object
billingInformation String / No Yes Transaction billing information, required except for subscription payment repurchase. The format is json string. Please refer to TransactionAddress object
shippingInformation String / No Yes Transaction mailing information, required except for subscription payment repurchase. The format is json string. Please refer to TransactionAddress object
lpmsInfo String / No Yes Local payment method information, required when product type is LPMS, The format is json string. Please refer to LpmsInfo object
sign String / Yes No Signature string.

TxnOrderMsg

Name Type Length Required Signed Description
returnUrl String 256 Yes No The URL of the merchant's side
products String 1024 Yes No Product information list. The format is json string. For example:[{"name":"iphone11","price":"5300.00","num":"2","currency":"CNY"}, {"name":"macBook","price":"1234.00","num":"1","currency":"USD","type":"discount"}],
the enumeration of the "type" field is as follows:
discount
shipping_fee
Not passing "type" means the product information itself
transactionIp String 64 Yes No The transaction IP of the cardholder
appId String 20 Yes No Merchant application id. When a merchant registers a website, Onerway will create an application id for the merchant
javaEnabled Boolean / Yes No The cardholder's browser enable java or not
colorDepth String 64 Yes No The cardholder's screen color depth
screenHeight String 64 Yes No The cardholder's screen resolution
screenWidth String 64 Yes No The cardholder's screen resolution
timeZoneOffset String 64 Yes No The time zone of the cardholder's browser
accept String 2048 Yes No The Accept request header of the cardholder's browser
userAgent String 2048 Yes No the cardholder's browser type
contentLength String 64 Yes No The content length other than content length header of the cardholder's browser
language String 64 Yes No The language of the cardholder's browser
periodValue String / No No Number of installments. Required when subProductType is INSTALLMENT.
notifyUrl String 256 No No Notification url. Please refer to Notification

TransactionAddress

Name Type Length Required Signed Description
firstName String 64 No No The first name
lastName String 64 No No The last name
jpFirstName String 64 No No The first name (Japanese Katakana)
jpLastName String 64 No No The last name (Japanese Katakana)
phone String 32 No No Phone number
email String 256 Yes No Email
postalCode String 32 No No Postal code
address String 256 No No address
country String 64 Yes No Country. Please refer to ISO. For example: the United States is US
province String 64 No No State. Required when the country is the United States (US) or Canada (CA). Please refer to ISO. For example: American Samoa is AS
city String 64 No No city
street String 64 No No street
number String 64 No No house number
identityNumber String 64 No No ID number
birthDate String 64 No No date of birth, the format is yyyy/MM/dd

Subscription

Name Type Length Required Signed Description
requestType String 1 Yes No Subscription request Type. The enum is as follows: 0 - first purchase 1 - repurchase
merchantCustId String 50 No No Merchant customer id, required when requestType is 0.
expireDate String 10 No No Expiration date, required when requestType is 0. The format is yyyy-MM-dd
frequencyType String 1 No No Subscription frequency type, required when requestType is 0. The enum is as follows: D - day
frequencyPoint String 2 No No Subscription frequency point, required when requestType is 0.
contractId String 20 No No Subscription contract id, required when requestType is 1.
tokenId String 300 No No Subscription token id, required when requestType is 1.

MpiInfo

Name Type Length Required Signed Description
eci String 2 Yes No transfer of responsibility
cavv String 128 Yes No Created by issuer
xid String 128 No No 3D-Secure v1 version Mpi transaction id (choose one of dsTransID to fill in)
dsTransID String 128 No No 3D-Secure v2 version Mpi transaction id (choose one of xid to fill in)

LpmsInfo

Name Type Length Required Signed Description
lpmsType String 64 Yes No Local payment method. Please refer to LpmsTypeEnum
bankName String 128 No No Bank name, required for some payment methods. Please refer to EFTBankNameEnum when lpmsType is EFT, and refer to Przelewy24BankNameEnum when lpmsType is Przelewy24.
iBan String 64 No No Bank account, required for transfer in some areas
prepaidNumber String / No No Prepaid card number, required for some local payment methods

Example responses

{
  "//": "Submit order for direct payment",
  "respCode":"20000",
  "respMsg":"Success",
  "data":{
    "transactionId":"1534446161027346432",
    "responseTime": "2022-07-08 11:22:31",
    "txnTimeZone": "+08:00",
    "status":"U",
    "sign":"..."
  }
}


{
  "//": "Submit order for token payment",
  "respCode":"20000",
  "respMsg":"Success",
  "data":{
    "transactionId":"163738134623746009",
    "responseTime": "2023-05-28 18:21:19",
    "txnTimeZone": "+08:00",
    "status":"U",
    "sign":"..."
  }
}

Response parameters

Name Type Signed Description
respCode String No Response code sourced from Onerway
respMsg String No Response message sourced from Onerway
data Map No Response data. Please refer to TxnInfo json object

TxnInfo

Name Type Signed Description
transactionId String Yes The transaction order number created by Onerway,corresponding to the merchant order number
responseTime String Yes Interface response time, the format is yyyy-MM-dd HH:mm:ss
txnTimeZone String Yes Transaction completion time zone, for example: +08:00
status String Yes Transaction processing result. Please refer toTxnStatusEnum
sign String No Signature string.

Update Order

Points for attention:
(1) If the field in 'TransactionAddress' does not need to be updated, it will not be passed. If 'null' or empty string is passed, it will also be updated.

POST /v1/sdkTxn/updateOrder

Example requests

{
"merchantNo":"800035",
"merchantTxnId":"1654675447527",
"transactionId":"1534446161027346432",
"orderAmount":"20",
"shippingInformation":"{\"firstName\":\"Shipping\",\"lastName\":\"Name\",\"phone\":\"188888888888\",\"email\":\"taoyun15@gmail.com\",\"postalCode\":\"888888\",\"address\":\"Shipping Address Test\",\"country\":\"CN\",\"province\":\"HB\",\"city\":\"WH\",\"street\":\"833 Cheung Sha Wan Road\",\"number\":\"1\",\"identityNumber\":\"82962612865\"}",
"billingInformation":"{\"firstName\":\"test\",\"lastName\":\"test\",\"phone\":\"18600000000\",\"email\":\"taoyun15@gmail.com\",\"postalCode\":\"430000\",\"address\":\"Unit 1113, 11/F, Tower 2, Cheung Sha Wan Plaza, 833 Cheung Sha Wan Road, Lai Chi Kok\",\"country\":\"CN\",\"province\":\"HB\",\"city\":\"HK\"}",
"sign":"..."
}

Request parameters

Name Type Length Required Signed Description
merchantNo String 20 Yes Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
merchantTxnId String 64 No Yes Merchant transaction order number created by the merchant.Different order numbers are regarded as different transactions. required at least one of transactionId and merchantTxnId
transactionId String 20 No Yes The transaction order number created by Onerway,corresponding to the merchant order number. required at least one of transactionId and merchantTxnId
orderAmount String 19 Yes Yes The transaction order amount that needs to be modified.
billingInformation String / No Yes Transaction billing information. The format is json string. Please refer to TransactionAddress object
shippingInformation String / No Yes Transaction mailing information. The format is json string. Please refer to TransactionAddress object
sign String / Yes No Signature string.

TransactionAddress

Name Type Length Required Signed Description
firstName String 64 No No The first name
lastName String 64 No No The last name
jpFirstName String 64 No No The first name (Japanese Katakana)
jpLastName String 64 No No The last name (Japanese Katakana)
phone String 32 No No Phone number
email String 256 No No Email
postalCode String 32 No No Postal code
address String 256 No No address
country String 64 No No Country. Please refer to ISO. For example: the United States is US
province String 64 No No State. Required when the country is the United States (US) or Canada (CA). Please refer to ISO. For example: American Samoa is AS
city String 64 No No city
street String 64 No No street
number String 64 No No house number
identityNumber String 64 No No ID number
birthDate String 64 No No date of birth, the format is yyyy/MM/dd

Example responses

{
  "respCode":"20000",
  "respMsg":"Success",
  "data":{
    "transactionId":"1534446161027346432",
    "sign":"..."
  }
}

Response parameters

Name Type Signed Description
respCode String No Response code sourced from Onerway
respMsg String No Response message sourced from Onerway
data Map No Response data. Please refer to TxnInfo json object

TxnInfo

Name Type Signed Description
transactionId String Yes The transaction order number created by Onerway,corresponding to the merchant order number
sign String No Signature string.

Cashier Payment

Cashier Payment

POST /txn/payment

Example requests

{
  "billingInformation":"{\"country\":\"US\",\"email\":\"test@qq.com\"}",
  "merchantNo":"800037",
  "merchantTxnId":"1654675447527",
  "merchantTxnTime":"2022-03-08 16:04:07",
  "merchantTxnTimeZone":"+08:00",
  "orderAmount":"35",
  "orderCurrency":"USD",
  "productType":"CARD",
  "cardInfo":"{\"holderName\":\"CL BRW2\"}",
  "shippingInformation":"{\"country\":\"US\",\"email\":\"test@qq.com\"}",
  "subProductType":"DIRECT",
  "txnOrderMsg":"{\"appId\":\"1458672763818790912\",\"returnUrl\":\"http://v1-demo.test.com/\",\"products\":\"[{\\\"price\\\":\\\"110.00\\\",\\\"num\\\":\\\"1\\\",\\\"name\\\":\\\"iphone11\\\",\\\"currency\\\":\\\"USD\\\"}]\"}",
  "txnType":"SALE",
  "sign":"..."
}

Request parameters

Name Type Length Required Signed Description
merchantNo String 20 Yes Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
merchantTxnId String 64 Yes Yes Merchant transaction order number created by the merchant.Different order numbers are regarded as different transactions
merchantTxnTime String / No Yes The time when the merchant transaction order occurred. The format is yyyy-MM-dd HH:mm:ss
merchantTxnTimeZone String 64 No Yes The time zone when the merchant transaction order occurred. For example: +08:00
merchantTxnOriginalId String 128 No Yes Merchant's original order number. Mark the unique order number on the merchant website. Repeatable. The same order can only be paid successfully once
productType String 16 Yes Yes Product Type, Please refer to ProductTypeEnum
subProductType String 16 Yes Yes Sub product type, Please refer to SubProductTypeEnum
txnType String 16 Yes Yes Transaction type, Please refer to TxnTypeEnum
orderAmount String 19 Yes Yes The amount of the transaction order
orderCurrency String 8 Yes Yes The currency of the transaction order. Please refer to ISO 4217 Currency Codes
subscription String / No Yes Subscription information required for subscription payment. The format is json string. Please refer to Subscription object
mpiInfo String / No Yes Mpi information, 3ds verification result set, required when risk3dsStrategy is EXTERNAL. The format is json string. Please refer to MpiInfo object
txnOrderMsg String / No Yes Transaction business information, required except for subscription payment repurchase. The format is json string. Please refer to TxnOrderMsg object
cardInfo String / No Yes Transaction card information of merchant's customer , The format is json string. Please refer to TxnCardInfo object
billingInformation String / No Yes Transaction billing information, required except for subscription payment repurchase. The format is json string. Please refer to TransactionAddress object
shippingInformation String / No Yes Transaction mailing information, required except for subscription payment repurchase. The format is json string. Please refer to TransactionAddress object
lpmsInfo String / No Yes Local payment method information, required when product type is LPMS, The format is json string. Please refer to LpmsInfo object
sign String / Yes No Signature string.

TxnOrderMsg

Name Type Length Required Signed Description
returnUrl String 256 Yes No The URL of the merchant's side
products String 1024 Yes No Product information list. The format is json string. For example:[{"name":"iphone11","price":"5300.00","num":"2","currency":"CNY"}, {"name":"macBook","price":"1234.00","num":"1","currency":"USD","type":"discount"}],
the enumeration of the "type" field is as follows:
discount
shipping_fee
Not passing "type" means the product information itself
appId String 20 Yes No Merchant application id. When a merchant registers a website, Onerway will create an application id for the merchant
notifyUrl String 256 No No Notification url. Please refer to Notification

TxnCardInfo

Name Type Length Required Signed Description
holderName String 64 No No The cardholder's Name

TransactionAddress

Name Type Length Required Signed Description
firstName String 64 No No The first name
lastName String 64 No No The last name
jpFirstName String 64 No No The first name (Japanese Katakana)
jpLastName String 64 No No The last name (Japanese Katakana)
phone String 32 No No Phone number
email String 256 Yes No Email
postalCode String 32 No No Postal code
address String 256 No No address
country String 64 Yes No Country. Please refer to ISO. For example: the United States is US
province String 64 No No State. Required when the country is the United States (US) or Canada (CA). Please refer to ISO. For example: American Samoa is AS
city String 64 No No city
street String 64 No No street
number String 64 No No house number
identityNumber String 64 No No ID number
birthDate String 64 No No date of birth, the format is yyyy/MM/dd

Subscription

Name Type Length Required Signed Description
requestType String 1 Yes No Subscription request Type. The enum is as follows: 0 - first purchase, Cashier only supports first purchase.
merchantCustId String 50 No No Merchant customer id, required when requestType is 0.
expireDate String 10 No No Expiration date, required when requestType is 0. The format is yyyy-MM-dd
frequencyType String 1 No No Subscription frequency type, required when requestType is 0. The enum is as follows: D - day
frequencyPoint String 2 No No Subscription frequency point, required when requestType is 0.

MpiInfo

Name Type Length Required Signed Description
eci String 2 Yes No transfer of responsibility
cavv String 128 Yes No Created by issuer
xid String 128 No No 3D-Secure v1 version Mpi transaction id (choose one of dsTransID to fill in)
dsTransID String 128 No No 3D-Secure v2 version Mpi transaction id (choose one of xid to fill in)

LpmsInfo

Name Type Length Required Signed Description
lpmsType String 64 Yes No Local payment method. Please refer to LpmsTypeEnum
bankName String 128 No No Bank name, required for some payment methods. Please refer to EFTBankNameEnum when lpmsType is EFT, and refer to Przelewy24BankNameEnum when lpmsType is Przelewy24.
iBan String 64 No No Bank account, required for transfer in some areas
prepaidNumber String / No No Prepaid card number, required for some local payment methods

Example responses

{
  "respCode":"20000",
  "respMsg":"Success",
  "data":{
    "transactionId":"1534446161027346432",
    "merchantTxnId":"1654675447527",
    "merchantNo":"800037",
    "responseTime":"",
    "txnTime":"",
    "orderAmount":"35.00",
    "orderCurrency":"USD",
    "txnAmount":"",
    "txnCurrency":null,
    "txnTimeZone":null,
    "status":"U",
    "reason":null,
    "redirectUrl":"https://test-v3-checkout.ronhan.com/checkout/67c32c03db894932a97c05f9d9068a64",
    "sign":"..."
  }
}

Response parameters

Name Type Signed Description
respCode String No Response code sourced from Onerway
respMsg String No Response message sourced from Onerway
data Map No Response data. Please refer to TxnInfo json object

TxnInfo

Name Type Signed Description
transactionId String Yes The transaction order number created by Onerway,corresponding to the merchant order number
merchantNo String Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
merchantTxnId String Yes Merchant transaction order number created by the merchant.Different order numbers are regarded as different transactions
responseTime String Yes Interface response time, the format is yyyy-MM-dd HH:mm:ss
txnTime String Yes Transaction completion time, the format is yyyy-MM-dd HH:mm:ss
txnTimeZone String Yes Transaction completion time zone, for example: +08:00
orderAmount String Yes The amount of the transaction order
orderCurrency String Yes The currency of the transaction order. Please refer to ISO 4217 Currency Codes
txnAmount String Yes The transaction amount in settlement currency
txnCurrency String Yes The settlement currency. Please refer to ISO 4217 Currency Codes
status String Yes Transaction processing result. Please refer toTxnStatusEnum
reason String Yes Reason for transaction failure
redirectUrl String Yes When the transaction status is U, the merchant needs to be redirected to this to open the cashier page(url needs to be decoded by URLDecoder)
sign String No Signature string.

API Payment

Consult Payment

POST /v1/txn/consultPaymentMethod

Example requests

{
  "//": "Consult the payment methods available for payment",
  "merchantNo": "800037",
  "appId":"1514185267394957312",
  "country":"PH",
  "orderAmount":"0.2",
  "orderCurrency":"USD",
  "sign": "..."
}


{
  "//": "Consult the payment methods available for auto debit",
  "merchantNo": "800058",
  "appId":"1496733359741014016",
  "country":"CN",
  "orderAmount":"0.2",
  "orderCurrency":"GBP",
  "subProductType":"AUTO_DEBIT",
  "sign": "..."
}

Request parameters

Name Type Length Required Signed Description
merchantNo String 20 Yes Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
appId String 20 Yes Yes Merchant application id. When a merchant registers a website, Onerway will create an application id for the merchant
country String 64 Yes Yes Country. Please refer to ISO. For example: the United States is US
subProductType String 16 No Yes Sub product type, Please refer to SubProductTypeEnum. Please transfer AUTO_DEBIT in auto debit, and other scenarios do not need to transfer values.
paymentMode String 16 No Yes Payment mode. Please refer to PaymentModeEnum. Default as WEB
osType String 16 No Yes Operating system type. Please refer to OsTypeEnum. Required when paymentMode is not WEB
orderAmount String 19 Yes Yes The amount of the transaction order
orderCurrency String 8 Yes Yes The currency of the transaction order. Please refer to ISO 4217 Currency Codes
sign String / Yes No Signature string.

Example responses

{
  "//": "Consult the payment methods available for payment",
  "respCode":"20000",
  "respMsg":"Success",
  "data":[
    {
      "productType":"CARD",
      "paymentMethod":"AE",
      "paymentMethodDetail":null
    },
    {
      "productType":"CARD",
      "paymentMethod":"MASTERCARD",
      "paymentMethodDetail":null
    },
    {
      "productType":"CARD",
      "paymentMethod":"VISA",
      "paymentMethodDetail":null
    },
    {
      "productType":"LPMS",
      "paymentMethod":"Alipay+",
      "paymentMethodDetail":{
        "paymentMethodName":"Alipay+",
        "logos":[
          {
            "logoName": "AlipayPlus",
            "logoUrl": "https://cdn.marmot-cloud.com/storage/aplus-checkout-prod/icon/prod/CONNECT_WALLET.png",
            "logoPattern": "default",
            "logoWidth": "810",
            "logoHeight": "190"
          }
        ],
        "promoNames": [
          "{\"en_US\":\"RM1 Voucher\", \"zh_CN\":\"1 元 红包\"}"
        ]
      }
    }
  ]
}


{
  "//": "Consult the payment methods available for auto debit",
  "respCode":"20000",
  "respMsg":"Success",
  "data":[
     {
         "productType": "LPMS",
         "paymentMethod": "Alipay+",
         "paymentMethodDetail": {
             "paymentMethodName": "Alipay+",
             "logos": [
                 {
                     "logoName": "Alipay+",
                     "logoUrl": "https://cdn.marmot-cloud.com/storage/aplus-checkout-prod/icon/prod/Z02TE0280000000A/5e0675cb5c70afa61b52998e0a7edce03a6e0417f3ae0722fab45cb81d12c4e8/P1-WEB-01-0614.png",
                     "logoPattern": "P1-WEB-01",
                     "logoWidth": "400",
                     "logoHeight": "48"
                 }
             ],
             "promoNames": [
                 "{\"en_US\":\"A+ Cashier Promotion Test\",\"fil_PH\":\"A+ Cashier Promotion Test\"}"
             ]
         }
     }
  ]
}

Response parameters

Name Type Signed Description
respCode String No Response code sourced from Onerway
respMsg String No Response message sourced from Onerway
data List No Response data. Please refer to PaymentMethod json object

PaymentMethod

Name Type Signed Description
productType String No Product Type, Please refer to ProductTypeEnum
paymentMethod String No The specific payment method, including card type and local payment type
paymentMethodDetail Map No Payment method details, Please refer to PaymentMethodDetail json object

PaymentMethodDetail

Name Type Signed Description
paymentMethodName String No Payment method brand name
logos List No Payment method logos information. Please refer to Logo json object
promoNames List No List of the promotion names. The key is the languages, such as en_US, while the value is the promotion name, such as RM1 Voucher. The format is json string.
Commonly used values of the languages include:
zh_CN: Simplified Chinese
zh_HK: Traditional Chinese
en_US: English
ko_KR: Korean
fil_PH: Filipino
ms_MY: Malay
id_ID: Indonesian
th_TH: Thai

Logo

Name Type Signed Description
logoName String No The logo name
logoUrl String No The logo URL
logoPattern String No The pattern of the logo. This parameter corresponds to the name of the logo that is specified by the merchant
logoWidth String No The width of the logo. Unit: px
logoHeight String No The height of the logo. Unit: px

Bind Card

POST /v1/txn/bindCard

Example requests

{
  "merchantNo":"800037",
  "appId":"1458672763818790912",
  "merchantCustId":"custId_1640247522000",
  "cardInfo":"{\"cardNumber\":\"4000027891380961\",\"cvv\":\"789\",\"month\":\"12\",\"year\":\"2022\",\"holderName\":\"CL BRW2\"}",
  "email":"shipping@test.com",
  "country":"US",
  "transactionIp":"127.0.0.1",
  "sign":"..."
}

Request parameters

Name Type Length Required Signed Description
merchantNo String 20 Yes Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
appId String 20 Yes Yes Merchant application id. When a merchant registers a website, Onerway will create an application id for the merchant
merchantCustId String 50 Yes Yes Merchant's customer id
cardInfo String / Yes Yes Transaction card information of merchant's customer , The format is json string. Please refer to TxnCardInfo object
email String 256 Yes Yes The email of merchant's customer
country String 64 Yes Yes The country of merchant's customer. Please refer to ISO. For example: the United States is US
transactionIp String 64 Yes Yes The transaction IP of merchant's customer
sign String / Yes No Signature string.

TxnCardInfo

Name Type Length Required Signed Description
holderName String 64 Yes No The cardholder's Name
cardNumber String 128 Yes No The cardholder's card number
month String 64 Yes No The month of card number, for example: 03
year String 64 Yes No The year of card number, for example: 2021
cvv String 64 Yes No The cvv of card number

Example responses

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1573856617225345201",
    "tokenId": "2a6f9b7720403a161860b6cc9e2121e3bf0e2c59bad870501e51233ce7f34f6a",
    "sign": "..."
  }
}

Response parameters

Name Type Signed Description
respCode String No Response code sourced from Onerway
respMsg String No Response message sourced from Onerway
data Map No Response data. Please refer to TokenInfo json object

TokenInfo

Name Type Signed Description
transactionId String Yes The transaction order number created by Onerway
tokenId String Yes Token id
sign String No Signature string.

API Payment

POST /v1/txn/doTransaction

Example requests

{
  "//": "Direct card payment",
  "merchantNo": "800037",
  "merchantTxnId": "1640229747000",
  "merchantTxnTime": "2021-12-22 15:30:30",
  "merchantTxnTimeZone": "+08:00",
  "productType": "CARD",
  "subProductType": "DIRECT",
  "txnType": "SALE",
  "orderAmount": "20",
  "orderCurrency": "USD",
  "txnOrderMsg": "{\"returnUrl\":\"https://www.ronhan.com/\",\"products\":\"[{\\\"price\\\":\\\"110.00\\\",\\\"num\\\":\\\"1\\\",\\\"name\\\":\\\"iphone11\\\",\\\"currency\\\":\\\"USD\\\"}]\",\"transactionIp\":\"127.0.0.1\",\"appId\":1458672763818790912,\"javaEnabled\":false,\"colorDepth\":\"24\",\"screenHeight\":\"1080\",\"screenWidth\":\"1920\",\"timeZoneOffset\":\"-480\",\"accept\":\"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\",\"contentLength\":\"340\",\"language\":\"zh-CN\"}",
  "cardInfo": "{\"cardNumber\":\"4000027891380961\",\"cvv\":\"789\",\"month\":\"12\",\"year\":\"2022\",\"holderName\":\"test sandbox\"}",
  "shippingInformation": "{\"firstName\":\"ShippingFirstName\",\"lastName\":\"ShippingLastName\",\"phone\":\"188888888888\",\"email\":\"shipping@test.com\",\"postalCode\":\"888888\",\"address\":\"ShippingAddress\",\"country\":\"CN\",\"province\":\"SH\",\"city\":\"SH\",\"street\":\"lujiazui\",\"number\":\"1\",\"identityNumber\":\"110000\"}",
  "billingInformation": "{\"firstName\":\"billingFirstName\",\"lastName\":\"billingLastName\",\"phone\":\"18600000000\",\"email\":\"billing@test.com\",\"postalCode\":\"430000\",\"address\":\"BillingAddress\",\"country\":\"CN\",\"province\":\"HK\",\"city\":\"HK\",\"street\":\"jianshazui\",\"number\":\"2\",\"identityNumber\":\"220000\"}",
  "sign": "..."
}


{
  "//": "Subscription first purchase",
  "merchantNo":"800037",
  "merchantTxnId":"1640247522000",
  "merchantTxnTime":"2021-12-22 15:30:30",
  "merchantTxnTimeZone":"+08:00",
  "productType":"CARD",
  "subProductType":"SUBSCRIBE",
  "txnType":"SALE",
  "orderAmount":"200",
  "orderCurrency":"USD",
  "txnOrderMsg":"{\"returnUrl\":\"https://www.ronhan.com/\",\"products\":\"[{\\\"price\\\":\\\"110.00\\\",\\\"num\\\":\\\"1\\\",\\\"name\\\":\\\"iphone11\\\",\\\"currency\\\":\\\"USD\\\"}]\",\"transactionIp\":\"127.0.0.1\",\"appId\":1458672763818790912,\"javaEnabled\":false,\"colorDepth\":\"24\",\"screenHeight\":\"1080\",\"screenWidth\":\"1920\",\"timeZoneOffset\":\"-480\",\"accept\":\"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\",\"contentLength\":\"340\",\"language\":\"zh-CN\"}",
  "cardInfo":"{\"cardNumber\":\"4000027891380961\",\"cvv\":\"789\",\"month\":\"12\",\"year\":\"2022\",\"holderName\":\"CL BRW2\"}",
  "shippingInformation":"{\"firstName\":\"ShippingFirstName\",\"lastName\":\"ShippingLastName\",\"phone\":\"188888888888\",\"email\":\"shipping@test.com\",\"postalCode\":\"888888\",\"address\":\"Shipping Address\",\"country\":\"CN\",\"province\":\"SH\",\"city\":\"SH\",\"street\":\"lujiazui\",\"number\":\"1\",\"identityNumber\":\"110000\"}",
  "billingInformation":"{\"firstName\":\"billingFirstName\",\"lastName\":\"billingLastName\",\"phone\":\"18600000000\",\"email\":\"billing@test.com\",\"postalCode\":\"430000\",\"address\":\"Billing Address\",\"country\":\"CN\",\"province\":\"HK\",\"city\":\"HK\",\"street\":\"jianshazui\",\"number\":\"2\",\"identityNumber\":\"220000\"}",
  "subscription":"{\"merchantCustId\":\"custId_1640247522000\",\"requestType\":\"0\",\"expireDate\":\"2022-11-11\",\"frequencyType\":\"D\",\"frequencyPoint\":1}",
  "sign":"..."
}


{
  "//": "Subscription repurchase",
  "merchantNo": "800037",
  "merchantTxnId": "1640323631000",
  "merchantTxnTime":"2021-12-22 15:30:30",
  "merchantTxnTimeZone":"+08:00",
  "productType":"CARD",
  "subProductType":"SUBSCRIBE",
  "txnType": "SALE",
  "orderAmount": "163",
  "orderCurrency": "USD",
  "txnOrderMsg":"{\"products\":\"[{\\\"price\\\":\\\"110.00\\\",\\\"num\\\":\\\"1\\\",\\\"name\\\":\\\"iphone11\\\",\\\"currency\\\":\\\"USD\\\"}]\"}",
  "cardInfo": null,
  "shippingInformation": null,
  "billingInformation":null,
  "subscription":"{\"requestType\":\"1\",\"tokenId\":\"2a6f9b7720403a161860b6cc9e2121e3bf0e2c59bad870501e51233ce7f34f6a\",\"contractId\":\"1473942457062490112\"}",
  "sign":"..."
}


{
  "//": "Local payment",
  "merchantNo": "800037",
  "merchantTxnId": "1646043155000",
  "merchantTxnTime":"2022-02-28 15:30:30",
  "merchantTxnTimeZone":"+08:00",
  "productType":"LPMS",
  "subProductType":"DIRECT",
  "txnType": "SALE",
  "orderAmount": "20",
  "orderCurrency":  "BRL",
  "txnOrderMsg": "{\"returnUrl\":\"https://www.ronhan.com/\",\"products\":\"[{\\\"name\\\":\\\"iphone 11\\\",\\\"price\\\":\\\"5300.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"CNY\\\"}]\",\"transactionIp\":\"2600:1700:f0f1:1e30:d08f:c6da:976c:45cd\",\"appId\":1493520562615545856}",
  "lpmsInfo":"{\"lpmsType\":\"Boleto\",\"bankName\":\"\",\"iban\":\"\"}",
  "shippingInformation":"{\"firstName\":\"da\",\"lastName\":\"xiong\",\"phone\":\"8522847000\",\"email\":\"shipping@example.com\",\"postalCode\":\"123456\",\"address\":\"HHHEEII\",\"country\":\"MY\",\"province\":\"BABA\",\"city\":\"BALALA\",\"street\":\"1010\",\"number\":\"20-1202\",\"identityNumber\":\"11112223333\",\"birthDate\":\"2020/12/28\"}",
  "billingInformation":"{\"firstName\":\"José\",\"lastName\":\"Silva\",\"phone\":\"8522847035\",\"email\":\"jose@example.com\",\"postalCode\":\"61919-230\",\"address\":\"Rua E\",\"country\":\"BR\",\"province\":\"CE\",\"city\":\"Maracanaú\",\"street\":\"1040\",\"identityNumber\":\"853.513.468-93\",\"birthDate\":\"2000/12/20\"}",
  "sign":"..."
}


{
  "//": "Local payment for Alipay+",
  "merchantNo": "800037",
  "merchantTxnId": "1648711802000",
  "merchantTxnTime":"2022-03-31 15:30:00",
  "merchantTxnTimeZone":"+08:00",
  "productType":"LPMS",
  "subProductType":"DIRECT",
  "txnType": "SALE",
  "orderAmount": "2",
  "orderCurrency":  "CNY",
  "txnOrderMsg": "{\"returnUrl\":\"https://www.ronhan.com/\",\"products\":\"[{\\\"name\\\":\\\"iphone 11\\\",\\\"price\\\":\\\"5300.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"CNY\\\"}]\",\"transactionIp\":\"127.0.0.1\",\"appId\":1509428893066776576}",
  "lpmsInfo":"{\"lpmsType\":\"Alipay+\",\"bankName\":\"\",\"iban\":\"\"}",
  "shippingInformation": "{\"email\":\"shipping@test.com\",\"country\":\"CN\"}",
  "billingInformation":  "{\"firstName\":\"José\",\"lastName\":\"Silva\",\"phone\":\"8522847035\",\"email\":\"customer@email\",\"country\":\"CN\"}",
  "sign":"..."
}


{
  "//": "token payment",
  "merchantNo":"800037",
  "merchantTxnId":"16402473654230",
  "merchantTxnTime":"2022-07-12 17:39:30",
  "merchantTxnTimeZone":"+08:00",
  "productType":"CARD",
  "subProductType":"TOKEN",
  "txnType":"SALE",
  "orderAmount":"200",
  "orderCurrency":"USD",
  "txnOrderMsg":"{\"returnUrl\":\"https://www.ronhan.com/\",\"products\":\"[{\\\"price\\\":\\\"110.00\\\",\\\"num\\\":\\\"1\\\",\\\"name\\\":\\\"iphone11\\\",\\\"currency\\\":\\\"USD\\\"}]\",\"transactionIp\":\"127.0.0.1\",\"appId\":1458672763818790912,\"javaEnabled\":false,\"colorDepth\":\"24\",\"screenHeight\":\"1080\",\"screenWidth\":\"1920\",\"timeZoneOffset\":\"-480\",\"accept\":\"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\",\"contentLength\":\"340\",\"language\":\"zh-CN\"}",
  "shippingInformation":"{\"firstName\":\"ShippingFirstName\",\"lastName\":\"ShippingLastName\",\"phone\":\"188888888888\",\"email\":\"shipping@test.com\",\"postalCode\":\"888888\",\"address\":\"Shipping Address\",\"country\":\"CN\",\"province\":\"SH\",\"city\":\"SH\",\"street\":\"lujiazui\",\"number\":\"1\",\"identityNumber\":\"110000\"}",
  "billingInformation":"{\"firstName\":\"billingFirstName\",\"lastName\":\"billingLastName\",\"phone\":\"18600000000\",\"email\":\"billing@test.com\",\"postalCode\":\"430000\",\"address\":\"Billing Address\",\"country\":\"CN\",\"province\":\"HK\",\"city\":\"HK\",\"street\":\"jianshazui\",\"number\":\"2\",\"identityNumber\":\"220000\"}",
  "tokenInfo":"{\"tokenId\":\"2a6f9b7720403a161860b6cc9e2121e3bf0e2c59bad870501e51233ce7f34f6a\"}",
  "sign":"..."  
}


{
  "//": "offline payment (user payment code)",
  "merchantNo":"800058",
  "merchantTxnId":"16402473654231",
  "merchantTxnTime":"2022-8-12 17:51:24",
  "merchantTxnTimeZone":"+08:00",
  "productType":"PAYMENT_CODE",
  "subProductType":"DIRECT",
  "txnType":"SALE",
  "orderAmount":"10.1",
  "orderCurrency":"CNY",
  "lpmsInfo":"{\"bankName\":\"banco_agrario\",\"lpmsType\":\"Alipay+\",\"iban\":\"02\",\"walletAccountId\":\"281666025563970651556390\"}",
  "risk3dsStrategy":"",
  "txnOrderMsg":"{\"terminalId\":\"122222\",\"returnUrl\":\"https://www.ronhan.com/\",\"products\":\"[{\\\"name\\\":\\\"iphone 11\\\",\\\"price\\\":\\\"5300.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"CNY\\\"},{\\\"name\\\":\\\"macBook\\\",\\\"price\\\":\\\"1234.00\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"}]\",\"transactionIp\":\"127.0.0.1\",\"appId\":1559440595840868352,\"javaEnabled\":false,\"colorDepth\":\"24\",\"screenHeight\":\"1080\",\"screenWidth\":\"1920\",\"timeZoneOffset\":\"-480\",\"accept\":\"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\",\"contentLength\":\"340\",\"language\":null}",
  "shippingInformation":"{\"firstName\":\"Shipping\",\"lastName\":\"Name\",\"phone\":\"188888888888\",\"email\":\"taoyun15@gmail.com\",\"postalCode\":\"888888\",\"address\":\"Shipping Address Test\",\"country\":\"CN\",\"province\":\"HB\",\"city\":\"WH\",\"street\":\"833 Cheung Sha Wan Road\",\"number\":\"1\",\"identityNumber\":\"82962612865\"}",
  "billingInformation":"{\"firstName\":\"test\",\"lastName\":\"test\",\"phone\":\"18600000000\",\"email\":\"taoyun15@gmail.com\",\"postalCode\":\"430000\",\"address\":\"Unit 1113, 11/F, Tower 2, Cheung Sha Wan Plaza, 833 Cheung Sha Wan Road, Lai Chi Kok\",\"country\":\"CN\",\"province\":\"HB\",\"city\":\"HK\"}",
  "sign":"..."
}

{
  "//": "offline payment (merchant order code)",
  "merchantNo":"800058",
  "merchantTxnId":"1665740062000",
  "merchantTxnTime":"2022-8-12 17:51:24",
  "merchantTxnTimeZone":"+08:00",
  "productType":"ORDER_CODE",
  "subProductType":"DIRECT",
  "txnType":"SALE",
  "orderAmount":"10.1",
  "orderCurrency":"CNY",
  "lpmsInfo":"{\"bankName\":\"banco_agrario\",\"lpmsType\":\"Alipay+\",\"iban\":\"02\"}",
  "originTransactionId":null,
  "risk3dsStrategy":"",
  "txnOrderMsg":"{\"terminalId\":null,\"returnUrl\":\"https://www.ronhan.com/\",\"products\":\"[{\\\"name\\\":\\\"iphone 11\\\",\\\"price\\\":\\\"5300.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"CNY\\\"},{\\\"name\\\":\\\"macBook\\\",\\\"price\\\":\\\"1234.00\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"}]\",\"transactionIp\":\"127.0.0.1\",\"appId\":1580023073311760384,\"javaEnabled\":false,\"colorDepth\":\"24\",\"screenHeight\":\"1080\",\"screenWidth\":\"1920\",\"timeZoneOffset\":\"-480\",\"accept\":\"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\",\"contentLength\":\"340\",\"language\":null}",
  "shippingInformation":"{\"firstName\":\"Shipping\",\"lastName\":\"Name\",\"phone\":\"188888888888\",\"email\":\"taoyun15@gmail.com\",\"postalCode\":\"888888\",\"address\":\"Shipping Address Test\",\"country\":\"CN\",\"province\":\"HB\",\"city\":\"WH\",\"street\":\"833 Cheung Sha Wan Road\",\"number\":\"1\",\"identityNumber\":\"82962612865\"}",
  "billingInformation":"{\"firstName\":\"test\",\"lastName\":\"test\",\"phone\":\"18600000000\",\"email\":\"taoyun15@gmail.com\",\"postalCode\":\"430000\",\"address\":\"Unit 1113, 11/F, Tower 2, Cheung Sha Wan Plaza, 833 Cheung Sha Wan Road, Lai Chi Kok\",\"country\":\"CN\",\"province\":\"HB\",\"city\":\"HK\"}",
  "sign":"..."
}

{
  "//": "auto debit",
  "merchantNo":"800058",
  "merchantTxnId":"1667979905000",
  "merchantTxnTime":"2022-11-09 08:01:01",
  "merchantTxnTimeZone":"+08:00",
  "productType":"LPMS",
  "subProductType":"AUTO_DEBIT",
  "txnType":"SALE",
  "orderAmount":"226.1",
  "orderCurrency":"CNY",
  "lpmsInfo":"{\"bankName\":\"banco_agrario\",\"lpmsType\":\"Alipay+\",\"iban\":\"02\"}",
  "tokenInfo":"{\"tokenId\":\"79c241bd655760470925222334f53e39a2a45720a5fc7ffa234a3e58ec020a2613d1de\"}",
  "originTransactionId":null,
  "risk3dsStrategy":"",
  "txnOrderMsg":"{\"returnUrl\":\"https://www.ronhan.com/\",\"products\":\"[{\\\"name\\\":\\\"iphone 11\\\",\\\"price\\\":\\\"5300.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"CNY\\\"},{\\\"name\\\":\\\"macBook\\\",\\\"price\\\":\\\"1234.00\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"}]\",\"transactionIp\":\"127.0.0.1\",\"appId\":1496733359741014016,\"javaEnabled\":false,\"colorDepth\":\"24\",\"screenHeight\":\"1080\",\"screenWidth\":\"1920\",\"timeZoneOffset\":\"-480\",\"accept\":\"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\",\"contentLength\":\"340\",\"language\":null}",
  "shippingInformation":"{\"firstName\":\"Shipping\",\"lastName\":\"Name\",\"phone\":\"188888888888\",\"email\":\"taoyun15@gmail.com\",\"postalCode\":\"888888\",\"address\":\"Shipping Address Test\",\"country\":\"CN\",\"province\":\"HB\",\"city\":\"WH\",\"street\":\"833 Cheung Sha Wan Road\",\"number\":\"1\",\"identityNumber\":\"82962612865\"}",
  "billingInformation":"{\"firstName\":\"test\",\"lastName\":\"test\",\"phone\":\"18600000000\",\"email\":\"taoyun15@gmail.com\",\"postalCode\":\"430000\",\"address\":\"Unit 1113, 11/F, Tower 2, Cheung Sha Wan Plaza, 833 Cheung Sha Wan Road, Lai Chi Kok\",\"country\":\"CN\",\"province\":\"HB\",\"city\":\"HK\"}",
  "sign":"..."
}

{
  "//": "Google Pay",
  "merchantNo": "800058",
  "merchantTxnId": "1684282754511",
  "merchantTxnTime": "2023-07-03 14:56:30",
  "merchantTxnTimeZone": "+08:00",
  "productType": "CARD",
  "subProductType": "DIRECT",
  "txnType": "SALE",
  "orderAmount": "33",
  "orderCurrency": "USD",
  "txnOrderMsg": "{\"returnUrl\":\"https://www.ronhan.com/\",\"products\":\"[{\\\"name\\\":\\\"iphone 11\\\",\\\"price\\\":\\\"5300.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"USD\\\"}]\",\"transactionIp\":\"2600:1700:f0f1:1e30:d08f:c6da:976c:45cd\",\"appId\":1598554105489707008}",
  "lpmsInfo": null,
  "tokenInfo":"{\"provider\":\"GooglePay\",\"tokenId\":\"{\\\"signature\\\":\\\"MEUCIFBHezjERp370abPVV1UnsUKifPIfqqkCDYbnqdQc5ZzAiEAul+0YgApwubbuOJiaOy7ac3h1xzfaIHqHRscxhuE93c\\\\u003d\\\",\\\"intermediateSigningKey\\\":{\\\"signedKey\\\":\\\"{\\\\\\\"keyValue\\\\\\\":\\\\\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEyrLXxj0lB4JwQOkzbX9nKMYmqKMCWUfRaz3oBt6QRQ3Qlp9L4XqBFwleeXDF4EAlmUOprm9cNfAWomCz9vbsA\\\\\\\\u003d\\\\\\\\u003d\\\\\\\",\\\\\\\"keyExpiration\\\\\\\":\\\\\\\"1689020235704\\\\\\\"}\\\",\\\"signatures\\\":[\\\"MEQCIEWC5iz28j+Hggk5CfkXpIstNCZee2xGbp85KeLlZjhpAiACu/AXvaBlXvaDnV6BoQV8bgXaRWOv0ugtFP5X3nz9AQ\\\\u003d\\\\u003d\\\"]},\\\"protocolVersion\\\":\\\"ECv2\\\",\\\"signedMessage\\\":\\\"{\\\\\\\"encryptedMessage\\\\\\\":\\\\\\\"6lmGzlYxIqYjJlhV7Y4pi6COa9r0kQpOw0Q1zIFWMMDMdCdVPJfudphfmZyLybHIb/g0ppWwX3vtvWzkGEI6NPNygwFJuc6ohGCjGoB8pSlu2TugMoXH2Jn28pT3jM2lbtQfSz4vTD/NrfNZ0XCI8vTVLYPVRwUpXKkXi5HT+UWeEwEuF4S5BCF5tzYJd/TJXa3pTsHx2+/D9/Pjbj69SWlrj1AnZ5aK1Nos1Fqi8U7eieHeTzEfCftUlUfB85hHdo64O53K+K2sST2F39V4LIxT7sbIvbSw9C8H8BgdcBxwYHImR5rj1eEPAtoxaQPmjC8v6Bqfl1d3xnvUyjDNcsB4gkGcAG09PrM9GshOogJnMhhlxrerT/eta1DL4Y0W9Cw8gM8MKxTxaQIJVxcdWplxAr7ot1j0k+IwjajkJ2x4mpajsLMrvMMN3wyCGgBUZymcZQQXjT3SVz50EiS5aAEe87JCWmBswuYovSSgFt33J4UBXwpdtcigI5tq8RUisJgwObKXBO8yaGFjvSADyeKAps94PvHh6on/JiDEMCITrMur7hDjSvwW/qhG5GcweayEmKk\\\\\\\\u003d\\\\\\\",\\\\\\\"ephemeralPublicKey\\\\\\\":\\\\\\\"BDWyUluGaiOcBzaS00h9RV1c3JlCPL00osk/GyA4F/fKca2zzcyv5eiedUn83j519pNVAsS14XwovAar7qNL+KY\\\\\\\\u003d\\\\\\\",\\\\\\\"tag\\\\\\\":\\\\\\\"KvOPUKi2fIJLDfhvpgyNUd6ppPuS1AGhvNYeXTKHNLQ\\\\\\\\u003d\\\\\\\"}\\\"}\"}",
  "shippingInformation":"{\"firstName\":\"José\",\"lastName\":\"Silva\",\"phone\":\"8522847035\",\"email\":\"zhongxing.feng@onerway.com\",\"postalCode\":\"93000\",\"address\":\"242, bab sebta\",\"country\":\"US\",\"province\":\"Tetu\",\"city\":\"Fqee eDg3\",\"street\":\"1040\",\"identityNumber\":\"853.513.468-93\",\"birthDate\":\"2000/12/20\"}",  
  "billingInformation":"{\"firstName\":\"José\",\"lastName\":\"Silva\",\"phone\":\"8522847035\",\"email\":\"zhongxing.feng@onerway.com\",\"postalCode\":\"93000\",\"address\":\"242, bab sebta\",\"country\":\"US\",\"province\":\"Tetu\",\"city\":\"Fqee eDg3\",\"street\":\"1040\",\"identityNumber\":\"853.513.468-93\",\"birthDate\":\"2000/12/20\"}",
  "sign":"..."
}

{
  "//": "Apple Pay",
  "merchantNo": "800037",
  "merchantTxnId": "1688966346884",
  "merchantTxnTime": "2023-07-10 13:19:06",
  "merchantTxnTimeZone": "+08:00",
  "orderAmount": "10",
  "orderCurrency": "USD",
  "productType": "CARD",
  "subProductType": "DIRECT",
  "txnType": "SALE",
  "shippingInformation": "{\"country\":\"US\",\"email\":\"qingxia.cai@pacypay.com\"}",
  "billingInformation": "{\"country\":\"US\",\"firstName\":\"wuyou\",\"lastName\":\"bi\",\"address\":\"833 Cheung Sha Wan Road\",\"province\":\"NY\",\"city\":\"NEW YORK CITY\",\"identityNumber\":\"123456789\",\"phone\":\"18301800000\",\"street\":\"1040\",\"postalCode\":\"10000\",\"email\":\"qingxia.cai@pacypay.com\"}",
  "tokenInfo": "{\"tokenId\":\"{\\\"paymentData\\\":{\\\"data\\\":\\\"PP82ornKbVQUWnxGmTn8McaTHi0A1o0sxJ9QkHWLLWAJJevRm7PWGjFeeFI/jqdqaqrw9fLFhPMLc6TxfrgqzdKjNFdKgmy36zbzNE3ZIrtlGE6DKMfLSBGr7P9UFFsFhHfVdWjogqflesSka3NdXG+mlpNH+TOW8mLz67i0OEwckS84yOxm3/0DGVVHjo26g8zSgG4iykIBCIlOb2cquwJU/Q+xb/l39X2w8M6D91nQlZ73029V9On2FWDheAOpsIgc4X/PM9zsPPhdZEx9lhADSU4KP1NgCy3kzxdh6RbX7kbLSdw7dppXfa9rHkpxPn2AHr9tFAEbeSf9dnn+7M1VGd/G/NjA5SGhMsvMrYI1JuHx+/iwjJ7NbTjGQ3jOwkNfwZN3/EKQf/Ih9Q\\u003d\\u003d\\\",\\\"signature\\\":\\\"MIAGCSqGSIb3DQEHAqCAMIACAQExDTALBglghkgBZQMEAgEwgAYJKoZIhvcNAQcBAACggDCCA+MwggOIoAMCAQICCEwwQUlRnVQ2MAoGCCqGSM49BAMCMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xOTA1MTgwMTMyNTdaFw0yNDA1MTYwMTMyNTdaMF8xJTAjBgNVBAMMHGVjYy1zbXAtYnJva2VyLXNpZ25fVUM0LVBST0QxFDASBgNVBAsMC2lPUyBTeXN0ZW1zMRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABMIVd+3r1seyIY9o3XCQoSGNx7C9bywoPYRgldlK9KVBG4NCDtgR80B+gzMfHFTD9+syINa61dTv9JKJiT58DxOjggIRMIICDTAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFCPyScRPk+TvJ+bE9ihsP6K7/S5LMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMB0GA1UdDgQWBBSUV9tv1XSBhomJdi9+V4UH55tYJDAOBgNVHQ8BAf8EBAMCB4AwDwYJKoZIhvdjZAYdBAIFADAKBggqhkjOPQQDAgNJADBGAiEAvglXH+ceHnNbVeWvrLTHL+tEXzAYUiLHJRACth69b1UCIQDRizUKXdbdbrF0YDWxHrLOh8+j5q9svYOAiQ3ILN2qYzCCAu4wggJ1oAMCAQICCEltL786mNqXMAoGCCqGSM49BAMCMGcxGzAZBgNVBAMMEkFwcGxlIFJvb3QgQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDUwNjIzNDYzMFoXDTI5MDUwNjIzNDYzMFowejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8BcRhBnXZIXVGl4lgQd26ICi7957rk3gjfxLk+EzVtVmWzWuItCXdg0iTnu6CP12F86Iy3a7ZnC+yOgphP9URaOB9zCB9DBGBggrBgEFBQcBAQQ6MDgwNgYIKwYBBQUHMAGGKmh0dHA6Ly9vY3NwLmFwcGxlLmNvbS9vY3NwMDQtYXBwbGVyb290Y2FnMzAdBgNVHQ4EFgQUI/JJxE+T5O8n5sT2KGw/orv9LkswDwYDVR0TAQH/BAUwAwEB/zAfBgNVHSMEGDAWgBS7sN6hWDOImqSKmd6+veuv2sskqzA3BgNVHR8EMDAuMCygKqAohiZodHRwOi8vY3JsLmFwcGxlLmNvbS9hcHBsZXJvb3RjYWczLmNybDAOBgNVHQ8BAf8EBAMCAQYwEAYKKoZIhvdjZAYCDgQCBQAwCgYIKoZIzj0EAwIDZwAwZAIwOs9yg1EWmbGG+zXDVspiv/QX7dkPdU2ijr7xnIFeQreJ+Jj3m1mfmNVBDY+d6cL+AjAyLdVEIbCjBXdsXfM4O5Bn/Rd8LCFtlk/GcmmCEm9U+Hp9G5nLmwmJIWEGmQ8Jkh0AADGCAYgwggGEAgEBMIGGMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUwIITDBBSVGdVDYwCwYJYIZIAWUDBAIBoIGTMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTIzMDYzMDA1MjAwM1owKAYJKoZIhvcNAQk0MRswGTALBglghkgBZQMEAgGhCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIPvB6yeEgFRF2yArO/2AQi9d88+xAqn8G0oQWXjpGnskMAoGCCqGSM49BAMCBEcwRQIgY0Ps1+7GWv5ZvfxHxKSkKO5t07oXYYk1KUH1/XtZ2d4CIQCgWkj/EQaoMKCIZ5o2TsHodRfrz4flayrJVl5R/E1VRQAAAAAAAA\\u003d\\u003d\\\",\\\"header\\\":{\\\"publicKeyHash\\\":\\\"+TkoHtf29uayv2/XFAWqpcfy9IS4t1IZXtXl+DFj8fU\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEbqL/gyIw2zksZ0OQlmaLuZJRyIPGPEPKUVTCvFTOaYzlpDHUFfI4zHBqp7M5zTbcDJG2NoppetIWqao9MeUC1w\\u003d\\u003d\\\",\\\"transactionId\\\":\\\"a7db8ba8d885861d026306e45390ec3b8806e2de0e9d049121befb93daae273a\\\"},\\\"version\\\":\\\"EC_v1\\\"},\\\"paymentMethod\\\":{\\\"displayName\\\":\\\"MasterCard 0839\\\",\\\"network\\\":\\\"MasterCard\\\",\\\"type\\\":\\\"credit\\\"},\\\"transactionIdentifier\\\":\\\"A7DB8BA8D885861D026306E45390EC3B8806E2DE0E9D049121BEFB93DAAE273A\\\"}\",\"provider\":\"ApplePay\"}",
  "txnOrderMsg": "{\"transactionIp\":\"127.0.0.1\",\"appId\":\"1674712864920072192\",\"userAgent\":\"Mozilla\",\"returnUrl\":\"http://www.pacypay.com/\",\"products\":\"[{\\\"price\\\":\\\"110.00\\\",\\\"num\\\":\\\"1\\\",\\\"name\\\":\\\"mac12\\\",\\\"currency\\\":\\\"USD\\\"}]\"}",
  "sign": "..."
}

Request parameters

Name Type Length Required Signed Description
merchantNo String 20 Yes Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
merchantTxnId String 64 Yes Yes Merchant transaction order number created by the merchant.Different order numbers are regarded as different transactions
merchantTxnTime String / No Yes The time when the merchant transaction order occurred. The format is yyyy-MM-dd HH:mm:ss
merchantTxnTimeZone String 64 No Yes The time zone when the merchant transaction order occurred. For example: +08:00
merchantTxnOriginalId String 128 No Yes Merchant's original order number. Mark the unique order number on the merchant website. Repeatable. The same order can only be paid successfully once
productType String 16 Yes Yes Product Type, Please refer to ProductTypeEnum
subProductType String 16 Yes Yes Sub product type, Please refer to SubProductTypeEnum
txnType String 16 Yes Yes Transaction type, Please refer to TxnTypeEnum
paymentMode String 16 No Yes Payment mode. Please refer to PaymentModeEnum. Default as WEB
osType String 16 No Yes Operating system type. Please refer to OsTypeEnum. Required when paymentMode is not WEB
orderAmount String 19 Yes Yes The amount of the transaction order
orderCurrency String 8 Yes Yes The currency of the transaction order. Please refer to ISO 4217 Currency Codes
originTransactionId String 20 No Yes The original transaction order number sourced from Onerway, often used for reverse transactions such as refunds, to find the corresponding forward transaction order number
risk3dsStrategy String 16 No Yes 3ds risk control strategy. Please refer toRisk3dsStrategyEnum
subscription String / No Yes Subscription information required for subscription payment. The format is json string. Please refer to Subscription object
mpiInfo String / No Yes Mpi information, 3ds verification result set, required when risk3dsStrategy is EXTERNAL. The format is json string. Please refer to MpiInfo object
txnOrderMsg String / No Yes Transaction business information, required except for subscription payment repurchase. The format is json string. Please refer to TxnOrderMsg object
cardInfo String / No Yes Transaction card information, required when product type is CARD and except for subscription payment repurchase, token payment, Google Pay and Apple Pay. The format is json string. Please refer to TxnCardInfo object
billingInformation String / No Yes Transaction billing information, required except for subscription payment repurchase. The format is json string. Please refer to TransactionAddress object
shippingInformation String / No Yes Transaction mailing information, required except for subscription payment repurchase. The format is json string. Please refer to TransactionAddress object
lpmsInfo String / No Yes Local payment method information, required when product type is LPMS and except for auto debit, The format is json string. Please refer to LpmsInfo object
tokenInfo String / No Yes Token information, required when subProductType is TOKEN or AUTO_DEBIT, format is json string. Please refer to TokenInfo object
sign String / Yes No Signature string.

TxnOrderMsg

Name Type Length Required Signed Description
returnUrl String 256 Yes No The URL of the merchant's side
products String 1024 Yes No Product information list. The format is json string. For example:[{"name":"iphone11","price":"5300.00","num":"2","currency":"CNY"}, {"name":"macBook","price":"1234.00","num":"1","currency":"USD","type":"discount"}],
the enumeration of the "type" field is as follows:
discount
shipping_fee
Not passing "type" means the product information itself
transactionIp String 64 Yes No The transaction IP of the cardholder
appId String 20 Yes No Merchant application id. When a merchant registers a website, Onerway will create an application id for the merchant
javaEnabled Boolean / Yes No The cardholder's browser enable java or not
colorDepth String 64 Yes No The cardholder's screen color depth
screenHeight String 64 Yes No The cardholder's screen resolution
screenWidth String 64 Yes No The cardholder's screen resolution
timeZoneOffset String 64 Yes No The time zone of the cardholder's browser
accept String 2048 Yes No The Accept request header of the cardholder's browser
userAgent String 2048 Yes No the cardholder's browser type
contentLength String 64 Yes No The content length other than content length header of the cardholder's browser
language String 64 Yes No The language of the cardholder's browser
periodValue String / No No Number of installments. Required when subProductType is INSTALLMENT.
terminalId String 64 No No The unique ID that is assigned by the merchant to identify a store terminal, required when productType is PAYMENT_CODE.
notifyUrl String 256 No No Notification url. Please refer to Notification

TxnCardInfo

Name Type Length Required Signed Description
holderName String 64 Yes No The cardholder's Name
cardNumber String 128 Yes No The cardholder's card number
month String 64 Yes No The month of card number, for example: 03
year String 64 Yes No The year of card number, for example: 2021
cvv String 64 Yes No The cvv of card number

TransactionAddress

Name Type Length Required Signed Description
firstName String 64 No No The first name
lastName String 64 No No The last name
jpFirstName String 64 No No The first name (Japanese Katakana)
jpLastName String 64 No No The last name (Japanese Katakana)
phone String 32 No No Phone number
email String 256 Yes No Email
postalCode String 32 No No Postal code
address String 256 No No address
country String 64 Yes No Country. Please refer to ISO. For example: the United States is US
province String 64 No No State. Required when the country is the United States (US) or Canada (CA). Please refer to ISO. For example: American Samoa is AS
city String 64 No No city
street String 64 No No street
number String 64 No No house number
identityNumber String 64 No No ID number
birthDate String 64 No No date of birth, the format is yyyy/MM/dd

Subscription

Name Type Length Required Signed Description
requestType String 1 Yes No Subscription request Type. The enum is as follows: 0 - first purchase 1 - repurchase
merchantCustId String 50 No No Merchant customer id, required when requestType is 0.
expireDate String 10 No No Expiration date, required when requestType is 0. The format is yyyy-MM-dd
frequencyType String 1 No No Subscription frequency type, required when requestType is 0. The enum is as follows: D - day
frequencyPoint String 2 No No Subscription frequency point, required when requestType is 0.
contractId String 20 No No Subscription contract id, required when requestType is 1.
tokenId String 300 No No Subscription token id, required when requestType is 1.

MpiInfo

Name Type Length Required Signed Description
eci String 2 Yes No transfer of responsibility. Please refer to EciEnum
cavv String 128 Yes No Created by issuer
xid String 128 No No 3D-Secure v1 version Mpi transaction id (choose one of dsTransID to fill in)
dsTransID String 128 No No 3D-Secure v2 version Mpi transaction id (choose one of xid to fill in)

LpmsInfo

Name Type Length Required Signed Description
lpmsType String 64 Yes No Local payment method. Please refer to LpmsTypeEnum
bankName String 128 No No Bank name, required for some payment methods. Please refer to EFTBankNameEnum when lpmsType is EFT, and refer to Przelewy24BankNameEnum when lpmsType is Przelewy24.
iBan String 64 No No Bank account, required for transfer in some areas
walletAccountId String 128 No No Wallet account id (payment code), required when productType is PAYMENT_CODE.
prepaidNumber String / No No Prepaid card number, required for some local payment methods

TokenInfo

Name Type Length Required Signed Description
tokenId String / No No Token id obtained by binding the payment methods. In Google Pay and Apple Pay scenarios, the provided token content needs to be converted into JSON format string
provider String / No No Token provider, when the value is blank, it defaults to Oneway and is generally used in token payment scenarios; For others, please refer to TokenProviderEnum

Example responses

{
  "//": "Direct card payment",
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1473856517125345280",
    "responseTime": "2021-12-23 11:22:31",
    "txnTime": "2021-12-23 11:22:31",
    "txnTimeZone": "+08:00",
    "orderAmount": "20.00",
    "orderCurrency": "USD",
    "txnAmount": "20.00",
    "txnCurrency": "USD",
    "status": "S",
    "redirectUrl": null,
    "periodValue": null,
    "contractId": null,
    "tokenId": null,
    "eci": null,
    "sign": "..."
  }
}


{
  "//": "Subscription first purchase",
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1473942456961826816",
    "responseTime": "2021-12-23 17:04:01",
    "txnTime": "2021-12-23 17:04:01",
    "txnTimeZone": "+08:00",
    "orderAmount": "200.00",
    "orderCurrency": "USD",
    "txnAmount": null,
    "txnCurrency": null,
    "status": "R",
    "redirectUrl": "https://sandbox-v3-gw-dmz.pacypay.com//3dsSecure/direct/3DS_1473942457892581377I",
    "contractId": "1473942457062490112",
    "tokenId": "2a6f9b7720403a161860b6cc9e2121e3bf0e2c59bad870501e51233ce7f34f6a",
    "eci": null,
    "sign": "..."
  }
}


{
  "//": "Subscription repurchase",
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1474250301443518464",
    "responseTime": "2021-12-24 13:27:17",
    "txnTime": "2021-12-24 13:27:17",
    "txnTimeZone": "+08:00",
    "orderAmount": "163.00",
    "orderCurrency": "USD",
    "txnAmount": "163.00",
    "txnCurrency": "USD",
    "status": "S",
    "redirectUrl": null,
    "contractId": "1473942457062490112",
    "tokenId": "2a6f9b7720403a161860b6cc9e2121e3bf0e2c59bad870501e51233ce7f34f6a",
    "eci": null,
    "sign": "..."
  }
}


{
  "//": "Local payment",
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1498239706186051584",
    "responseTime": "2022-02-28 18:12:37",
    "txnTime": "2022-02-28 18:12:36",
    "txnTimeZone": "+08:00",
    "orderAmount": "20.00",
    "orderCurrency": "BRL",
    "txnAmount": null,
    "txnCurrency": null,
    "status": "R",
    "redirectUrl": "https://sandbox.ebanxpay.com/print/?hash=621ca01414557c5009067504858cd223b90efca03add5c94",
    "contractId": null,
    "tokenId": null,
    "eci": null,
    "periodValue": null,
    "sign": "..."
  }
}


{
  "//": "Local payment for Alipay+",
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1509432822252380160",
    "responseTime": "2022-03-31 15:30:04",
    "txnTime": "2022-03-31 15:30:03",
    "txnTimeZone": "+08:00",
    "orderAmount": "2.00",
    "orderCurrency": "CNY",
    "txnAmount": null,
    "txnCurrency": null,
    "status": "R",
    "redirectUrl": "https://open-sea.alipayplus.com/api/open/v1/ac/cashier/self/codevalue/checkout.htm?charset=UTF-8&codeValue=281666040090cylL0chma8X6eA30FRz0bbed&loadMode=2",
    "contractId": null,
    "tokenId": null,
    "eci": null,
    "periodValue": null,
    "sign": "..."
  }
}


{
  "//": "token payment",
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1563942450861823816",
    "responseTime": "2022-07-12 17:39:32",
    "txnTime": "2022-07-12 17:39:31",
    "txnTimeZone": "+08:00",
    "orderAmount": "200.00",
    "orderCurrency": "USD",
    "txnAmount": null,
    "txnCurrency": null,
    "status": "R",
    "redirectUrl": "https://sandbox-v3-gw-dmz.pacypay.com//3dsSecure/direct/3DS_1563942450861823816",
    "contractId": null,
    "tokenId": "2a6f9b7720403a161860b6cc9e2121e3bf0e2c59bad870501e51233ce7f34f6a",
    "eci": null,
    "sign": "..."
  }    
}


{
  "//": "offline payment (user payment code)",
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
      "transactionId": "1559475985037299712",
      "responseTime": "2022-08-16 17:51:26",
      "txnTime": "2022-08-16 17:51:24",
      "txnTimeZone": "+08:00",
      "orderAmount": "10.10",
      "orderCurrency": "CNY",
      "txnAmount": "1.50",
      "txnCurrency": "USD",
      "status": "S",
      "redirectUrl": null,
      "contractId": null,
      "tokenId": null,
      "eci": null,
      "periodValue": null,
      "sign": "..."
  }
}

{
  "//": "offline payment (merchant order code)",
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
      "transactionId": "1580854573646868480",
      "responseTime": "2022-10-14 17:34:37",
      "txnTime": "2022-10-14 17:34:35",
      "txnTimeZone": "+08:00",
      "orderAmount": "10.10",
      "orderCurrency": "CNY",
      "txnAmount": null,
      "txnCurrency": null,
      "status": "R",
      "redirectUrl": null,
      "contractId": null,
      "tokenId": null,
      "eci": null,
      "periodValue": null,
      "codeForm": {
          "expireTime": "2022-10-14T17:37:36+08:00",
          "codeDetails": [
              {
                  "codeValueType": "QRCODE",
                  "codeValue": "2816660400948dlf6HZ7X9h8zc48ucQ0cyti",
                  "displayType": "TEXT"
              },
              {
                  "codeValueType": "QRCODE",
                  "codeValue": "https://qr.alipayplus.com/showQrImage?code=2816660400948dlf6HZ7X9h8zc48ucQ0cyti&picSize=L",
                  "displayType": "IMAGE"
              }
          ]
      },
      "sign": "..."
  }
}

{
  "//": "auto debit",
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
      "transactionId": "1590249160219205632",
      "responseTime": "2022-11-09 15:45:22",
      "txnTime": "2022-11-09 15:45:19",
      "txnTimeZone": "+08:00",
      "orderAmount": "226.10",
      "orderCurrency": "CNY",
      "txnAmount": "60.89",
      "txnCurrency": "USD",
      "status": "S",
      "redirectUrl": null,
      "contractId": null,
      "tokenId": "79c241bd655760470925222334f53e39a2a45720a5fc7ffa234a3e58ec020a2613d1de",
      "eci": null,
      "periodValue": null,
      "codeForm": null,
      "sign": "..."
  }
}

{
  "//": "Google Pay",
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
      "transactionId": "1675760413855604736",
      "responseTime": "2023-07-03 14:56:36",
      "txnTime": "2023-07-03 14:56:31",
      "txnTimeZone": "+08:00",
      "orderAmount": "33.00",
      "orderCurrency": "USD",
      "txnAmount": "33.00",
      "txnCurrency": "USD",
      "status": "S",
      "redirectUrl": null,
      "contractId": null,
      "tokenId": null,
      "eci": null,
      "periodValue": null,
      "codeForm": null,
      "presentContext": null,
      "redirectType": null,
      "sign": "..."
    }
}

{
    "//": "Apple Pay",
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
      "transactionId": "1678272678211248128",
      "responseTime": "2023-07-10 13:19:26",
      "txnTime": "2023-07-10 13:19:21",
      "txnTimeZone": "+08:00",
      "orderAmount": "10.00",
      "orderCurrency": "USD",
      "txnAmount": "10.00",
      "txnCurrency": "USD",
      "status": "S",
      "redirectUrl": null,
      "contractId": null,
      "tokenId": null,
      "eci": null,
      "periodValue": null,
      "codeForm": null,
      "presentContext": null,
      "redirectType": null,
      "sign": "..."
    }
}

Response parameters

Name Type Signed Description
respCode String No Response code sourced from Onerway
respMsg String No Response message sourced from Onerway
data Map No Response data. Please refer to TxnInfo json object

TxnInfo

Name Type Signed Description
transactionId String Yes The transaction order number created by Onerway,corresponding to the merchant order number
responseTime String Yes Interface response time, the format is yyyy-MM-dd HH:mm:ss
txnTime String Yes Transaction completion time, the format is yyyy-MM-dd HH:mm:ss
txnTimeZone String Yes Transaction completion time zone, for example: +08:00
orderAmount String Yes The amount of the transaction order
orderCurrency String Yes The currency of the transaction order. Please refer to ISO 4217 Currency Codes
txnAmount String Yes The transaction amount in settlement currency
txnCurrency String Yes The settlement currency. Please refer to ISO 4217 Currency Codes
status String Yes Transaction processing result. Please refer toTxnStatusEnum
redirectUrl String Yes when the transaction status is R, the merchant needs to redirect to this URL to complete part of the transaction, including 3ds verification, local payment cashier and so on
periodValue String No Number of installments
contractId String Yes Subscription contract id , returned when paying for the first subscription
tokenId String Yes Subscription token id , returned when paying for the first subscription
eci String Yes Transfer of responsibility
codeForm Map No Code info. Please refer to CodeForm json object
sign String No Signature string.

CodeForm

Name Type Signed Description
expireTime String No The expiration time of the order code. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
codeDetails List No The details about the order code. Please refer to CodeDetail json object

CodeDetail

Name Type Signed Description
codeValueType String No The type of the code.
BARCODE: indicates a barcode
QRCODE: indicates a QR code
codeValue String No The value of the code.
displayType String No Indicates how to display the code on the UI.
TEXT: indicates that the code can be directly displayed on the UI as text or a label.
IMAGE: indicates that the code can be directly displayed on the UI as a image.

Google Pay


With Google Pay, consumer can use their already stored credit or debit cards to make payments on shopping websites. Consumer get a simpler and secure payment experience.

Google Pay Integration
You can choose the right way to access Google Pay according to your situation.

Preparation before access

Before you start technology integration, you need to support the following Google Pay constraints:

1. Range of cards supported by Google Pay

ONERWAY supports Google Pay with VISA and Mastercard.

2. Scope of support:

(1) List of countries where you can use Google Pay ;
(2) List of supported browsers ;

ONERWAY Payment Page


All the content related to Google Pay has been integrated in the ONERWAY checkout page, you only need to call the Cashier Payment API, upload the fields as required, and subsequent transactions are completed by ONERWAY.

The information displayed at the ONERWAY checkout page is as follows:


API Payment Integrations

In this model, merchants need to integrate Google Pay's JS and related logic judgment, and then send the generated token to ONERWAY, and then ONERWAY completes the subsequent payment.

1. Follow the official Google Pay guidelines to complete the following steps:

(1) Request production access

2. Connect to JS, refer to Demo.

(1) Add Google Pay API Javascript library on web pages <script async src="https://pay.google.com/gp/p/js/pay.js" onload="console.log('TODO: add onload function')"> </script>
(2) Specify Google Pay API version const baseRequest = { apiVersion: 2, apiVersionMinor: 0 }
(3) Apply for a payment token for your PSP const tokenizationSpecification = { type: 'PAYMENT_GATEWAY', parameters: { 'gateway': 'ronghan', // regardless of the testing or production environment, this field needs to be assigned a value of 'ronghan' 'gatewayMerchantId': 'exampleGatewayMerchantId' // test environment, this field needs to be assigned a value of "800096", while production environment is provided by Ronghan } };
(4) Specify supported payment card networks
Specify the payment card network that your website accepts const allowedCardNetworks = ['MASTERCARD', 'VISA'];
Google Pay Api may return payment cards (PAN_ONLY) recorded by Google and/or device tokens (CRYPTOGRAM_3DS) authenticated with 3D secure ciphertext on Android devices const allowedCardAuthMethods = ['PAN_ONLY', 'CRYPTOGRAM_3DS']
(5) Specify the payment methods you allow const baseCardPaymentMethod = { type: 'CARD', parameters: { allowedAuthMethods: allowedCardAuthMethods, allowedCardNetworks: allowedCardNetworks, }, };
(6) After successfully loading the Google Pay API Javascript library, initialize the PaymentsClient object
Note: We recommend that you initialize paymentsClient only once and use a unified instance when calling other APIs such as CreateButton, IsReadyToPay, PrefetchPaymentData, and LoadPaymentData // the initial development can use the TEST environment, but the payment method selected in the TEST environment cannot be used for transactions. The formal environment uses the Production environment const paymentsClient = new google.payments.api.PaymentsClient({environment: 'TEST'});
(7) Determine if Google Pay API can be used for payment
Add the payment method you allow to the request object for the amount const isReadyToPayRequest = Object.assign({}, baseRequest, { allowedPaymentMethods: [baseCardPaymentMethod], }, );
Call isReadyToPay() to determine if the current device and/or browser supports the Google Pay API paymentsClient.isReadyToPay(isReadyToPayRequest) .then((response) => { if (response.result) { // add Google Pay payment button } }) .catch((err) => { // show error in developer console for debugging console.error('isReadyToPay', err); });
(8) Add Google Pay payment button const button = paymentsClient.createButton({ onClick: onGooglePaymentButtonClicked, // click on Google Pay payment button callback function allowedPaymentMethods: [baseCardPaymentMethod], buttonSizeMode: 'fill', // button size buttonLocale: 'en', // language }); document.querySelector('.container').appendChild(button);
(9) Create a PaymentDataRequest object const cardPaymentMethod = Object.assign({}, baseCardPaymentMethod, { tokenizationSpecification: tokenizationSpecification }); const paymentDataRequest Object.assign({}, baseRequest) paymentDataRequest.allowedPaymentMethods = [cardPaymentMethod]; paymentDataRequest.transactionInfo = { countryCode: 'US', currencyCode: 'USD', totalPriceStatus: 'FINAL', totalPrice: '1.00' } paymentDataRequest.merchantInfo = { merchantId: 'merchantId,' // provided by Ronghan merchantName: 'Merchant name', // merchant name encoded as UTF-8 merchantOrigin: 'merchantOrigin', // the fully qualified domain of the requesting merchant }
(10) Register a time handler for user gestures (call loadPaymentData() immediately after clicking the purchase button) const onGooglePaymentButtonClicked = () => { paymentsClient.loadPaymentData(paymentDataRequest) .then((paymentData) => { // if using gateway tokenization, pass this token without modification paymentToken = paymentData.paymentMethodData.tokenizationData.token; // request payment using token }) .catch((err) => { // show error in developer console for debugging console.error('loadPaymentData', err); }); }
(11) For more information, please refer to Google Pay official website documentation

3. For Test cards used in Google Pay, please refer to Google Pay Test Card Suite ;

4. After the completion of the previous three steps, get the token of Google Pay, please send this field together with other fields to ONERWAY through the API Payment, and then ONERWAY completes the payment and returns the payment result;

Apple Pay


With Apple Pay, consumer can use their already stored credit or debit cards to make payments on shopping websites. Consumer get a simpler and secure payment experience.

Apple Pay Integration
You can choose the right way to access Apple Pay according to your situation.

Preparation before access

Before you start technology integration, you need to support the following Apple Pay constraints:

1. Range of cards supported by Apple Pay:

ONERWAY supports Apple Pay with VISA and Mastercard

2. Scope of support:

(1) List of countries where you can use Apple Pay ;
(2) List of supported Issuers ;
(3) List of supported browsers ;

3. Requirements of the merchant website:

(1) Submitted domains must have a valid SSL certificate;
(2) Submitted domains must be HTTPS, and the domain server supports TLS 1.2 or higher;
(3) Submitted domains must meet Apple Pay communication security requirements ;

ONERWAY Payment Page


All content related to Apple Pay has been integrated in the ONERWAY cashier, and you only need to do a little work to use Apple Pay.
(1) Obtain the apple app site association file from ONERWAY and place it in the specified directory of your current shopping website. The directory path is: https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association;
(2) Call the Cashier Payment API, upload the fields as required, and all subsequent transactions will be completed by ONERWAY.

The information displayed at the ONERWAY checkout page is as follows:


API Payment Integrations

In this model, merchants need to integrate Apple Pay's JS and related logic judgment, and then send the generated token to ONERWAY, and then ONERWAY completes the subsequent payment.

1. Follow the official Apple Pay guidelines to complete the following steps:

（1）Create an App ID
（2）Create a Merchant id
（3）Create a payment processing certificate
（4）Create a merchant identity certificate
（5）Register and validate your merchant domain with Apple

2. Connect to JS, refer to Demo:

(1) Add Apple Pay API Javascript library on web pages <script async src="https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js" onload="console.log('TODO: add onload function')"> </script>
(2) Place button
Button styles can be customized, and button support languages can be set according to needs <style> apple-pay-button { --apple-pay-button-width: 150px; --apple-pay-button-height: 30px; --apple-pay-button-border-radius: 3px; --apple-pay-button-padding: 0px 0px; --apple-pay-button-box-sizing: border-box; } </style> <-- The button can be hidden first. After verifying that Apple Pay payment is supported, the Apple Pay button can be displayed --> <apple-pay-button buttonstyle="black" type="plain" locale="en"></apple-pay-button> (3) After successfully loading the Apple Pay API Javascript library, check if the current device and/or browser supports Apple Pay. If so, then initialize the Apple Pay button // Verification if (window.ApplePaySession) { // Merchant Identifier provided by Ronghan var promise = window.ApplePaySession.canMakePaymentsWithActiveCard('merchantIdentifier'); promise.then((canMakePayments) => { if (canMakePayments) { // TODO: Display Apple Pay button console.log('canMakePayments'); } }).catch((err) => { console.log('error', err); }); }
If you use Apple Pay in Chinese Mainland, you need to add additional device verification (ronghan doesn't support it yet)
The device is either an iPhone or an iPad
The system version is iOS 11.2 or newer version
(4) Create a session after clicking the Apple Pay button const request = { countryCode: 'US', currencyCode: 'USD', supportedNetworks: ['visa', 'masterCard'], merchantCapabilities: ['supports3DS'], total: { label: 'Demo (Card is not charged)', type: 'final', amount: '0.01' }, } var session = new window.ApplePaySession(1, request); (5) Server authentication session session.onvalidatemerchant = event => { const validationURL = event.validationURL // TODO: Call your own server to request a new merchant session. }; (6) Authorized Payment session.onpaymentauthorized = event => { const applePaymentToken = event.payment.token; //ApplePay Payment Token // TODO: Request API authorization for payment // After requesting the API to obtain the payment result, call the session.completePayment method session.completePayment(session.STATUS_SUCCESS); // session.STATUS_SUCCESS session.STATUS_FAILURE }; (7) Cancel payment session.oncancel = event => { // TODO console.log('oncancel===========', event); }; (8) Present payment receipt and initiate merchant verification process session.begin(); (9) For more information, please refer to Apple Pay official website documentation

3. After the completion of the previous steps, get the token of Apple Pay, please send this field together with other fields to ONERWAY through the API Payment, and then ONERWAY completes the payment and returns the payment result;

Create Merchant id

Follow these steps to create a Merchant id.

1. Login developer.apple.com/account;

2. From the Certificates, IDs & Profiles section, select "Identifiers".

3. Choose Merchant IDs


4. Choose Merchant IDs, click Continue;

5. Click the Add button, fill in the Description and Identifier, and click Continue. (Recommended name for the Identifier: merchant.[yoursitename].onerway.test for the test environment, and merchant.[yoursitename].onerway.prod for the production environment. Example: merchant.ABC.Onerway.Test)

6. Check the information and click the Register button. This will give you the Merchant ID;

Create a payment processing certificate

The Payment processing certificate is Apple Pay's certificate for encrypting payment transaction data against the Merchant ID dimension. The validity of the certificate is 25 months.
Steps:

1. Login developer.apple.com/account;

2. From the Certificates, IDs & Profiles section, select "Identifiers".

3. Select the Merchant IDs that have been successfully registered before and go to the next step

4. Select the Apple Pay Payment Processing Certificate section and click the Create Certificate button to go to the next step

5. Select the no China mainland region.

6. Generate the appropriate certificate according to Apple Pay guidelines . The ECC file (.csr file) is exported and uploaded to apple pay.

7. After the upload, download the certificate (.cer file). Double-click the certificate (.cer file), then in the pop-up page (Keychain access software), select the certificate and export (.p12 file), send to ONERWAY staff;

Note: This step must be done on a MAC system;

Create a Merchant identity certificate

The Merchant Identity certificate is Apple Pay's certificate for the Merchant ID dimension used to verify data with the Apple Pay server. The validity of the certificate is 25 months.
Steps:

1. Login developer.apple.com/account;

2. From the Certificates, IDs & Profiles section, select "Identifiers".

3. Select the Merchant IDs that have been successfully registered before and go to the next step

4. Select the Apple Pay Merchant Identity Certificate section and click the Create Certificate button to enter the next step

5. Generate the appropriate certificate according to Apple Pay guidelines . The RSA file (.csr file) is exported and uploaded to apple pay.

6. After the upload, download the certificate (.cer file). Double-click the certificate (.cer file), then in the pop-up page (Keychain access software), select the certificate and export (.p12 file), save for later calls to Apple JS);

Note: This step must be done on a MAC system;

Register and validate your merchant domain with Apple

Domains that need to use Apple Pay need to be registered and verified with Apple Pay. Steps:

1. Login developer.apple.com/account;

2. From the Certificates, IDs & Profiles section, select "Identifiers"

3. Select the Merchant IDs that have been successfully registered before and go to the next step

4. Follow the Apple Pay domain registration guidelines .

Auto Debit

Process Description


1. Before signing the contract, you can consult about the available payment methods.
2. The merchant can obtain the URL of the signing page corresponding to the payment method selected by the customer through the interface, and then redirect to this page to let the customer complete the signing (that is, bind the payment method).
3. After signing the contract, the customer will go back to the return url designated by the merchant. Authorization code and transaction order number are spliced behind the url. The merchant needs to use the authorization code and transaction order number to apply for a token and save it.
4. The token can be used for auto debit transactions within the validity period of the token. After expiration, this process needs to be repeated.

Consult Payment


Please refer to \API Payment\Consult Payment.
It should be noted that in order to accurately inquire about the payment methods available for auto debit, subProductType must be transferred to AUTO_DEBIT.

Get Url

POST /v1/txn/prepare

Example requests

{
    "requestId": "1667979672000",
    "merchantNo":"800058",
    "subProductType":"AUTO_DEBIT",
    "paymentMode":"WEB",
    "osType":null,
    "appId":"1496733359741014016",
    "merchantCustId":"1667979672000",
    "lpmsType":"Alipay+",
    "country":"",
    "orderCurrency":"CNY",
    "returnUrl":"https://www.ronhan.com",
    "sign":"..."
}

Request parameters

Name Type Length Required Signed Description
requestId String 64 Yes Yes The ID of the request created by the merchant.
merchantNo String 20 Yes Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
subProductType String 16 Yes Yes Sub product type, Please refer to SubProductTypeEnum
paymentMode String 16 No Yes Payment mode. Please refer to PaymentModeEnum. Default as WEB
osType String 16 No Yes Operating system type. Please refer to OsTypeEnum. Required when paymentMode is not WEB
appId String 20 Yes Yes Merchant application id. When a merchant registers a website, Onerway will create an application id for the merchant
merchantCustId String 50 Yes Yes Merchant customer id
lpmsType String 64 Yes Yes Local payment method. Please refer to LpmsTypeEnum
country String 64 No Yes Country. Please refer to ISO. For example: the United States is US
orderCurrency String 8 Yes Yes The currency of the transaction order. Please refer to ISO 4217 Currency Codes
returnUrl String 256 Yes Yes The URL of the merchant's side. The customer will jump back to this url after binding
sign String / Yes No Signature string.

Example responses

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "redirectUrl": "https://g.alipayplus.com/page/ac-auth-payment/auth/mobile/index.html?loadMode=2&authRequestId=2022110919091305000050000158064",
        "sign": "..."
    }
}

Response parameters

Name Type Signed Description
respCode String No Response code sourced from Onerway
respMsg String No Response message sourced from Onerway
data Map No Response data. Please refer to PrepareInfo json object

PrepareInfo

Name Type Signed Description
redirectUrl String Yes The merchant needs to redirect to this URL so that the customer can continue signing.
sign String No Signature string.

Apply Token

Points for attention:
(1) This interface only applies for token, and will not return results synchronously. After successful application, it will asynchronously notify the merchant of the information about the token

POST /v1/txn/applyToken

Example requests

{
    "transactionId": "1590248211400531968",
    "merchantNo":"800058",
    "authCode":"281SP213_1667979760302000012dee6",
    "sign":"..."
}

Request parameters

Name Type Length Required Signed Description
merchantNo String 20 Yes Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
transactionId String 20 Yes Yes The transaction order number created by Onerway. It needs to be obtained from the returnUrl, and the corresponding field is authState
authCode String 64 Yes Yes Authorization code returned by the payment method signed by the customer. It needs to be obtained from the returnUrl. The corresponding field is authCode
sign String / Yes No Signature string.

Example responses

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": null
}

Response parameters

Name Type Signed Description
respCode String No Response code sourced from Onerway
respMsg String No Response message sourced from Onerway

Auto Debit


Please refer to \API Payment\API Payment。
Note that subProductType must be transferred to AUTO_DEBIT.

Customs Declaration

Customs Declaration

POST /v1/txn/declareCustoms

Example requests

{
  "merchantNo":"800058",
  "originTxnId":"1524994590991003648",
  "isUpdate":false,
  "merCustomsNo":"hanguo",
  "merCustomsName":"jwyhanguo_card",
  "customs":"NINGBO",
  "isSplit":false,
  "subOrderNo":"",
  "productAmount":"10",
  "transportAmount":"0",
  "amount":"18.29",
  "currency":"CNY",
  "buyer":"{\"certType\":\"ID_CARD\",\"idNo\":\"230227198707200000\",\"name\":\"TEST\"}",
  "sign":"..."
}

Request parameters

Name Type Length Required Signed Description
merchantNo String 20 Yes Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
originTxnId String 20 Yes Yes The transaction order number sourced from Onerway that needs to be declared .
isUpdate Boolean / Yes Yes The merchant can decide whether to update customs declaration information. The value of this field is true means to update, and false means to add.
merCustomsNo String 128 Yes Yes The merchant code that is registered in the customs system.
merCustomsName String 256 Yes Yes The merchant name that is registered in the customs system.
customs String 64 Yes Yes The customs code. Please refer to CustomsCodeEnum
amount String 19 Yes Yes The amount to be declared.
currency String 8 Yes Yes The currency of the amount to be declared. Please refer to ISO 4217 Currency Codes. Currently only supports CNY
buyer String / Yes Yes The buyer information. The format is json string. Please refer to Buyer object
isSplit Boolean / Yes Yes The merchant can decide whether the order is split for declaration. If the value of this field is true, order splitting is allowed.
subOrderNo String 64 No Yes The unique ID that is assigned by the merchant to identify an order. When isSplit is true, this field is required and is used as the order ID to be declared to the customs.
productAmount String 19 No Yes The amount of the product. When isSplit is true, this field is required
transportAmount String 19 No Yes The amount of logistics costs. When isSplit is true, this field is required
sign String / Yes No Signature string.

Buyer

Name Type Length Required Signed Description
certType String 64 Yes No Identification type. Please refer to CredentialsTypeEnum. Currently only supports ID_CARD
idNo String 64 Yes No Identification Number
name String 64 Yes No Buyer full name

Example responses

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "declareCustomsId": "1524997122043752448",
    "sign": "..."
  }
}

Response parameters

Name Type Signed Description
respCode String No Response code sourced from Onerway
respMsg String No Response message sourced from Onerway
data Map No Response data. Please refer to DeclareCustoms json object

DeclareCustoms

Name Type Signed Description
declareCustomsId String Yes The customs declaration order number created by Onerway. This field can be used to query customs declaration results
sign String No Signature string.

Transaction details declaration

Payment order declaration

POST /v1/txn/declarePayment

Example requests

{
  "merchantNo": "800043",
  "appId": "1452526626019663872",
  "originTxnId": "123456",
  "merchantTxnId": "654321-1234",
  "tradeTime": "2022-08-12 12:39:41",
  "subOrderQuantity": "1",
  "orderCurrency": "USD",
  "orderAmount": "14",
  "txnCurrency": "CNY",
  "txnAmount": "84",
  "convCurRate": "6",
  "buyerName": "qingdong.zhang",
  "buyerEmail": "qingdong.zhang@onerway.com",
  "buyerCounty": "CN",
  "sign": "..."
}

Request parameters

Name Type Length Required Signed Description
merchantNo String 20 Yes Yes Merchant number. OnerWay creates the merchant number for the merchant when the merchant registers
appId String 20 Yes Yes Merchant Application ID. OnerWay creates an application id for the merchant when the merchant signs up for the site
originTxnId String 20 Yes Yes Trade orders from Onerway that need to be reported
merchantTxnId String 64 Yes Yes Merchant transaction order number created by the merchant
tradeTime String 19 Yes Yes Transaction time in the format of yyyy-MM-dd HH:mm:ss,
subOrderQuantity String 12 Yes Yes Number of sub orders.
orderCurrency String 3 Yes Yes The currency of the trade order. See ISO 4217 Currency Codes
orderAmount String 19 Yes Yes Order amount.
txnCurrency String 3 Yes Yes Settlement currency. See ISO 4217 Currency Codes
txnAmount String 19 Yes Yes Settlement amount
convCurRate String 19 Yes Yes Conversion Rates
buyerName String 64 Yes Yes Name of payer
buyerEmail String 19 Yes Yes Payer Email
buyerCounty String 19 Yes Yes Country or region of payer
sign String / Yes No Signature string.

Example responses

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "merchantNo": "800043",
        "appId": "1452526626019663872",
        "originTxnId": "123456",
        "merchantTxnId": "654321-1234",
        "recordId": "1570284047903137792",
        "sign": "..."
    }
}

Response parameters

Name Type Required Description
respCode String No Response code from Onerway
respMsg String No Response message from Onerway
data Map No Response data. See the object DeclarePayment

DeclarePayment

Name Type Required Description
merchantNo String Yes The customs declaration number created by Onerway. This field can be used to query customs declaration results
appId String Yes Merchant Application ID. OnerWay creates an application id for the merchant when the merchant signs up for the site
originTxnId String Yes Transaction order number from Onerway that needs to be declared.
merchantTxnId String Yes Merchant transaction order number created by the merchant, different order numbers are considered different transactions
recordId String Yes Declaration record return ID
sign String No Signature string.

Trade orders declaration

POST /v1/txn/declareTrade

Example requests

{
  "merchantNo": "800043",
  "appId": "1452526626019663872",
  "originTxnId": "123456",
  "merchantTxnId": "654321-1234",
  "isOnerway":"false",
  "subTradeOrders":"[{\"merchantTxnId\":\"654321-1234\",\"merchantSubTxnId\":\"654321-1234-1\",\"goodsName\":\"iphone 14 pro\",\"goodsQuantity\":\"1\",\"tradeType\":\"货物贸易\",\"currency\":\"USD\",\"amount\":\"14\"}]",
  "sign": "..."
}

Request parameters

Name Type Length Required Signed Description
merchantNo String 20 Yes Yes Merchant number. OnerWay creates the merchant number for the merchant when the merchant registers
appId String 20 Yes Yes Merchant Application ID. OnerWay creates an application id for the merchant when the merchant signs up for the site
originTxnId String 20 Yes Yes Trade orders from Onerway that need to be reported
merchantTxnId String 64 Yes Yes Merchant transaction order number created by the merchant, different order numbers are considered different transactions
subTradeOrders String 1024 Yes Yes Trade order information in the format of a json string. See the object SubTradeOrder
sign String / Yes Yes Signature string.

SubTradeOrder

Name Type Length Required Signed Description
merchantTxnId String 64 Yes No Merchant Order Number
merchantSubTxnId String 64 Yes No Merchant sub order number
goodsName String 256 Yes No Product Name
goodsQuantity String 12 Yes No Quantity of items
tradeType String 8 Yes No Transaction type: Trade in goods, trade in services... General default trade in goods
currency String 3 Yes No Sub-order Currency
amount String 19 Yes No Sub-order amount

Example responses

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "merchantNo": "800043",
        "appId": "1452526626019663872",
        "originTxnId": "123456",
        "merchantTxnId": "654321-1234",
        "recordId": "1570284047903137792",
        "sign": "..."
    }
}

Response parameters

Name Type Required Description
respCode String No Response code from Onerway
respMsg String No Response message from Onerway
data Map No Response data. See the object DeclareTrade

DeclareTrade

Name Type Required Description
merchantNo String Yes Merchant number.
appId String Yes App Id
originTxnId String Yes Transaction order number from Onerway that needs to be declared.
merchantTxnId String Yes Merchant transaction order number created by the merchant
recordId String Yes Declaration record return ID
sign String No Signature String

Track order declaration

POST /v1/txn/declareTrack

Example requests

{
  "merchantNo": "800043",
  "appId": "1452526626019663872",
  "originTxnId": "123456",
  "merchantTxnId": "654321-1234",
  "subTrackOrders":"[{\"merchantTxnId\":\"654321-1234\",\"merchantSubTxnId\":\"654321-1234-1\",\"carrierName\":\"UPS\",\"carrierService\":\"UPS Ground \",\"logTrackNum\":\"UPS111222334\",\"shipDate\":\"2022-09-11\"}]",
  "sign": "..."
}

Request parameters

Name Type Length Required Signed Description
merchantNo String 20 Yes Yes Merchant number
appId String 20 Yes Yes App id
originTxnId String 20 Yes Yes Trade orders from Onerway that need to be reported
merchantTxnId String 64 Yes Yes Merchant transaction order number created by the merchant
subTrackOrders String 1024 Yes Yes Trade order information in the format of a json string. See the object SubTrackOrder
sign String / Yes Yes Signature

SubTrackOrder

Name Type Length Required Signed Description
merchantTxnId String 64 Yes No Merchant Order Number
merchantSubTxnId String 64 Yes No Merchant sub order number
carrierName String 16 Yes No Carriers such as UPS
carrierService String 32 Yes No Carrier services such as UPS Ground
logTrackNum String 64 Yes No Logistics tracking number
shipDate String 10 Yes No Date of shipment, in the format yyyy-MM-dd

Example responses

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "merchantNo": "800043",
        "appId": "1452526626019663872",
        "originTxnId": "123456",
        "merchantTxnId": "654321-1234",
        "recordId": "1570284047903137792",
        "sign": "..."
    }
}

Response parameters

Name Type Required Description
respCode String No Response code from Onerway
respMsg String No Response message from Onerway
data Map No Response data. See the object DeclareTrack

DeclareTrack

Name Type Required Description
merchantNo String Yes Merchant number.
appId String Yes App Id
originTxnId String Yes Transaction order number from Onerway that needs to be declared.
merchantTxnId String Yes Merchant transaction order number created by the merchant
recordId String Yes Declaration record return ID
sign String No Signature String

Cancel

Cancel Transaction

Points for attention:
(1) The cancellation application can only be initiated within 5 minutes to 30 minutes after the payment is completed and the transaction status is still in processing.
(2) According to the application, we will verify the final status of the original transaction, and the processing method of cancellation will vary according to the actual final status of the original transaction.
(3) If it is determined that the original transaction is actually unsuccessful, the merchant will be notified directly that the cancellation is successful; if it is determined that the original transaction is actually successful, then we will initiate a refund, and notify the merchant that the cancellation is successful after the refund is successful.

POST /v1/txn/cancelTxn

Example requests

{
  "merchantNo": "800058",
  "originTransactionId": "1484408335541923840",
  "sign": "..."
}

Request parameters

Name Type Length Required Signed Description
originTransactionId String 20 Yes Yes The original transaction order number sourced from Onerway, often used for reverse transactions, to find the corresponding forward transaction order number
merchantNo String 20 Yes Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
sign String / Yes No Signature string.

Example responses

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1484409612279672832",
    "status": "I"
  }
}

Response parameters

Name Type Signed Description
respCode String No Response code sourced from Onerway
respMsg String No Response message sourced from Onerway
data Map No Response data. Please refer to TxnCancelInfo json object

TxnCancelInfo

Name Type Signed Description
transactionId String No Cancellation order number
status String No The status of applying for cancellation. Please refer to TxnStatusEnum

Cancel Subscription

POST /v1/txn/sub/cancel

Example requests

{
  "merchantNo": "800037",
  "contractId": "1473942457062490112",
  "sign": "..."
}

Request parameters

Name Type Length Required Signed Description
contractId String 20 Yes Yes Subscription contract id
merchantNo String 20 Yes Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
sign String / Yes No Signature string.

Example responses

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": "3"
}

Response parameters

Name Type Signed Description
respCode String No Response code sourced from Onerway
respMsg String No Response message sourced from Onerway
data String No contract status. Please refer to ContractStatusEnum

Refund

Apply Refund

POST /v1/txn/onlineRefund

Example requests

{
  "merchantNo": "800037",
  "refundType": "0",
  "merchantTxnId": "1640241780000",
  "originTransactionId":"1473906683882672128",
  "refundAmount": "20",
  "sign": "..."
}

Request parameters

Name Type Length Required Signed Description
merchantNo String 20 Yes Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
refundType String 1 Yes Yes Transaction Refund Type, The enum is as follows: 0 - apply for a refund 1 - cancel the refund
merchantTxnId String 64 No Yes Merchant refund transaction order number created by the merchant.Different order numbers are regarded as different transactions
originTransactionId String 20 Yes Yes The original transaction order number sourced from Onerway. It is a forward transaction order number when refundType is 0. And it is a refund transaction order number when refundType is 1.
refundAmount String 19 Yes Yes Refund transaction amount, the currency of this amount should correspond to the order currency sent during the forward transaction
sign String / Yes No Signature string.

Example responses

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": "1473906993397141504"
}

Response parameters

Name Type Signed Description
respCode String No Response code sourced from Onerway
respMsg String No Response message sourced from Onerway
data String No Refund transaction order number created by Onerway, returned when applying for refund

Transaction Search

Inquiry Transactions

POST /v1/txn/list

Example requests

{
  "merchantNo": "800037",
  "merchantTxnIds": "1640244407000,1640244473000",
  "transactionIds": "",
  "txnTypes": "",
  "startTime": "",
  "endTime": "",
  "current": "1",
  "sign": "..."
}

Request parameters

Name Type Length Required Signed Description
merchantNo String 20 Yes Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
merchantTxnIds String / No Yes Merchant transaction order number, which can be multiple, separated by commas, for example: "554815,684541"
transactionIds String / No Yes Onerway transaction order number which can be multiple, separated by commas
txnTypes String / No Yes Transaction type which can be multiple, separated by commas
startTime String / No Yes transaction start time, the format is yyyy-MM-dd HH:mm:ss
endTime String / No Yes transaction end time, the format is yyyy-MM-dd HH:mm:ss. The maximum interval is 90 days.
current String / Yes Yes The current page number of the query
sign String / Yes No Signature string.

Example responses

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "content": [
      {
        "transactionId": "1473918047031586816",
        "merchantTxnId": "1640244407000",
        "txnTime": "2021-12-23 15:27:01",
        "originTransactionId": null,
        "productType": "CARD",
        "subProductType": "DIRECT",
        "txnType": "0006",
        "status": "S",
        "paymentMethod": "VISA",
        "orderAmount": "20.00",
        "orderCurrency": "USD",
        "txnAmount": "20.00",
        "txnCurrency": "USD",
        "settleRate": "1",
        "arn": null,
        "appId": "1458672763818790912",
        "website": "800037.sc.com",
        "cardBinCountry": "US",
        "cardNumber": "400002******0961",
        "reason": null,
        "userPaymentStatus": "true"
      },
      {
        "transactionId": "1473918280901783552",
        "merchantTxnId": "1640244473000",
        "txnTime": "2021-12-23 15:27:56",
        "originTransactionId": null,
        "productType": "CARD",
        "subProductType": "DIRECT",
        "txnType": "0006",
        "status": "S",
        "paymentMethod": "VISA",
        "orderAmount": "20.00",
        "orderCurrency": "USD",
        "txnAmount": "20.00",
        "txnCurrency": "USD",
        "settleRate": "1",
        "arn": null,
        "appId": "1458672763818790912",
        "website": "800037.sc.com",
        "cardBinCountry": "US",
        "cardNumber": "400002******0961",
        "reason": null,
        "userPaymentStatus": null
      }
    ],
    "current": "1",
    "size": "10",
    "totalPages": "1",
    "totalElements": "2"
  }
}

Response parameters

Name Type Signed Description
respCode String No Response code sourced from Onerway
respMsg String No Response message sourced from Onerway
data Map No Response data. Please refer to Page json object

Page

Name Type Signed Description
content List No Transaction information list, Please refer to TxnInfo json object
current String No The current page number
size String No The current page size
totalPages String No Total pages
totalElements String No Total items

TxnInfo

Name Type Signed Description
transactionId String No The transaction order number created by Onerway,corresponding to the merchant order number
merchantTxnId String No Merchant transaction order number created by the merchant.Different order numbers are regarded as different transactions
txnTime String No Transaction completion time
originTransactionId String No The original transaction order number sourced from Onerway.
productType String No Product Type, Please refer to ProductTypeEnum
subProductType String No Sub product type, Please refer to SubProductTypeEnum
txnType String No Transaction type, Please refer to TxnTypeEnum
status String No Transaction processing result. Please refer toTxnStatusEnum
reason String No Reason for transaction failure
paymentMethod String No The specific payment method, including card type and local payment type
walletTypeName String No Wallet type brand name
orderAmount String No The amount of the transaction order
orderCurrency String No The currency of the transaction order. Please refer to ISO 4217 Currency Codes
txnAmount String No The transaction amount in settlement currency
txnCurrency String No The settlement currency. Please refer to ISO 4217 Currency Codes
settleRate String No Settle rate (txnAmount = orderAmount * settleRate).
customsDeclarationAmount String No Amount available for customs declaration
customsDeclarationCurrency String No The currency of the amount available for customs declaration. Please refer to ISO 4217 Currency Codes
arn String No ARN
appId String No Merchant application id. When a merchant registers a website, Onerway will create an application id for the merchant
website String No Transaction website
cardBinCountry String No Country of card bin
cardNumber String No Transaction card number
userPaymentStatus String No User payment status, true: paid, false: unpaid, (Only Blik/Konbini/Payeasy/Sofort transactions may concern this field; This field can be ignored when value is null)
holderName String No The cardholder's Name
eci String No Transfer of responsibility

Inquiry Chargebacks

POST /v1/chargeback/list

Example requests

{
  "chargebackIds":"",
  "current":"1",
  "importTimeEnd":"",
  "importTimeStart":"",
  "merchantNo":"800037",
  "merchantTxnIds":"",
  "originTransactionIds":"1535176982304575488",
  "sign":"…"
}

Request parameters

Name Type Length Required Signed Description
merchantNo String 20 Yes Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
merchantTxnIds String / No Yes Merchant transaction order number, which can be multiple, separated by commas, for example: "554815,684541"
originTransactionIds String / No Yes The original transaction order number sourced from Onerway, which can be multiple, separated by commas
chargebackIds String / No Yes The chargeback transaction order number, sourced from Onerway, which can be multiple, separated by commas
importTimeStart String / No Yes The start time of the chargeback transaction received by Oneway, the format is yyyy-MM-dd HH:mm:ss
importTimeEnd String / No Yes The end time of the chargeback transaction received by Oneway, the format is yyyy-MM-dd HH:mm:ss. The maximum interval is 90 days.
current String / Yes Yes The current page number of the query
sign String / Yes No Signature string.

Example responses

{
  "respCode":"20000",
  "respMsg":"Success",
  "data":{
    "content":[
      {
        "merchantNo":"800037",
        "chargebackId":"1535178069061324800",
        "importTime":"2022-06-10 16:32:29",
        "merchantTxnId":"1654849689044",
        "originTransactionId":"1535176982304575488",
        "txnAmount":"30.90",
        "txnCurrency":"EUR",
        "txnTime":"2022-06-10 16:28:10",
        "paymentMethod":"VISA",
        "chargebackAmount":"1.00",
        "chargebackCurrency":"USD",
        "chargebackDate":"2022-06-10",
        "chargebackReason":"chargeback occurs",
        "chargebackArn":"123",
        "appealDueTime":"2022-09-10 10:21:55",
        "chargebackCode":"res1206CODE",
        "chargebackStatus":"NEW"
      }
    ],
    "current":"1",
    "size":10,
    "totalPages":1,
    "totalElements":1
  }
}

Response parameters

Name Type Signed Description
respCode String No Response code sourced from Onerway
respMsg String No Response message sourced from Onerway
data Map No Response data. Please refer to Page json object

Page

Name Type Signed Description
content List No Transaction information list, Please refer to ChargebackInfo json object
current String No The current page number
size String No The current page size
totalPages String No Total pages
totalElements String No Total items

ChargebackInfo

Name Type Signed Description
merchantNo String No Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
merchantTxnId String No Merchant transaction order number created by the merchant.Different order numbers are regarded as different transactions
originTransactionId String No The original transaction order number sourced from Onerway.
txnAmount String No The original transaction amount in settlement currency
txnCurrency String No The original transaction settlement currency. Please refer to ISO 4217 Currency Codes
txnTime String No The original transaction completion time
paymentMethod String No The specific payment method, including card type and local payment type
chargebackId String No The chargeback transaction order number created by Onerway
importTime String No The time of the chargeback transaction received by Oneway
chargebackAmount String No Chargeback amount that occurred
chargebackCurrency String No The currency of the chargeback amount. Please refer to ISO 4217 Currency Codes
chargebackDate String No The date the chargeback occurred
chargebackStatus String No Chargeback transaction status. Please refer toChargebackStatusEnum
chargebackReason String No Reason for chargeback
chargebackArn String No ARN
appealDueTime String No Deadline for submission of appeal materials, the format is yyyy-MM-dd HH:mm:ss
chargebackCode String No The chargeback code

Inquiry Customs Declaration

POST /v1/txn/getCustomsResult

Example requests

{
  "declareCustomsId":"1524997122043752448",
  "merchantNo":"800058",
  "sign":"..."
}

Request parameters

Name Type Length Required Signed Description
merchantNo String 20 Yes Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
declareCustomsId String 20 Yes Yes The customs declaration order number created by Onerway when merchant sends customs declaration request
sign String / Yes No Signature string.

Example responses

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "declareCustomsId": "1524997122043752448",
    "updateTime": "2022-05-13 14:20:40",
    "status": "S",
    "reason": null,
    "verifyDepartment": "CUP",
    "verifyDepartmentTxnId": "202108120000000808000000",
    "actualAmount": "18.29",
    "payCode": "31222699S7",
    "subOrderNo": null,
    "sign": "..."
  }
}

Response parameters

Name Type Signed Description
respCode String No Response code sourced from Onerway
respMsg String No Response message sourced from Onerway
data Map No Response data. Please refer to CustomsResult json object

CustomsResult

Name Type Signed Description
declareCustomsId String Yes The customs declaration order number created by Onerway when merchant sends customs declaration request
clearanceCustomsId String Yes Customs clearance id, used for merchant customs clearance
updateTime String Yes Customs declaration completion time, the format is yyyy-MM-dd HH:mm:ss
status String Yes Customs declaration processing result. Please refer toTxnStatusEnum
reason String Yes Reason for customs declaration failure
verifyDepartment String Yes The clearing organization. Please refer to VerifyDepartmentEnum
verifyDepartmentTxnId String Yes The clearing organization's clearing serial number. Can be verified by organizations trusted by the People's Bank of China.
actualAmount String Yes Actual customs declaration amount. Currency is CNY.
payCode String Yes The wallet's registration ID in the customs system.
subOrderNo String Yes The unique ID that is assigned by the merchant to identify an order.
sign String No Signature string.

Notification

Notification

Points for attention:
(1) The notification url can be sent to us in two ways: one is provided by the merchant when registering in Onerway, and the other is transmitted through the fields in the API.
(2) First, the system will find the notification url in the API. If not, it will find the notification url in the background configuration. If neither is found, it will not send a notification.
(3) The merchant needs to develop according to the following parameters and respond to the receiving results.
(4) Please add v1/txn/notifyResult to the URI part of the notification url.
(5) The payment result is subject to this notification !

POST {notifyUrl}

Example requests

{
  "//": "Payment result notification",
  "notifyType": "TXN",
  "transactionId": "1599953668994019328",
  "txnType": "SALE",
  "merchantNo": "800096",
  "merchantTxnId": "1670293654000",
  "originMerchantTxnId": null,
  "responseTime": "2022-12-06 10:27:39",
  "txnTime": "2022-12-06 10:27:35",
  "txnTimeZone": "+08:00",
  "orderAmount": "29.00",
  "orderCurrency": "USD",
  "txnAmount": "29.00",
  "txnCurrency": "USD",
  "customsDeclarationAmount": null,
  "customsDeclarationCurrency": null,
  "status": "S",
  "contractId": null,
  "tokenId": null,
  "tokenExpireTime": null,
  "eci": null,
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "periodValue": null,
  "paymentMethod": "VISA",
  "walletTypeName": null,
  "sign": "..."
}


{
  "//": "Refund result notification",
  "notifyType":"TXN",
  "transactionId":"1600000893212209152",
  "txnType":"REFUND",
  "merchantNo":"800096",
  "merchantTxnId":"1670304250000",
  "originMerchantTxnId":"1670304250000",
  "responseTime":"2022-12-06 13:36:06",
  "txnTime":null,
  "txnTimeZone":"+08:00",
  "orderAmount":"16.00",
  "orderCurrency":"USD",
  "txnAmount":"16.00",
  "txnCurrency":"USD",
  "settleRate":"1",
  "customsDeclarationAmount":null,
  "customsDeclarationCurrency":null,
  "status":"S",
  "contractId":null,
  "tokenId":null,
  "tokenExpireTime":null,
  "eci":null,
  "reason":"{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "periodValue":null,
  "paymentMethod":"VISA",
  "walletTypeName":null,
  "sign": "..."
}


{
  "//": "Cancel transaction result notification",
  "notifyType":"CANCEL",
  "transactionId":"1600013917075582976",
  "txnType":"SALE",
  "merchantNo":"800058",
  "merchantTxnId":"1670308019000",
  "originMerchantTxnId":null,
  "responseTime":null,
  "txnTime":"2022-12-06 14:26:59",
  "txnTimeZone":null,
  "orderAmount":"323.90",
  "orderCurrency":"USD",
  "txnAmount":"",
  "txnCurrency":null,
  "settleRate":null,
  "customsDeclarationAmount":null,
  "customsDeclarationCurrency":null,
  "status":"S",
  "contractId":null,
  "tokenId":null,
  "tokenExpireTime":null,
  "eci":null,
  "reason":"{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "periodValue":null,
  "paymentMethod":null,
  "walletTypeName":null,
  "sign": "..."
}


{
  "//": "Refund audit result notification",
  "notifyType":"REFUND_AUDIT",
  "transactionId":"1605750169942548480",
  "txnType":null,
  "merchantNo":"800058",
  "merchantTxnId":null,
  "originMerchantTxnId":null,
  "responseTime":null,
  "txnTime":null,
  "txnTimeZone":null,
  "orderAmount":"",
  "orderCurrency":null,
  "txnAmount":"",
  "txnCurrency":null,
  "customsDeclarationAmount":null,
  "customsDeclarationCurrency":null,
  "status":"F",
  "contractId":null,
  "tokenId":null,
  "tokenExpireTime":null,
  "eci":null,
  "reason":null,
  "periodValue":null,
  "paymentMethod":null,
  "walletTypeName":null,
  "sign": "..."
}


{
  "//": "Chargeback notification",
  "notifyType": "CHARGEBACK",
  "merchantNo": "800096",
  "transactionId": "1599959226371321856",
  "originTransactionId": "1599953668994019328",
  "originMerchantTxnId": "1670293654000",
  "importTime": "2022-12-06 10:49:40",
  "chargebackDate": "2022-12-06",
  "chargebackAmount": "2.00",
  "chargebackCurrency": "USD",
  "chargebackStatus": "NEW",
  "chargebackArn": "555",
  "chargebackCode": "res1206CODE",
  "chargebackReason": "res1206",
  "appealDueTime": "2023-03-06 10:49:40",
  "sign": "..."
}

Request parameters

Name Type Length Signed Description
notifyType String / Yes Notification type. Please refer to NotifyTypeEnum
txnType String / Yes Transaction type. Please refer to TxnTypeEnum. Returned when notifyType is TXN, used to distinguish between payment and refund
transactionId String 20 Yes The transaction order number created by Onerway,corresponding to the merchant order number
originTransactionId String 20 No The original transaction order number sourced from Onerway, corresponding forward transaction, will be returned in the notification of reverse transactions such as refunds
merchantTxnId String 64 Yes Merchant transaction order number created by the merchant.Different order numbers are regarded as different transactions
originMerchantTxnId String 64 No The merchant's original transaction order number, corresponding forward transaction, will be returned in the notification of reverse transactions such as refunds
merchantNo String 20 Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
responseTime String / Yes Interface response time, the format is yyyy-MM-dd HH:mm:ss
txnTime String / Yes Transaction completion time, the format is yyyy-MM-dd HH:mm:ss
txnTimeZone String / Yes Transaction completion time zone, for example: +08:00
orderAmount String 19 Yes The amount of the transaction order
orderCurrency String 8 Yes The currency of the transaction order. Please refer to ISO 4217 Currency Codes
txnAmount String 19 Yes The transaction amount in settlement currency
txnCurrency String 8 Yes The settlement currency. Please refer to ISO 4217 Currency Codes
settleRate String 19 Yes Settle rate (txnAmount = orderAmount * settleRate).
customsDeclarationAmount String 19 No Amount available for customs declaration
customsDeclarationCurrency String 8 No The currency of the amount available for customs declaration. Please refer to ISO 4217 Currency Codes
paymentMethod String 64 No The specific payment method, including card type and local payment type
walletTypeName String 128 No Wallet type brand name
status String 1 Yes Transaction processing result. The enum is as follows: S - Transaction success/cancel transaction success F - Transaction failed/approval not pass/cancel transaction failed
reason String 512 Yes Reason for transaction failure
periodValue String / No Number of installments
contractId String 20 Yes Subscription contract id , returned when paying for the first subscription
tokenId String 300 Yes Subscription token id , returned when paying for the first subscription or applying token in auto debit
tokenExpireTime String / No The expiration time of the token, returned when applying token in auto debit
eci String 2 Yes Transfer of responsibility
chargebackDate String / Yes Date of chargeback, the format is yyyy-MM-dd
importTime String / Yes The time of the chargeback transaction received by Oneway, the format is yyyy-MM-dd HH:mm:ss
appealDueTime String / Yes Deadline for submission of appeal materials, the format is yyyy-MM-dd HH:mm:ss
chargebackAmount String 19 Yes The chargeback amount
chargebackCurrency String 8 Yes The currency corresponding to the chargeback amount. Please refer to ISO 4217 Currency Codes
chargebackStatus String 16 Yes The chargeback status. Please refer toChargebackStatusEnum
chargebackArn String 128 Yes The chargeback ARN
chargebackCode String 32 Yes The chargeback code
chargebackReason String 1024 Yes The chargeback reason
sign String / No Signature string.

Example responses

"1530009844336164864"

Response parameters

Name Type Signed Description
transactionId String No The transaction order number created by Onerway,corresponding to the merchant order number

Just return the value of transactionId !

File

Download Settlement File

Points for attention:
(1) The interface returns a file stream, and the Content-Type in the response header is application/octet-stream
(2) The character set only supports UTF-8
(3) It is recommended to write the file stream to a file with a suffix of csv, please refer to settlement_800037_20220408_USD.csv and settlement_800037_20220325_GBP.csv

GET /v1/settlementFile/download

Http header parameter

Name Type Length Required Signed Description
merchantNo String 20 Yes Yes Merchant number. When a merchant registers, Onerway will create a merchant number for the merchant
date String 8 Yes Yes Settlement date, the format is yyyyMMdd
currency String 8 Yes Yes Settlement currency. Please refer to ISO 4217 Currency Codes
sign String / Yes No Signature string.

Document content

Settlement batch

Name Description
Settlement Date The settlement date calculated according to the settlement cycle
Settlement Currency Merchant settlement currency
Transaction Amount The transaction amount in the settlement currency
Refund Amount The amount for which a refund transaction occurred and the refund was successful
Transaction Processing Fee handling fee charged in direct payment transactions
Refund Processing Fee handling fee charged in refund transaction
Fee Fee charged in direct payment transactions
Interchange Fee Only in IC++ mode
Scheme Fee Only in IC++ mode
Markup Only in IC++ mode
Deposit Release The amount returned when the deposit is released
Deposit A certain amount of risk charged according to the contract, which will be returned after expiration
Settlement Amount In a batch, the netted amount of transaction amount and handling fee

Settlement details

Name Description
Settlement Date The settlement date calculated according to the settlement cycle
Settlement Batch ID A settlement batch will only generate one batch number
Transaction ID A transaction generates a transaction serial number
Merchant Order ID Merchant's transaction order number
Production Type CARD/LPMS
Card Type Card type and local payment method
APP ID Merchant application id. When a merchant registers a website, Onerway will create an application id for the merchant
Transaction URL Merchant transaction website
Order_Currency Transaction order currency
Order Amount Transaction order amount
Transaction Type /
Transaction Status /
Settlement Currency Merchant settlement currency
Transaction Amount The transaction amount in the settlement currency
Processing Fee handling fee
Fee transaction fee
Interchange Fee Only in IC++ mode
Scheme Fee Only in IC++ mode
Markup Only in IC++ mode
Deposit A certain amount of risk charged according to the contract, which will be returned after expiration
Settlement Amount In a transaction detail, the netted amount of transaction amount and handling fee
Settlement Status Settlement successful / Settlement failed
Wallet Type Code The code corresponding to the wallet type (currently exists when the local payment method is Alipay+)
Merchant Order Time Merchant transaction order occurrence time

Transaction Type

Code Description
SALE Pay directly
REFUND Refund
CB Chargeback
CB_CANCEL Chargeback Cancellation
CB_VOID Chargeback void
CB_APPEAL Chargeback Appeal
CB_APPEAL_SUCCESS Chargeback appeal successful
CB_APPEAL_SECOND Second Chargeback Appeal
CB_APPEAL_SECOND_SUCCESS Second chargeback appeal successful
CB_APPEAL_SECOND_FAILURE Second chargeback appeal failed

Code example



    public void downLoad(@RequestParam("localFileName") String localFileName,HttpServletResponse response) {
        HttpClient client = new HttpClient();
        GetMethod get = null;
        FileOutputStream output = null;
        try {
            get = new GetMethod("https://sandbox-v3-acquiring.pacypay.com/v1/settlementFile/download");
            get.setRequestHeader("merchantNo", "500010");
            get.setRequestHeader("date", "20211026");
            get.setRequestHeader("currency", "USD");
            get.setRequestHeader("sign","...");
            MultiThreadedHttpConnectionManager connectionManager = new MultiThreadedHttpConnectionManager();
            HttpConnectionManagerParams params = new HttpConnectionManagerParams();
            params.setConnectionTimeout( 20000 );
            params.setSoTimeout( 20000 );
            connectionManager.setParams(params);
            client = new HttpClient(connectionManager);
            HttpClientParams clientParams = new HttpClientParams();
            clientParams.setParameter("http.protocol.allow-circular-redirects", true);
            clientParams.setParameter("http.protocol.max-redirects", 4);
            client.setParams(clientParams);
            int i = client.executeMethod(get);
            if (200 == i) {
                File storeFile = new File(localFileName);
                output = new FileOutputStream(storeFile);
                output.write(get.getResponseBody());
            } else {
                System.out.println("DownLoad file occurs exception, the error code is :" + i);
            }
            InputStream inStream = new FileInputStream(localFileName);
            response.reset();
            response.setContentType("application/octet-stream");
            response.addHeader("Content-Disposition", "attachment; filename=\"" + localFileName + "\"");
            byte[] b = new byte[100];
            int len;
            try {
                while ((len = inStream.read(b)) > 0)
                    response.getOutputStream().write(b, 0, len);
                inStream.close();
            } catch (IOException e) {
                e.printStackTrace();
            }
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            try {
                if(output != null){
                    output.close();
                }
            } catch (IOException e) {
                e.printStackTrace();
            }
            get.releaseConnection();
            client.getHttpConnectionManager().closeIdleConnections(0);
        }
    }


Response Codes

Common Response Codes

code message Further action
20000 Success N/A
40004 API that does not exist N/A
40000 Illegal parameter [] N/A
40013 Abnormal parameters (cannot be read) N/A
40005 Unsupported request method N/A
40015 Unsupported media type N/A
50000 Unknown exception Human intervention is usually needed. It is recommended that you contact the technical support team to troubleshoot the issue.
50001 Merchant was not found It is recommended that you contact the technical support team to troubleshoot the issue.
50002 Repeated order transactions! N/A
50003 The query condition cannot be empty! (Order number or start and end time, both cannot be empty at the same time) Please ensure that the request parameters meet the requirements.
50005 The cumulative refund amount cannot be greater than the transaction amount！ N/A
50006 The source transaction does not support online refunds！ It is recommended that you contact the technical support team to troubleshoot the issue.
50007 The time range of transaction inquiry cannot exceed ninety days! N/A
50008 The initiating transaction ip is not in the configured whitelist! Human intervention is usually needed. It is recommended that you contact the technical support team to troubleshoot the issue.
50012 Repurchase initiation failed, contract information verification failed! It is recommended that you contact the technical support team to troubleshoot the issue.
50015 Online refund failed, this transaction does not support the initiation of a refund! N/A
50016 Online refund failed, there are unapproved orders! Please wait for the refund review to complete.
50017 Online refund failed, the source transaction was unsuccessful! N/A
50018 Non-existent transaction order! Check if the transaction ID or source transaction ID in the request is correct.
50020 Forced refund failed, the channel does not support online refund! It is recommended that you contact the technical support team to troubleshoot the issue.
50021 Failed to cancel the refund request, the refund has been processed and cannot be canceled! N/A
50023 Card number cannot be empty！ Please ensure that the request parameters meet the requirements.
50028 Invalid product format Please ensure that the request parameters meet the requirements.
50029 Card year/month is invalid Check if the card info in the request is correct.
50031 Card expired card Check if the card info in the request is correct.
50032 Invalid card number Check if the card info in the request is correct.
50033 Unsupported currency Check if the currency in the request is correct.
50034 Invalid transaction type Please ensure that the request parameters meet the requirements.
50035 Invalid transaction amount Check if the amount in the request is correct.
50036 Incorrect card information Please ensure that the request parameters meet the requirements.
50037 Merchant not enabled It is recommended that you contact the technical support team to troubleshoot the issue.
50045 Transaction Website is invalid Check if the website in the request is correct.
50047 Refund transaction must go through the designated interface for refund! Please use the refund interface for refund transactions.
50048 Invalid productType! Please ensure that the request parameters meet the requirements.
50049 Invalid subProductType! Please ensure that the request parameters meet the requirements.
50070 Subscription contract unavailable The subscription contract has been closed or cancelled, please create a new subscription.
50071 Subscription contract expired The subscription contract has expired, please create a new subscription.
50072 Subscription frequency is illegal The frequency of repurchase does not match the subscription contract information, please confirm the repurchase frequency.
50073 Subscription contract param can not be null Please ensure that the request parameters meet the requirements.
50074 Transaction number does not match merchant number N/A
50090 Subscription failed! Merchant customer number cannot be empty！ Please ensure that the request parameters meet the requirements.
50091 Repurchase failed! The contract number or token cannot be empty！ Please ensure that the request parameters meet the requirements.
50092 Transaction failed Human intervention is usually needed. It is recommended that you contact the technical support team to troubleshoot the issue.
50120 billingInformation cannot be empty or email and country cannot be empty Please ensure that the request parameters meet the requirements.
50121 risk3dsStrategy is EXTERNAL, mpiInfo not be null Please check the risk3dsStrategy.
50201 Account is disabled or does not exist! Please contact the operation personnel to confirm the merchant account status.
50204 Appid is invalid! Please contact the operation personnel to confirm the app id status.
53001 Invalid 3DS service The 3DS service is faulty. Please contact technical support.
53002 3DS permission is not available The 3DS service is usually faulty at the issuer or acquirer . Please contact technical support.
53003 No such issuer There is a problem with the credit card number, for example, the credit card BIN doesn't match the range of any issuer in the acquirer's list.
53004 Timeout A timeout occurred between the acquirer and the issuer. Please try again.
54001 Invalid transaction This code is generated by the issuer when no specific decline reason/code is returned.
54002 Invalid merchant Typically, this does not indicate any general issue with the merchant This decline reason is usually the result of an issue regarding an internal standard.
54003 Duplicate transmission. Indicates that a transaction was sent twice. Please modify it and try again.
54004 Payment failed. Generic error, an error caused by a failed transaction.
54005 Common decline Common error, unknown error.
54006 Invalid request parameter value. Please ensure that the request parameters meet the requirements.
55001 3DS Authentication failure 3DS verification failed.
55002 Invalid billing information Some information in the billing information is unavailable. Please check and try again.
55003 Decline for CVV2 failure Failure due to CVV input error, please cardholder check it and retry.
55004 Incorrect PIN or PIN missing This error is due to a PIN problem, and may indicate that the card is being blocked due to a security issue, such as exceeding the limit of PIN entry attempts at a point of sale.
55005 Lost card or Stolen card This error code is returned when the card is listed as lost or stolen on the issuer's side.
55006 High risk Failed transactions due to risk control.
55007 Exceeds withdrawal frequency limit The transaction amount or count exceeds the permitted frequency for this card or account.
55008 Strong customer authentication requried. This error means that stronger customer authentication is required.
55009 Invalid amount or currency conversion field overflow This error code is the result of an issue with the transaction amount or currency. This code may be triggered as a result of the currency or financial reasons such as insufficient funds.
55010 Refer to card issuer Please refers to the card issuer. It is possible that such transactions could be authorized with voice AuthCode.
55011 Card Authentication failed This error is the card information verification failure, please the cardholder check the card information and try again.
55012 Card not effective Invalid card, please the cardholder check the card information and try again.
55013 Card processing is forbidden Forbidden card, please the cardholder check the card information and try again.
55014 No credit account This usually indicates that there is an issue with the account connected to the credit card, for example, the account is expired, cancelled, or does not exist.
55015 No checking account This usually indicates that there is an issue with the account connected to the credit card, for example, the account is expired, cancelled, or does not exist.
55016 No savings account This usually indicates that there is an issue with the account connected to the credit card, for example, the account is expired, cancelled, or does not exist.
55017 Missing or invalid CardData data Missing or invalid CardData data, please the cardholder check the card information and try again.
55018 Expired card or expiration date is missing The credit card is no longer valid or expiration date is missing. It is also possible that the expiration date does not match the card details.
55019 Do not honor The most common and general issuer decline code. This code is generated by the issuer when no specific decline reason/code is returned.
55020 Retain Card Retain Card, please the cardholder check the card information and try again.
55021 Restricted card Restricted card, please the cardholder check the card information and try again.
55022 Rejected by customer N/A
55023 Custom Fraud Screen Filter. N/A
55024 Suspected fraud The transaction is suspected to be fraudulent.
55025 Transaction not permitted to cardholder The issuer did not allow this transaction against this card based on internal reasons, such as the transaction originated from a specifically restricted industry or country.
55026 Insufficient funds The credit card holder lacks sufficient funds to complete the transaction.
55027 Transaction failed trying again later. Please try again.
55028 Soft Decline – Authentication is Advised. User error - general cause - please try again.
55029 Cardholder withdrawal frequency limit User error - general cause - please try again.
55030 Invalid issuing account N/A
55031 Abnormal issuing account N/A
55032 Invalid Card Number User error - incorrect card number.
55033 Cryptographic failure User error - incorrect password.
55034 Unsupported card type, please contact support. Please contact support.
55035 Decline by route. Please contact support.
55036 Filter error, please contact support. Please contact support.
55044 The order is closed. N/A
55045 Exceed Refund window. N/A
55046 Closed Account N/A

Reference

RSA Key generation

1. Generate pkcs1 private key

openssl genrsa -out private.pem 2048

2. Convert pkcs1 private key to pkcs8 private key

openssl pkcs8 -topk8 -inform PEM -in private.pem -outform pem -nocrypt -out pkcs8.pem

3. Generate the public key of pkcs8

openssl rsa -in private.pem -pubout -out public_pkcs8.pem

Supported Cipher suite

For TLS1.2, the supported Cipher suite are as follows:

TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
Using something outside of this range will result in SSL connection failure!

Enumeration

Product type

ProductTypeEnum

Code Description
ALL It can only be used in the cashier payment scenario, indicating that the aggregated cashier will be opened
CARD Credit card
LPMS Local payment method
PAYMENT_CODE Payment code (The merchant scans the user's payment code)
ORDER_CODE Order code (The user scans the merchant's order code)

Sub product type

SubProductTypeEnum

Code Description
DIRECT direct payment
SUBSCRIBE subscription payment
INSTALLMENT installment payment
TOKEN token payment
AUTO_DEBIT auto debit

Transaction type

TxnTypeEnum

Code Description
SALE direct payment
REFUND Refund, only for transaction inquiries and notification
BIND_CARD Bind the payment methods (card and local payment), only for transaction inquiries and notification

Payment mode

PaymentModeEnum

Code Description
WEB The client-side terminal type is a website that is opened via a PC browser.
WAP The client-side terminal type is an HTML page that is opened via a mobile browser.

Operating system type

OsTypeEnum

Code Description
IOS iOS
ANDROID Android

Notification type

NotifyTypeEnum

Code Description
TXN Transactions notification, including payment and refund
REFUND_AUDIT Refund audit result notification
CANCEL Transaction cancellation notification
CHARGEBACK Chargeback notification

Transaction Status

TxnStatusEnum

Code Description
S Transaction successful
F Transaction failed / review failed
P The transaction result is unknown (processing)
R 3ds verification required
N transaction cancelled
I Refund pending review/cancellation pending
U Pending payment, only in the cashier payment

Contract status

ContractStatusEnum

Code Description
0 pending
1 enable
2 disable
3 cancelled

3ds risk strategy

Risk3dsStrategyEnum

Code Description
INNER Internal 3ds (using 3ds provided by Onerway)
EXTERNAL External 3ds (using 3ds provided by merchant)
NONE None (doesn't go 3ds)
DEFAULT Default (not passed as this value, depends on Onerway to judge whether it needs to go 3ds)

Customs code

CustomsCodeEnum

Code Description
GUANGZHOU Guangzhou Customs
HANGZHOU Hangzhou Customs
NINGBO Ningbo Customs
ZHENGZHOU_BS Zhengzhou (Bonded Logistics Center)
CHONGQING Chongqing Customs
SHANGHAI Shanghai Customs
SHENZHEN Shenzhen Customs
ZHENGZHOU_ZH_ZS Zhengzhou integrated Bonded Area
TIANJIN Tianjin Customs

Identification type

CredentialsTypeEnum

Code Description
ID_CARD ID card

Verify Department

VerifyDepartmentEnum

Code Description
CUP indicates that the clearing channel is Unionpay
NUCC indicates that the clearing channel is NetsUnion
OTHER indicates that the clearing channel is others

Chargeback Status

ChargebackStatusEnum

Code Description
NEW Indicates that a new chargeback occurs
FA In the first appeal
FAF The first appeal failed
FAS The first appeal success
FAT Timeout for first appeal
SA In the second appeal
SAF The second appeal failed
SAS The second appeal success
SAT Timeout for second appeal
ACCEPT Chargeback accepted
REVOKE Chargeback revoked
DELETE Deleted (only for notification of chargeback)

Language

LanguageEnum

Code Description
zh-cn Simplified Chinese
en English
de German
es Spanish
fr French
it Italian
nl Dutch
ko Korean
zh-tw Traditional Chinese
ja Japanese
th Thai
ar Arabic
ru Russian
sv Swedish
fi Finnish
pt Portuguese
pl Polish
no Norwegian

Eci

EciEnum

Code Description
00 Used by MasterCard. ACS service is not available or the card does not support 3D verification
01 Used by MasterCard. Cardholder or issuer has not registered 3D security verification service
02 Used by MasterCard. Cardholder 3D security verification passed
05 Used by Visa. Cardholder 3D security verification passed
06 Used by Visa. Cardholder or issuer has not registered 3D security verification service
07 Used by Visa. The ACS service is not available or the card does not support 3D verification

Token provider

TokenProviderEnum

Code Description
GooglePay Token provided by GooglePay, usually used in Google Pay scenarios
ApplePay Token provided by ApplePay, usually used in Apple Pay scenarios

Local payment method

LpmsTypeEnum

lpmsType Name Country(ISO) Currencys Required fields Single limit
Alipay+ Alipay+ Worldwide EUR, USD, GBP email, country
WeChat WeChat GB GBP email, country
Klarna Klarna AU, AT, BE, FI, FR, DE, GR, IE, IT, NL, PT, ES, CZ, DK, NO, PL, SE, CH, GB AUD, EUR, CZK, DKK, NOK, PLN, SEK, CHF, GBP email, country, language, products
Boleto Boleto BR BRL, EUR, USD email, country, identityNumber, province, street, city, postalCode
BankTransfer BankTransfer BR, PH BRL, EUR, USD, PHP email, country, identityNumber, province, street, city, postalCode, name
Banrisul Banrisul BR BRL, EUR, USD email, country, identityNumber, province, street, city, postalCode
Bradesco Bradesco BR BRL, EUR, USD email, country, identityNumber, province, street, city, postalCode
Banco do Brasil Banco do Brasil BR BRL, EUR, USD email, country, identityNumber, province, street, city, postalCode
Itau Itau BR BRL, EUR, USD email, country, identityNumber, province, street, city, postalCode
MercadoPago MercadoPago BR BRL, EUR, USD email, country, identityNumber, province, street, city, postalCode
PIX PIX BR BRL, EUR, USD email, country, identityNumber, province, street, city, postalCode
Servipag Servipag CL CLP, EUR, USD email, country
Sencillito Sencillito CL CLP, EUR, USD email, country
Webpay Webpay CL CLP, EUR, USD email, country
Multicaja Multicaja CL CLP, EUR, USD email, country
Baloto Baloto CO COP, EUR, USD email, country
EFT EFT CO COP, EUR, USD email, country, identityNumber, bankName
Efecty Efecty CO COP, EUR, USD email, country
SPEI SPEI MX MXN, USD email, country
OXXO OXXO MX MXN, USD email, country
OXXOPAY OXXOPAY MX MXN, USD email, country
MercadoPago MercadoPago MX MXN, USD email, country
PagoEfectivo PagoEfectivo PE PEN, USD email, country
safetypay-cash safetypay-cash PE PEN, USD email, country
safetypay-online safetypay-online PE PEN, USD email, country
PayU PayU PL,CZ PLN, CZK email, country
Przelewy24 Przelewy24 PL PLN email, country, bankName
safetypay-cash safetypay-cash EC USD email, country
safetypay-online safetypay-online EC USD email, country
Pagosnet Pagosnet BO BOB, USD email, country
SEPADD SEPADD AT, BE, BG, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HU, IE, IT, LV, LT, LU, MT, NL, PL, PT, RO, SK, SI, ES, SE, IS, LI, NO, AD, SM, MC, VA, PF, TF, GI, GG, IM, JE, BL, PM, CH, GB, WF EUR Cashier Payment: email, country
API Payment: email, country, IBAN		 0.10 EUR ~ 1,000 EUR
Sofort Sofort AT, BE, DE, NL, ES, CH EUR, CHF email, country
Giropay Giropay DE EUR email, country
iDEAL iDEAL NL AUD, CAD, DKK, EUR, GBP, HKD, NOK, SEK, USD email, country
Konbini Konbini JP JPY email, country
PayEasy PayEasy JP JPY email, country
POLi POLi AU AUD email, country
Bancontact Bancontact BE EUR email, country
OVO OVO ID IDR email, country
MyBank MyBank IT EUR email, country
Dragonpay Dragonpay Worldwide PHP email, country
Skrill Skrill Worldwide EUR, GBP, USD email, country
eNETS eNETS SG SG email, country
PayseraWallet PayseraWallet LT, LV, EE EUR email, country
LithuanianBanks LithuanianBanks LT EUR email, country
PaySafeCard PaySafeCard AT, AU, BE, BG, CA, CH, CY, CZ, DE, DK, ES, FI, FR, GB, GE, GI, GR, HR, HU, IE, IT, LI, LT, LU, MT, MX, NL, NZ, NO, PE, PL, PT, RO, SE, SI, SK, UY AUD, CAD, CHF, EUR, GBP, NOK, PLN, RON, SEK, USD email, country
Paysafecash Paysafecash AT, BE, CA, CH, CY, CZ, DK, ES, FR, GB, GR, HR, HU, IE, IT, LU, LT, MT, NL, PL, PT, RO, SE, SI, SK AUD, CAD, CHF, EUR, GBP, NOK, PLN, RON, SEK, USD email, country
Payconiq Payconiq BE, NL, LU EUR email, country
Trustly Trustly DE, DK, EE, ES, FI, GB, LT, LV, NL, NO, PL, SE, SK DKK, EUR, GBP, NOK, PLN, SEK email, country
GCash GCash PH PHP email, identityNumber, name 1 PHP ~ 10000 PHP (Equivalent)
GrabPay GrabPay PH PHP email, identityNumber, name >= 1 PHP
PayMaya PayMaya PH PHP email, identityNumber, name 1 PHP ~ 50000 PHP (Equivalent)
ELEVEN ELEVEN PH PHP email, identityNumber, name 1 PHP ~ 10000 PHP (Equivalent)
GrabPay GrabPay SG SG SGD country Min Value: 0.01
TrueMoney Wallet TrueMoney Wallet TH THB Cashier Payment: country
API Payment: country, phone		 Min Value: 20.00
Max Value: 100,000.00
Rabbit_Line_pay Rabbit Line Pay TH THB country Min Value: 20.00
Max Value: 150,000.00
PromptPay PromptPay TH THB country Min Value: 20.00
Max Value: 150,000.00
KRUNGSRI_ONLINE Krungsri Online TH THB country Min Value: 20.00
Max Value: 150,000.00
BUALUANG_IBANKING Bualuang iBanking TH THB country Min Value: 20.00
Max Value: 150,000.00
CITI_POINTS Pay with Points - Citi Rewards Points TH THB country Min Value: 20.00
Max Value: 150,000.00
K_PLUS K PLUS TH THB country Min Value: 20.00
Max Value: 150,000.00
MCASH MCASH MY MYR country Min Value: 1.00
Touch 'n Go eWallet Touch n Go MY MYR country Min Value: 1.00
ShopeePay ShopeePay MY MYR country Min Value: 1.00
Boost Boost MY MYR country Min Value: 1.00
BNI BNI VA ID IDR country Min Value: 1
Max Value: 10,000
MANDIRI Mandiri ATM ID IDR country Min Value: 1
Max Value: 10,000
Maybank Maybank VA ID IDR country Min Value: 1
Max Value: 10,000
PERMATA Permata VA ID IDR country Min Value: 1
Max Value: 10,000
BRI BRI VA ID IDR country Min Value: 1
Max Value: 10,000
CIMB CIMB VA ID IDR country Min Value: 1
Max Value: 10,000
OVO OVO ID IDR country Min Value: 1
Max Value: 10,000
DANA DANA ID IDR country Min Value: 1
Max Value: 10,000
QRIS Nobu Bank QRIS ID IDR country Min Value: 1
Max Value: 10,000
AKULAKU AKULAKU ID IDR country Min Value: 1
Max Value: 10,000
ShopeePay ShopeePay ID IDR country Min Value: 1
Max Value: 10,000
Konbini Konbini JP JPY country Min Value: 1
Max Value: 300,000
BankTransfer Bank Transfer Japan JP JPY Cashier Payment: country
API Payment: country, firstName, lastName, jpFirstName, jpLastName ,phone		 Min Value: 1
PayEasy PayEasy JP JPY Cashier Payment: country
API Payment: country, firstName, lastName, jpFirstName, jpLastName ,phone		 Min Value: 1
Max Value: 300,000
Paypay PayPay JP JPY country Min Value: 1
Max Value: 1,000,000
LINE_Pay LINE Pay JP JPY country Min Value: 1
Max Value: 1,000,000
Merpay merPay JP JPY country Min Value: 1
Max Value: 1,000,000
Rakuten_Pay Rakuten Pay JP JPY country Min Value: 100
Max Value: 9,999,999
BitCash Bit Cash JP JPY Cashier Payment: country
API Payment: country, prepaidNumber		 Min Value: 1
Max Value: 20,000
Net_Cash Net Cash JP JPY Cashier Payment: country
API Payment: country, prepaidNumber		 Min Value: 1
Max Value: 20,000
WebMoney Web Money JP JPY Cashier Payment: country
API Payment: country, prepaidNumber		 Min Value: 1
Max Value: 20,000
au au KDDI JP JPY country Min Value: 1
Max Value: 100,000
SoftBank SoftBank JP JPY country Min Value: 1
Max Value: 100,000
NTT_Docomo NTT Docomo JP JPY country Min Value: 1
Max Value: 100,000
Paidy Paidy JP JPY country Min Value: 1
Max Value: 1,000,000

EFT bank name

EFTBankNameEnum

bankName Description
banco_agrario BANCO AGRARIO
banco_av_villas BANCO AV VILLAS
banco_bbva_colombia_s.a. BANCO BBVA COLOMBIA S.A.
banco_caja_social BANCO CAJA SOCIAL
banco_colpatria BANCO COLPATRIA
banco_cooperativo_coopcentral BANCO COOPERATIVO COOPCENTRAL
banco_corpbanca_s.a BANCO CORPBANCA S.A
banco_davivienda BANCO DAVIVIENDA
banco_de_bogota BANCO DE BOGOTA
banco_de_occidente BANCO DE OCCIDENTE
banco_falabella_ BANCO FALABELLA
banco_gnb_sudameris BANCO GNB SUDAMERIS
banco_pichincha_s.a. BANCO PICHINCHA S.A.
banco_procredit BANCO PROCREDIT
bancolombia BANCOLOMBIA
bancoomeva_s.a. BANCOOMEVA S.A.
citibank_ CITIBANK
itau ITAU
nequi NEQUI

Przelewy24 bank name

Przelewy24BankNameEnum

bankName Description
20 Santander-Przelew24
26 P_ac_ z Inteligo
31 P_ac_ z iPKO (PKO BP)
33 BNP Paribas
43 Bank PEKAO S.A.
45 Credit Agricole
49 ING Bank _l_ski
52 Konto Inteligo
53 Bank PKO BP (iPKO)
54 Santander
64 Toyota Bank
65 Bank PEKAO S.A.
69 Volkswagen Bank
85 Bank Millennium
88 P_ac_ z Alior Bankiem
90 Nest Bank
95 Credit Agricole
99 P_ac_ z BO_
112 P_ac_ z ING
119 P_ac_ z CitiHandlowy
129 Alior - Raty
131 P_ac_ z Plus Bank
136 mBank - Raty
141 e-transfer Pocztowy24
143 Banki Sp—_dzielcze
144 Bank Nowy BFG S.A.
153 Getin Bank
154 BLIK
158 Noble Pay
161 P_ac_ z IdeaBank
185 EnveloBank
222 NestPrzelew
223 BNP Paribas P_ac_ z Pl@net
243 mBank - mTransfer
266 P24now
270 mBank (Us_ugaITP)
271 ING Bank Śląski (Us_uga ITP)
272 BNP Paribas (Us_uga ITP)
274 PKO BP (Us_uga ITP)
275 Santander (Us_uga ITP)
279 Inteligo (Us_uga ITP)
280 mBank - Raty