订单接口

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

请求

请求地址

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	是	交易货币	twd(台币)/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" 在A2A模式下，必须提供国别代码。因此统一为必填。
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"

签名参数增加header

参数名称	类型	是否必须	描述	格式/示例
Content-Type	string	是		application/json
OC-Key	string	是	请客服提供
OC-Signature	string	是	通过计算获取

代收 bank_code:

代码示例

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。下面是这两种结果的格式说明和示例。

当请求处理成功时，接口将返回以下结构的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."
  }
}

订单查询

订单查询接口用于查询特定订单的状态和详情。通过向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: 支出，从账户中支付款项。