订单接口

包含代收/代付/充值/结算等订单接口

请求

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.*;

public class Main {
    private static final String API_KEY = "API_KEY";
    private static final String API_SECRET = "API_SECRET";
    private static final String MerchantUID = "Merchant_UID";
    private static final String API_URL = "https://DOMAIN/octopus/api/order/new";

    public static void main(String[] args) {
        try {
            Map<String, String> data = new TreeMap<>();
            data.put("transaction_type", "income");
            data.put("amount", "100.00");
            data.put("currency", "php");
            data.put("payment", "gcash");
            data.put("merchant_order_id", "123qq");
            data.put("merchant_uid", MerchantUID);
            data.put("redirect_url", "https://example.com/redirect");
            data.put("notify_url", "https://example.com/notify");
            data.put("response_type", "json");
            data.put("country", "ph");

            StringBuilder dataString = new StringBuilder();
            for (Map.Entry<String, String> entry : data.entrySet()) {
                if (dataString.length() > 0) dataString.append("&");
                dataString.append(entry.getKey()).append("=").append(entry.getValue());
            }

            Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
            SecretKeySpec secret_key = new SecretKeySpec(API_SECRET.getBytes(), "HmacSHA256");
            sha256_HMAC.init(secret_key);
            String signature = javax.xml.bind.DatatypeConverter.printHexBinary(sha256_HMAC.doFinal(dataString.toString().getBytes())).toLowerCase();

            URL url = new URL(API_URL);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("OC-Key", API_KEY);
            conn.setRequestProperty("OC-Signature", signature);
            conn.setDoOutput(true);

            String jsonInputString = new JSONObject(data).toString();
            try(OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonInputString.getBytes("utf-8");
                os.write(input, 0, input.length);           
            }

            // Read the response ...
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

请求地址

http POST https://DOMAIN/octopus/api/order/new

基本参数

参数名称	类型	是否必须	描述	格式/示例
transaction_type	string	是	交易类型	二选一: income(收入)/expense(支出)
amount	string	是	交易金额	"100.00"
merchant_order_id	string	是	商户订单ID	商户自行生成的唯一订单号
merchant_uid	string	是	商户UID	联系管理员获得
currency	string	是	交易货币	cny(人民币)/usd(美元)/thb(泰铢)/vnd(越南盾)/php(菲律宾比索)/sgd(新加坡元)/idr(印尼盾)/bdt(孟加拉国塔卡)
payment	string	否	支付方式	商户后台可见，在商户后台勾选渠道后，可见支持的所有模式名称
redirect_url	string	否	交易完成后重定向的URL，银河渠道为必填	"https://example.com/redirect"
notify_url	string	否	服务器端通知URL	"https://example.com/notify"
response_type	string	否	响应类型（如返回JSON或重定向等）	目前仅支持:"json" 留空则为302重定向
country	string	否	国家代码	国际标准国家代码缩写，例如："US"
accounting_type	string	否	记账类型	recharge(充值)/receive(收款)/pay(付款)/settle(结算)
from	string	否	收入校验: 付款方账户	"6660006666789"
from_name	string	否	收入校验: 付款方名称	"John Doe"
from_bank_name	string	否	收入校验: 付款方银行名称	"Bank of Example"
to	string	否	支出校验: 收款方账户	"6660006666987"
to_name	string	否	支出校验: 收款方名称	"Jane Doe"
to_bank_name	string	否	支出校验: 收款方银行名称	"Example Bank"

卡转卡附加参数

这是采用卡转卡时，额外需要提供的参数

参数名称	类型	是否必须	描述	格式/示例
additional	string	否	收款附言	"any words"
float_precision	string	否	浮动金额范围代收浮动范围（2代表在正的2位小数范围内，-2代表在负的2位小数范围内）	"-2"
ttl	string	否	超时时间，以秒为单位	1200

Tianci渠道附加说明

tianci渠道代付时，需要提供以下参数

参数名称	类型	是否必须	描述	格式/示例
to_bank_name	string	是	收款银行编号	可以从后台查询。选择Thaiqr，查询代付银行列表，并且选择对应的银行编号
to_name	string	是	收款人姓名	"John Doe"
to	string	是	收款人账号	"6660006666987"

银河附加参数

这是采用银河渠时，额外需要提供的参数

参数名称	类型	是否必须	描述	格式/示例
bank_code	string	否	银行编号	"gcash"
remark	string	否	备注信息	"test"
ttl	string	否	超时时间，以秒为单位	1200

代收 bank_code:

gcash
PMP: PayMaya
UBP: UnionBank
USDT-TRC: usdt-trc

代付 bank_code:

bpi: BPI / BPI Family Savings Bank
Unibank: BDO Unibank, Inc.
mbt: Metropolitan Bank and Trust Co.
LBOB: LANDBANK / OFBank
SBC: Security Bank Corporation
UBP: Union Bank of the Philippines
PNB: Philippine National Bank (PNB)
CBC: China Banking Corporation
EWBC: East West Banking Corporation
RCBC: RCBC/DiskarTech
PSB: Philippine Savings Bank
AUB: Asia United Bank Corporation
PBC: Philippine Bank of Communications
DBP: Development Bank of the Philippines
RBB: Robinsons Bank Corporation
APY: Alipay / Lazada Wallet
AB: AllBank (A Thrift Bank), Inc.
BM: Bangko Mabuhay
BCH: Bank of China
BC: Bank of Commerce
BK: BanKo, A Subsidiary of BPI
BNB: BDO NeTwork Bank
BRB: Binangonan Rural Bank / BRBDigital
CB: Camalig Bank
CARD Bank: CARD Bank Inc.
SME: CARD SME Bank
CLB: Cebuana Lhuillier Bank / Cebuana Xpress
CBS: China Bank Savings, Inc.
CPI: CIMB Philippines, Inc.
Bayad: CIS Bayad Center / Bayad
CTBC: CTBC Bank (Philippines) Corporation
DCP: DCPay / COINS.PH
DCDB: Dumaguete City Development Bank
DB: Dungganon Bank (A Microfinance Rural Bank), Inc.
Komo: East West Rural Bank / Komo
ERB: Entrepreneur Rural Bank, Inc./ENTRP
ESB: Equicom Savings Bank, Inc.
GOT: GoTyme Bank
GP: GrabPay
IRI: I-Remit / iCASH
IEM: Infoserve / Nationlink
ISLA: ISLA Bank (A Thrift Bank), Inc.
LSB: Legazpi Savings Bank
LDB: Luzon Development Bank
MBS: Malayan Bank Savings and Mortgage Bank, Inc.
MYA: Maya Bank, Inc.
PMP: Maya Philippines, Inc./Maya Wallet
MBP: Maybank Philippines, Inc.
MCCB: Mindanao Consolidated CoopBank
NB: Netbank
OP: OmniPay, Inc.
PAS: Pacific Ace Savings Bank
PPS: PalawanPay
PRB: Partner Rural Bank (Cotabato), Inc.
PBB: Philippine Business Bank, Inc., A Savings Bank
PTC: Philippine Trust Company
PDB: Producers Bank
QB: Queenbank
QCRB: Quezon Capital Rural Bank
Asenso: Rural Bank of Guinobatan / Asenso
SB: Seabank
SP: ShopeePay
SCB: Standard Chartered Bank
STP: Starpay
SLB: Sterling Bank of Asia, Inc (A Savings Bank)
SSB: Sun Savings Bank, Inc.
TC: TayoCash
TDB: Tonik Bank
TPI: TraxionPay/DigiCOOP/COOPNET
USB: UCPB Savings Bank
UDB: UnionDigital Bank
UNO: UNObank
USSC: USSC Money Services
VB: Veterans Bank
WDB: Wealth Development Bank
TYB: Yuanta Savings Bank Philippines, Inc.
JC: Zybi Tech Inc. / JuanCash

代码示例

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.*;

public class Main {
    private static final String API_KEY = "API_KEY";
    private static final String API_SECRET = "API_SECRET";
    private static final String MerchantUID = "Merchant_UID";
    private static final String API_URL = "https://DOMAIN/octopus/api/order/new";

    public static void main(String[] args) {
        try {
            Map<String, String> data = new TreeMap<>();
            data.put("transaction_type", "income");
            data.put("amount", "100.00");
            data.put("currency", "php");
            data.put("payment", "gcash");
            data.put("merchant_order_id", "123qq");
            data.put("merchant_uid", MerchantUID);
            data.put("redirect_url", "https://example.com/redirect");
            data.put("notify_url", "https://example.com/notify");
            data.put("response_type", "json");
            data.put("country", "ph");

            StringBuilder dataString = new StringBuilder();
            for (Map.Entry<String, String> entry : data.entrySet()) {
                if (dataString.length() > 0) dataString.append("&");
                dataString.append(entry.getKey()).append("=").append(entry.getValue());
            }

            Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
            SecretKeySpec secret_key = new SecretKeySpec(API_SECRET.getBytes(), "HmacSHA256");
            sha256_HMAC.init(secret_key);
            String signature = javax.xml.bind.DatatypeConverter.printHexBinary(sha256_HMAC.doFinal(dataString.toString().getBytes())).toLowerCase();

            URL url = new URL(API_URL);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("OC-Key", API_KEY);
            conn.setRequestProperty("OC-Signature", signature);
            conn.setDoOutput(true);

            String jsonInputString = new JSONObject(data).toString();
            try(OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonInputString.getBytes("utf-8");
                os.write(input, 0, input.length);           
            }

            // Read the response ...
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

响应

接口返回值文档接口响应可能包含两种结果类型：success和error。下面是这两种结果的格式说明和示例。

// 成功的响应
{
  "result": "success",
  "data": {
    "payment": {
      // 支付信息的具体字段
    },
    "payment_url": "https://example.com/payments/checkout"
  }
}
// 有错误
{
  "result": "error",
  "data": "An error occurred processing your request"
}
//或
{
  "result": "error",
  "data": {
    "error": "Invalid parameters",
    "details": "The 'amount' field is required."
  }
}

当请求处理成功时，接口将返回以下结构的JSON数据：

字段名	类型	描述	示例值
result	string	操作结果	"success"/"error"
data	interface{}	操作返回的数据	{"payment": {...}, "payment_url": "url"}

payment对象总json字段说明

from：发送方的账户号码。
from_name：发送方的账户名称。
from_bank_name：发送方的银行名称。
to：接收方的账户号码。
to_name：接收方的账户名称。
to_bank_name：接收方的银行名称。
payment_status：支付状态。
payment_fail_reason：支付失败原因。
final_amount：交易的最终金额。
currency：交易使用的货币种类。
transaction_type：交易类型（收入/支出）。
payment_uid：支付的唯一标识。
channel：交易渠道。

代码示例

// 成功的响应
{
  "result": "success",
  "data": {
    "payment": {
      // 支付信息的具体字段
    },
    "payment_url": "https://example.com/payments/checkout"
  }
}
// 有错误
{
  "result": "error",
  "data": "An error occurred processing your request"
}
//或
{
  "result": "error",
  "data": {
    "error": "Invalid parameters",
    "details": "The 'amount' field is required."
  }
}

订单查询

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.*;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.json.JSONObject;

public class OrderQuery {
    private static final String API_KEY = "API_KEY";
    private static final String API_SECRET = "API_SECRET";
    private static final String API_URL = "https://DOMAIN/octopus/api/order/get";

    public static void main(String[] args) {
        try {
            Map<String, String> params = new HashMap<>();
            params.put("merchant_order_id", "12345611");

            // 对参数按键排序并构造查询字符串
            List<String> keys = new ArrayList<>(params.keySet());
            Collections.sort(keys);
            StringBuilder dataToSign = new StringBuilder();
            for (String key : keys) {
                if (dataToSign.length() > 0) {
                    dataToSign.append("&");
                }
                dataToSign.append(key).append("=").append(params.get(key));
            }

            Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
            SecretKeySpec secret_key = new SecretKeySpec(API_SECRET.getBytes(), "HmacSHA256");
            sha256_HMAC.init(secret_key);
            String signature = javax.xml.bind.DatatypeConverter.printHexBinary(sha256_HMAC.doFinal(dataToSign.toString().getBytes())).toLowerCase();

            String dataString = new JSONObject(params).toString();

            URL url = new URL(API_URL);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("OC-Key", API_KEY);
            conn.setRequestProperty("OC-Signature", signature);
            conn.setDoOutput(true);

            try(OutputStream os = conn.getOutputStream()) {
                byte[] input = dataString.getBytes("utf-8");
                os.write(input, 0, input.length);           
            }

            // Read the response...

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

订单查询接口用于查询特定订单的状态和详情。通过向API发送请求，包含必要的身份验证信息和订单识别信息，可以接收关于订单的当前状态、付款状态、金额等详细信息的响应。

请求地址

http POST https://DOMAIN/octopus/api/order/get

请求参数

请求订单查询接口时，需要提供以下参数：

merchant_order_id: 商户订单ID，这是在创建订单时由商户自行生成的唯一订单号。

返回 JSON 字段说明

from：发送方的账户号码。
from_name：发送方的账户名称。
from_bank_name：发送方的银行名称。
to：接收方的账户号码。
to_name：接收方的账户名称。
to_bank_name：接收方的银行名称。
amount：订单的原始金额。
final_amount：订单的最终金额。
currency：交易使用的货币种类。
country：交易国家。
transaction_type：交易类型（收入/支出）。
accounting_type：会计类型（对于收入：接收、充值；对于支出：支付、结算）。
merchant_order_id：商户订单号。
merchant_uid：商户的唯一标识。
merchant_name：商户名称。
channel：交易渠道。
payment_status：支付状态。
payment_fail_reason：支付失败原因。
payment：支付方式。
response_type：响应类型。
ip：用户IP地址。
user_agent：用户代理。
distribute_rules：分配规则。
payment_uid：支付的唯一标识。
redirect_url：重定向URL。
notify_url：通知URL。
notify_status：通知状态。
notify_fail_reason：通知失败原因。
accounting_status：会计状态。
accounting_fail_reason：会计处理失败原因。
signature_key：签名密钥。

代码示例

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.*;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.json.JSONObject;

public class OrderQuery {
    private static final String API_KEY = "API_KEY";
    private static final String API_SECRET = "API_SECRET";
    private static final String API_URL = "https://DOMAIN/octopus/api/order/get";

    public static void main(String[] args) {
        try {
            Map<String, String> params = new HashMap<>();
            params.put("merchant_order_id", "12345611");

            // 对参数按键排序并构造查询字符串
            List<String> keys = new ArrayList<>(params.keySet());
            Collections.sort(keys);
            StringBuilder dataToSign = new StringBuilder();
            for (String key : keys) {
                if (dataToSign.length() > 0) {
                    dataToSign.append("&");
                }
                dataToSign.append(key).append("=").append(params.get(key));
            }

            Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
            SecretKeySpec secret_key = new SecretKeySpec(API_SECRET.getBytes(), "HmacSHA256");
            sha256_HMAC.init(secret_key);
            String signature = javax.xml.bind.DatatypeConverter.printHexBinary(sha256_HMAC.doFinal(dataToSign.toString().getBytes())).toLowerCase();

            String dataString = new JSONObject(params).toString();

            URL url = new URL(API_URL);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("OC-Key", API_KEY);
            conn.setRequestProperty("OC-Signature", signature);
            conn.setDoOutput(true);

            try(OutputStream os = conn.getOutputStream()) {
                byte[] input = dataString.getBytes("utf-8");
                os.write(input, 0, input.length);           
            }

            // Read the response...

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

常用枚举字段说明

支付状态 (payment_status)

支付状态反映了订单支付过程的当前状态。

none: 默认值，表示状态未设置。
pending: 等待中，订单已创建但支付尚未开始。
processing: 支付中，支付正在处理。
completed: 支付完成，表示支付成功结束。
failed: 支付失败，支付过程中遇到错误。
reject: 支付拒绝，支付未能通过验证或被拒绝。
refund: 撤回，已对支付进行退款处理。
overdue: 逾期，支付未在规定时间内完成。

通知状态 (notify_status)

通知状态用于追踪订单支付结果的通知过程。

none: 默认值，表示状态未设置。
delivered: 通知中，通知已发送但未确认接收。
completed: 通知完成，接收方已成功接收通知。
failed: 通知失败，由于某些原因通知未能成功送达。

记账状态 (accounting_status)

记账状态反映了订单记账处理的当前状态。

none: 默认值，表示状态未设置。
delivered: 记账中，记账处理正在进行中。
accounted: 记账完成，记账成功完成。
failed: 记账失败，记账过程中出现问题。

交易类型 (transaction_type)

交易类型指明了订单的财务性质，是收入还是支出。

income: 收入，表示此订单为收入。
expense: 支出，表示此订单为支出。

记账类型 (accounting_type)

记账类型具体化了交易类型的财务处理方式。

recharge: 充值，指向账户的资金增加。
receive: 收款，从其他方收到款项。
settle: 结算，完成与商户或第三方的款项结算。
pay: 支出，从账户中支付款项。