VI | EN
Message us on Messenger
Developer resources

Escrow nhiều đơn — Shopee API

v2.payment.get_escrow_detail_batch · call it through Quantri360 with one API key for your own accounts / assets that you connected and authorized — 360 handles request signing and refreshing the authorization you granted.

v2.payment.get_escrow_detail_batch

POST/api/v2/payment/get_escrow_detail_batchVia 360: POST https://partner.quantri360.com/v1/shopee/api/v2/payment/get_escrow_detail_batch
Description

Chi tiết tiền của tối đa 50 đơn trong một lần gọi: khách trả bao nhiêu, giảm giá của shop / Shopee, từng khoản phí sàn (cố định, dịch vụ, thanh toán, affiliate…), phí vận chuyển và số tiền người bán thực nhận (escrow_amount). Bản theo lô của get_escrow_detail.

  • Gọi bằng POST, body JSON.
  • Đối chiếu (ví dụ thật): 275.600 tiền hàng − 48.506 phí cố định − 18.158 phí dịch vụ − 16.536 phí thanh toán − 2.436 hoa hồng affiliate − 2.700 phí bảo hiểm vận chuyển = 187.264 = escrow_amount (phí ship 41.000 được Shopee trợ đủ).
  • Quá 50 mã → exceed_max_limit. Nhiều trường chỉ có ở thị trường khác (BR, ID, MY, SG…) và luôn bằng 0 với gian hàng VN.

Request

Endpoint

POST https://partner.quantri360.com/v1/shopee/api/v2/payment/get_escrow_detail_batch

Authentication & shop

NameInTypeSampleDescription
AuthorizationheaderheaderBearer q360_live_ab12cd34_…Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand.
platform_shop_idquerystring100001Gian hàng (lấy ở GET /v1/platforms → shops[].platform_shop_id). BẮT BUỘC khi brand có > 1 gian hàng trên nền tảng; 360 bỏ tham số này trước khi chuyển tiếp.

Request parameters

NameInTypeRequiredSampleDescription
order_sn_listbodystring[]Yes["2610230ABCDE15","2610270ABCDE07"]Mã đơn, 1–50 (khuyến nghị ≤ 20 mỗi lần để phản hồi nhanh).

Request examples

curl -s -X POST "https://partner.quantri360.com/v1/shopee/api/v2/payment/get_escrow_detail_batch" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_sn_list":["2610230ABCDE15","2610270ABCDE07"]}'
Python
import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.post(
    "https://partner.quantri360.com/v1/shopee/api/v2/payment/get_escrow_detail_batch",
    params={},
    json={
        "order_sn_list": [
            "2610230ABCDE15",
            "2610270ABCDE07"
        ]
    },
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=60,
)
print(r.status_code)
print(r.json())
Node.js
const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/shopee/api/v2/payment/get_escrow_detail_batch');
for (const [k, v] of Object.entries({})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
  method: 'POST',
  headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({"order_sn_list":["2610230ABCDE15","2610270ABCDE07"]}),
});
console.log(r.status, await r.json());
PHP
<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/shopee/api/v2/payment/get_escrow_detail_batch' . '?' . http_build_query([]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key, 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"order_sn_list":["2610230ABCDE15","2610270ABCDE07"]}');
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;

Response

Response fields (as returned by Shopee)

