収納代行API

収納代行の注文作成と照会:項目・金額・注文状態

サーバーでローカルの業務注文を保存してから収納代行注文を作成します。通信タイムアウトや支払い結果不明の場合は、元の加盟店注文番号で照会してください。どちらの呼び出しにも加盟店番号、現在のミリ秒タイムスタンプ、サーバー側の署名が必要です。

この記事の目次

注文作成API:POST JSON

アドレスの例: https://gateway.example.com/api/pay/collect/create、メソッド: POST、リクエストヘッダー: Content-Type: application/json、文字コードはUTF-8です。例のドメインは実際に開通したゲートウェイに置き換えてください。

項目必須入力ルール
mchIdはいあなたの加盟店番号。例では文字列です。
wayCodeはい開通済みチャネルまたは集約コード。例では文字列です。
outTradeNoはい加盟店注文番号。同じ加盟店内で一意とし、ローカル注文に関連付けます。
amountはい注文金額の単位は分。整数 1000 は10.00元を表します。
currencyCodeいいえ通貨。既定値は CNY。
notifyUrlはい非同期通知先。例: https://merchant.example.com/pay/notify。
subjectいいえ商品タイトル。送信する場合は署名に含めます。
bodyいいえ商品説明。送信する場合は署名に含めます。
clientIpいいえクライアントIP。実際の状況に合わせて指定します。
reqTimeはい現在のミリ秒タイムスタンプ。例では整数です。
signはいバックエンドで生成する小文字のMD5署名。自分自身の計算には含めません。

金額はサーバーが信頼できる注文記録から決定し、フロントエンドから渡された価格をそのまま信用しないでください。注文金額を整数の分で保存し、10.00元を10分と入力する誤りや、未処理の二進浮動小数点値による金額計算を避けます。

注文作成:項目の例

JSON内の識別情報と署名はすべてプレースホルダーです。reqTime は実際のリクエストでは現在のミリ秒整数値にし、署名を再計算してから送信してください。

JSON項目の例
{
  "mchId": "MERCHANT_ID",
  "wayCode": "80001",
  "outTradeNo": "DEMO_COLLECT_001",
  "amount": 1000,
  "currencyCode": "CNY",
  "notifyUrl": "https://merchant.example.com/pay/notify",
  "subject": "DEMO_PRODUCT",
  "reqTime": "CURRENT_UNIX_MILLISECONDS",
  "sign": "RECOMPUTE_ON_YOUR_SERVER"
}
Pythonバックエンドでの組み立て
import os
import time
from wenfupay_collect_sign import sign_collect

payload = {
    "mchId": os.environ["MERCHANT_ID"],
    "wayCode": "80001",  # Use a code enabled for your merchant.
    "outTradeNo": "YOUR_UNIQUE_ORDER_NO",
    "amount": 1000,     # 1000 cents = CNY 10.00.
    "currencyCode": "CNY",
    "notifyUrl": "https://merchant.example.com/pay/notify",
    "reqTime": int(time.time() * 1000),
}
payload["sign"] = sign_collect(payload, os.environ["MD5_SECRET"])
# Send payload as JSON from your server to:
# API_BASE_URL + "/api/pay/collect/create"
cURLでの送信方法
curl --request POST "$API_BASE_URL/api/pay/collect/create" \
  --header "Content-Type: application/json; charset=UTF-8" \
  --data @collect-create.json

例で使うPython署名関数をダウンロード。計算規則:MD5署名と検証。

注文照会:署名してからクエリ文字列をエンコード

Python GETパラメーター
import os
import time
from urllib.parse import urlencode
from wenfupay_collect_sign import sign_collect

params = {
    "mchId": os.environ["MERCHANT_ID"],
    "outTradeNo": "YOUR_EXISTING_ORDER_NO",
    "reqTime": int(time.time() * 1000),
}
# Alternative lookup: replace outTradeNo with platform_order_no.
params["sign"] = sign_collect(params, os.environ["MD5_SECRET"])
query_url = (
    os.environ["API_BASE_URL"].rstrip("/")
    + "/api/pay/collect/query?" + urlencode(params)
)
# Send a server-side GET. Do not create another order on a timeout.

Alipay・WeChatとチャネルコードの選び方

