Order Interface

Request

Request URL

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

Basic Parameters

Parameter Name	Type	Required	Description	Format/Example
transaction_type	string	Yes	Transaction type	Choose one: income/expense
amount	string	Yes	Transaction amount	"100.00"
merchant_order_id	string	Yes	Merchant order ID	A unique order number generated by the merchant
merchant_uid	string	Yes	Merchant UID	Contact the administrator to obtain
currency	string	Yes	Transaction currency	cny (Chinese Yuan)/usd (US Dollar)/thb (Thai Baht)/vnd (Vietnamese Dong)/php (Philippine Peso)/sgd (Singapore Dollar)/idr (Indonesian Rupiah)/bdt (Bangladeshi Taka)
payment	string	Yes	Payment method	Visible in the merchant backend; after selecting the channel in the backend, all supported mode names will be visible
redirect_url	string	No	URL to redirect after transaction completion;	"https://example.com/redirect"
notify_url	string	No	Server-side notification URL	"https://example.com/notify"
response_type	string	Yes	Response type (e.g., return JSON or redirect)	Currently supports only: "json"; leave blank for 302 redirect
country	string	Yes	Country code	International standard country code abbreviation, e.g., "US" In A2A mode, the country code must be provided, thus it is uniformly required.
accounting_type	string	No	ccount type	recharge/receive/pay/settle
from	string	No	Income verification: Payer account	"6660006666789"
from_name	string	No	Income verification: Payer account	"John Doe"
from_bank_name	string	No	Income verification: Payer bank name	"Bank of Example"
to	string	No	Expense verification: Payee account	"6660006666987"
to_name	string	No	Expense verification: Payee name	"Jane Doe"
to_bank_name	string	No	Expense verification: Payee bank name	For Bangladesh, please Include parameters: bkash / nagad / rocket.  For other regions, refer to the support bank code list.

Signature Parameters Add Header

Parameter Name	Type	Required	Description	Format/Example
Content-Type	string	Yes		application/json
OC-Key	string	Yes	Please provide by customer service
OC-Signature	string	Yes	Obtained through calculation

Deposite bank_code:

Code Example

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();  
        }  
    }  
}

Response

Interface Return Value Document The interface response may contain two types of results: success and error. Below are the format descriptions and examples for these two types of results.

When the request is processed successfully, the interface will return JSON data in the following structure:

Field Name	Type	Description	Example Value
result	string	Operation result	"success"/"error"
data	interface{}	Operation return data	{"payment": {...}, "payment_url": "url"}

Payment Object Total JSON Field Description

• from: Sender's account number.
  
• from_name: Sender's account name.
• from_bank_name: Sender's bank name.
• to: Receiver's account number.
• to_name: Receiver's account name.
• to_bank_name: Receiver's bank name.
• payment_status: Payment status.
• payment_fail_reason: Reason for payment failure.
• final_amount: The final amount of the transaction.
• currency: The currency used for the transaction.
• transaction_type: Transaction type (income/expense).
• payment_uid: Unique identifier for the payment.
• channel: Transaction channel.

Code Example

// Successful response  
{  
  "result": "success",  
  "data": {  
    "payment": {  
      // Specific fields of payment information  
    },  
    "payment_url": "https://example.com/payments/checkout"  
  }  
}  
// With error  
{  
  "result": "error",  
  "data": "An error occurred processing your request"  
}  
// or  
{  
  "result": "error",  
  "data": {  
    "error": "Invalid parameters",  
    "details": "The 'amount' field is required."  
  }  
}

Order Inquiry

The order inquiry interface is used to query the status and details of a specific order. By sending a request to the API that includes the necessary authentication information and order identification information, you can receive a response with detailed information about the current status of the order, payment status, amount, etc.

Request URL

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

Request Parameters

When requesting the order inquiry interface, the following parameters need to be provided:

• merchant_order_id: Merchant order ID, which is a unique order number generated by the merchant at the time of order creation.

Return JSON Field Description

• from: Sender's account number.
• from_name: Sender's account name.
• from_bank_name: Sender's bank name.
• to: Receiver's account number.
• to_name: Receiver's account name.
• to_bank_name: Receiver's bank name.
• amount: Original amount of the order.
• final_amount: Final amount of the order.
• currency: Currency used for the transaction.
• country: Transaction country.
• transaction_type: Transaction type (income/expense).
• accounting_type: Accounting type (for income: receipt, recharge; for expense: payment, settlement).
• merchant_order_id: Merchant order number.
• merchant_uid: Merchant's unique identifier.
• merchant_name: Merchant name.
• channel: Transaction channel.
• payment_status: Payment status.
• payment_fail_reason: Reason for payment failure.
• payment: Payment method.
• response_type: Response type.
• ip: User IP address.
• user_agent: User agent.
• distribute_rules: Distribution rules.
• payment_uid: Unique identifier for the payment.
• redirect_url: Redirect URL.
• notify_url: Notification URL.
• notify_status: Notification status.
• notify_fail_reason: Reason for notification failure.
• accounting_status: Accounting status.
• accounting_fail_reason: Reason for accounting processing failure.
• signature_key: Signature key.

Code Example

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");  

            // Sort parameters by key and construct the query string  
            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();  
        }  
    }  
}

Common Enumeration Field Descriptions

Payment Status (payment_status)

The payment status reflects the current state of the order payment process.

• none: Default value, indicates that the status is not set.
• pending: Waiting, the order has been created but payment has not yet started.
• processing: In payment, payment is being processed.
• completed: Payment completed, indicates that the payment was successfully completed.
• failed: Payment failed, an error occurred during the payment process.
• reject: Payment rejected, payment failed verification or was rejected.
• refund: Withdrawal, payment has been refunded.
• overdue: Overdue, payment was not completed within the specified time.

Notification Status (notify_status)

The notification status is used to track the notification process of the order payment result.

• none: Default value, indicates that the status is not set.
• delivered: In notification, the notification has been sent but not confirmed received.
• completed: Notification completed, the recipient has successfully received the notification.
• failed: Notification failed, the notification could not be successfully delivered for some reason.

Accounting Status (accounting_status)

The accounting status reflects the current state of the order accounting process.

• none: Default value, indicates that the status is not set.
• delivered: In accounting, the accounting process is ongoing.
• accounted: Accounting completed, accounting has been successfully completed.
• failed: Accounting failed, a problem occurred during the accounting process.

Transaction Type (transaction_type)

The transaction type indicates the financial nature of the order, whether it is income or expense.

• income: Income, indicates that this order is an income.
• expense: Expense, indicates that this order is an expense.

Accounting Type (accounting_type)

The accounting type specifies the financial processing method for the transaction type.

• recharge: Recharge, refers to an increase in funds to the account.
• receive: Receipt, receiving funds from another party.
• settle: Settlement, completing payment settlement with the merchant or third party.
• pay: Expense, paying funds from the account.