NameTypeSampleDescription
request_idstringd52ca43b277a4f9292fb8be658bfd33dMã request của Shopee để tra lỗi.
errorstringMã lỗi Shopee; rỗng = thành công.
messagestringMô tả lỗi.
responseobject[]Mỗi phần tử một đơn.
escrow_detailobject
order_snstring2610230ABCDE15Mã đơn.
buyer_user_namestringnguoimua123Tên tài khoản người mua.
return_order_sn_liststring[][]Mã yêu cầu trả hàng của đơn (nếu có).
order_incomeobjectDòng tiền của đơn (khoảng 90 trường; dưới đây là các trường dùng với gian hàng VN).
escrow_amountfloat187264Người bán THỰC NHẬN. Có thể đổi tới khi đơn hoàn tất (trả hàng, điều chỉnh phí).
order_original_pricefloat689000Giá gốc (trước mọi giảm giá).
order_seller_discountfloat413400Shop giảm giá.
cost_of_goods_soldfloat275600Tiền hàng sau giảm giá của shop.
voucher_from_sellerfloat0Voucher của shop.
voucher_from_shopeefloat50000Voucher Shopee tài trợ (không trừ vào người bán).
buyer_total_amountfloat225600Khách thực trả.
commission_feefloat48506Phí cố định.
service_feefloat18158Phí dịch vụ (Freeship Xtra, Voucher Xtra…).
seller_transaction_feefloat16536Phí thanh toán.
order_ams_commission_feefloat2436Hoa hồng affiliate (đơn qua tiếp thị liên kết).
shipping_seller_protection_fee_amountfloat2700Phí bảo hiểm / dịch vụ vận chuyển người bán đăng ký.
actual_shipping_feefloat41000Phí vận chuyển thực.
shopee_shipping_rebatefloat41000Shopee trợ giá vận chuyển.
buyer_paid_shipping_feefloat0Khách trả phí ship.
reverse_shipping_feefloat0Phí vận chuyển chiều hoàn (đơn trả hàng).
withholding_vat_taxfloat0Thuế GTGT Shopee khấu trừ (hộ / cá nhân kinh doanh).
withholding_pit_taxfloat0Thuế TNCN Shopee khấu trừ.
itemsobject[]Từng dòng hàng: item_id, item_name, item_sku, model_id, model_name, model_sku, quantity_purchased, original_price, discounted_price, discount_from_voucher_shopee / _seller, ams_commission_fee, activity_type (bundle_deal / add_on_deal), promotion_list.
buyer_payment_infoobjectẢnh chụp lúc đặt hàng (không cập nhật sau trả hàng / hủy): buyer_payment_method, buyer_total_amount, merchant_subtotal, shopee_voucher, seller_voucher, shipping_fee…

Response sample

{
  "error": "",
  "message": "",
  "request_id": "08ba69875ef335f8…",
  "response": [
    {
      "escrow_detail": {
        "order_sn": "2610230ABCDE15",
        "buyer_user_name": "nguoimua123",
        "return_order_sn_list": [],
        "order_income": {
          "escrow_amount": 187264,
          "order_original_price": 689000,
          "order_seller_discount": 413400,
          "cost_of_goods_sold": 275600,
          "voucher_from_shopee": 50000,
          "buyer_total_amount": 225600,
          "commission_fee": 48506,
          "service_fee": 18158,
          "seller_transaction_fee": 16536,
          "order_ams_commission_fee": 2436,
          "shipping_seller_protection_fee_amount": 2700,
          "actual_shipping_fee": 41000,
          "shopee_shipping_rebate": 41000,
          "items": [
            {
              "item_id": 10000000077,
              "item_name": "Áo sơ mi nữ công sở cổ nơ",
              "model_name": "Trắng,L",
              "model_sku": "WAKBD1016-Màu 1-L",
              "quantity_purchased": 1,
              "original_price": 689000,
              "discounted_price": 275600,
              "ams_commission_fee": 2436
            }
          ]
        },
        "buyer_payment_info": {
          "buyer_payment_method": "ShopeePay Linked Bank Account",
          "buyer_total_amount": 225600,
          "merchant_subtotal": 275600,
          "shopee_voucher": -50000
        }
      }
    }
  ]
}

Shopee error codes (11)

Show
CodeMeaning
error_dataDữ liệu không tồn tại hoặc không hợp lệ cho thao tác (vd mã không có, loại yêu cầu không cho phép).
error_paramTham số sai / thiếu / sai kiểu — xem `message` để biết tham số nào.
error_serverLỗi hệ thống Shopee — thử lại sau ít phút.
error_shopGian hàng không hợp lệ — kiểm tra platform_shop_id.
exceed_max_limitVượt số phần tử tối đa của một lần gọi (vd > 50 mã đơn).
common.error_not_foundKhông tìm thấy thông tin.
error_authỦy quyền gian hàng cho 360 đã hết hạn hoặc bị thu hồi (360 đã tự làm mới token một lần) — chủ gian hàng kết nối lại Shopee trong Partner.
error_limitChạm hạn mức gọi Shopee trong ngày của kết nối — 360 trả kèm thời điểm thử lại; giảm tần suất gọi.
error_rate_limitGọi quá nhanh — chờ vài giây rồi gọi lại (360 cũng giới hạn theo key: 429 + Retry-After).
shop_bannedGian hàng đang bị Shopee khóa — mọi API tạm ngưng tới khi gỡ khóa.
error_kyc_authGian hàng chưa hoàn tất đăng ký người bán trên Kênh Người Bán.

Get started

  1. Sign up for Partner
  2. Enable a data type of the Tài chính / đối soát group on the platform page
  3. Create an API key (tick the Shopee channel)
  4. Call it as in the examples above