订单接口
包含代收/代付/充值/结算等订单接口
请求
请求地址
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 | 否 | 支出校验: 收款方银行名称 |
孟加拉請帶入：bkash / 其他地區請參照支持银行清单代码帶入 |
签名参数增加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: 支出，从账户中支付款项。