80001 はAlipayの集約コード、90001 はWeChatの集約コードです。割り当てられた実チャネルコードも使用できます。集約では、関連付けられ、加盟店に権限があり、有効な実チャネルだけが候補になります。すべての加盟店で自動的に利用できるわけではありません。

サーバーで製品の決済選択肢を開通済みの wayCode に対応付けます。技術担当者が利用可能なコード、チャネル制限、テスト方法を確認するため、フロントエンドで内部ルーティング設定を把握する必要はありません。

上流で明確に未受理と確認できた場合に限り、集約ルーティングが次の候補を試すことがあります。タイムアウト、例外、結果不明の際はむやみに切り替えません。あなたのシステムでも元の注文を先に照会し、複数の注文が同時に支払われる事態を避けてください。

注文作成の応答を決済画面に接続

JSON応答の最上位には code、message、data および sign があります。正常な例の code は 0;data に含まれる項目: duplicate、id、platformOrderNo、orderStatus、payUrl、channelErrorMessage。

プラットフォーム注文番号を照会、通知の照合、突合のために保存します。実際に有効な payUrl を取得した場合だけ決済入口を表示してください。空の場合もあるため、決済ページのURLを自分で作ってはいけません。リンクのプロトコルと宛先ドメインを確認し、許可範囲は技術担当者との接続時に設定します。

code=0 は着金を意味しないため、コードや商品を直接提供してはいけません。プラットフォーム注文番号が取得できても、信頼できる支払い成功結果を待つ必要があります。完全なエラーコード処理と応答の署名検証は、接続テスト時に技術担当者が案内します。

照会API:GETで元の注文を確認

アドレスの例: https://gateway.example.com/api/pay/collect/query、メソッド: GET。実際の照会パラメーターで署名してから、標準のURLエンコードでクエリ文字列を作ります。

項目必須入力ルール
mchIdはい注文が属する加盟店番号。
outTradeNoいずれか一方加盟店注文番号。 platform_order_no のいずれか一方を指定します。
platform_order_noいずれか一方プラットフォーム注文番号。アンダースコアの名前に注意してください。
reqTimeはい今回の照会時点のミリ秒タイムスタンプ。
signはい今回のパラメーターから再生成し、注文作成の署名を再利用しません。

照会応答の data の例には platformOrderNo、merchantOrderNo、amount、currencyCode、orderStatus、payUrl が含まれます。リクエストの platform_order_no と応答の platformOrderNo は綴りが異なるため、パラメーターオブジェクトをそのまま共用しないでください。

照会応答の amount の単位と精度は、利用開始時に技術担当者が確認します。内部の金額基準へ明示的に変換してから照合し、注文作成時の分単位金額と直接比較しないでください。

注文状態と対応する業務処理

orderStatus意味製品側での処理
0支払い待ち支払い待ちを表示して計画的に照会し、商品は提供しません。
1決済成功信頼できる結果を照合してから冪等な提供処理へ進みます。
2支払い失敗失敗を記録し、再決済前に規則に従って元の注文を処理します。
3クローズ済み待機を終了し、注文と照合記録を保持します。
4期限切れ期限切れを表示し、再購入と例外的な入金は合意した方法で扱います。

HTTPタイムアウトは注文状態ではありません。「結果確認待ち」と記録して元の加盟店注文番号で照会してください。確認前に元のリクエストが必ず失敗したと判断したり、再採番で重複チェックを回避したりしてはいけません。

通知と照会で同じ決済処理関数を使用

  1. 元の注文を特定加盟店番号と加盟店注文番号でローカル記録を読み、所属する顧客と環境を確認します。
  2. 信頼できる結果を照合通知は先に署名検証し、照会は保護されたバックエンドリクエストを使って、接続仕様に従い応答を検証します。
  3. 冪等な更新を統一成功状態は一度だけ保存し、提供タスクには一意の業務キーを使います。
  4. 不一致を記録金額、通貨、状態が一致しない場合は提供を停止し、技術担当者と確認します。

続けて読む:署名ルールおよびコールバック処理の詳細。本文は稳付pay接続仕様に基づいています。

事業の内容に合わせて導入を確認

商品、注文量、決済方法、精算要件を伝え、インターフェース、資金の流れ、例外処理を一つずつ確認します。

稳付payに問い合わせる ↗