Skip to main content

建立付款交易

介面路徑​

請求方式API 路徑
POST{DOMAIN_NAME} /api/v1/trade/payment/create

請求電文​

Http.header 參數​

Content-TypeString必填
固定值：application/json
platformIdString選填
SLP 平台 ID，平台特店必填
merchantIdString必填
直連特店串接：SLP 分配的特店 ID；平台特店串接：SLP 分配的子特店 ID
apiKeyString必填
API 介面金鑰
requestIdString(32)必填
請求流水號，每個 HTTP 請求唯一
idempotentKeyString(32)選填
冪等 KEY

Http.body 封包​

acquirerTypeString(6)必填
串接模式，固定填：SDK
referenceOrderIdString(32)必填
特店訂單號
languageString(6)必填參考
語言
expireTimeInteger選填
部分付款方式支援，如 ATM 銀行轉帳等，單位 min
returnUrlString(256)必填
顧客付款完成之後回到特店的頁面
paySessionJSON String必填
PaySession相關，SDK 資訊，直接從 SDK 獲取傳入即可
passthroughString(256)選填
透傳資訊，response 原路回應
additionalDataMap選填
附加資訊

回應電文​

處理結果 http.statusCode​

* 500 /429 /400：處理異常​

codeString必填
錯誤碼，錯誤碼及錯誤描述詳情查看： Server 錯誤碼
msgString必填
錯誤描述，錯誤碼及錯誤描述詳情查看： Server 錯誤碼

* 200：處理成功​

acquirerTypeString(6)必填
串接模式，固定填：SDK
referenceOrderIdString(32)必填
特店訂單號
tradeOrderIdString(32)必填
SLP 付款交易訂單編號
sessionIdString(32)選填
SLP 結帳交易訂單編號
statusString(32)必填參考
付款狀態
subStatusString(32)必填參考
子付款狀態，採用手動請款時需要關注此參數；
actionTypeString(16)選填參考
指示下一步動作，對應 nextAction 欄位處理方式
nextActionNextAction選填
指示下一步動作，特店可忽略，傳送給 SDK 即可
additionalDataMap選填
附加資訊
POST/api/v1/trade/payment/create

sandbox api

https://api-sandbox.shoplinepayments.com/api/v1/trade/payment/create

live api

https://api.shoplinepayments.com/api/v1/trade/payment/create
請求電文範例
<?php
$url = 'https://api-sandbox.shoplinepayments.com/api/v1/trade/payment/create';

// 動態 requestId 與 referenceId
$referenceId = uniqid();
$requestId = uniqid();

// 正確格式的 headers 陣列
$headers = [
    "Content-Type: application/json",
    "merchantId: <YOUR-MERCHANT-ID>",
    "apiKey: <YOUR-API-KEY>",
    "requestId: $requestId"
];

// 正確格式的 Request Data
$data = [
    "acquirerType" => "SDK",
    "referenceOrderId" => $referenceId,
    "language" => "en",
    "amount" => [
        "value" => 100,
        "currency" => "TWD"
    ],
    "expireTime" => 60,
    "returnUrl" => "https://your-domain.com/return",
    "paySession" => "{}", //PaySession相關，SDK 資訊，直接從 SDK 獲取傳入即可
    "confirm" => [
        "paymentMethod" => "CreditCard",
        "paymentBehavior" => "Regular"
    ],
    "client" => [
        "ip" => "127.0.0.1",
    ],
    "order" => [
        "products" => [[
            "id" => "650815fd2a17ae0017f2d360",
            "name" => "ROYALPRO全分離乳清蛋白-綜合口味30入",
            "quantity" => 1,
            "amount" => [
                "value" => 100000,
                "currency" => "TWD"
            ],
            "sku" => "4329325836183615218",
            "desc" => "ROYALPRO全分離乳清蛋白-綜合口味30入",
            "url" => "https://www.shoplinepayments.com/product/4329325836183615218"
        ]],
        "shipping" => [
            "shippingMethod" => "宅配",
            "carrier" => "黑貓宅配",
            "personalInfo" => [
                "firstName" => "三",
                "lastName" => "張",
                "email" => "zhangsan@gmail.com",
                "phone" => "+8860287682010"
            ],
            "address" => [
                "countryCode" => "TW",
                "stateCode" => "",
                "state" => "",
                "city" => "台北市",
                "district" => "松山區",
                "street" => "敦化北路170號10樓 A室",
                "postcode" => "105405"
            ]
        ]
    ],
    "customer" => [
        "referenceCustomerId" => "referenceCustomerId",
        "type" => "0",
        "personalInfo" => [
            "firstName" => "三",
            "lastName" => "張",
            "email" => "zhangsan@gmail.com",
            "phone" => "+8860287682010"
        ]
    ],
    "billing" => [
        "personalInfo" => [
            "firstName" => "三",
            "lastName" => "張",
            "email" => "zhangsan@gmail.com",
            "phone" => "+8860287682010"
        ],
        "address" => [
            "countryCode" => "TW",
            "stateCode" => "",
            "state" => "",
            "city" => "台北市",
            "district" => "松山區",
            "street" => "敦化北路170號10樓 A室",
            "postcode" => "105405"
        ]
    ],
];
print_r($data);
$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => $headers
]);

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

// 回覆結果處理
$result = json_decode($response, true);
echo "HTTP Code: $httpCode";
print_r($result);
回應電文範例
{
  "tradeOrderId": "10010061012921418117718876160",
  "channelDealId": "CHANNEL_123",
  "status": "SUCCEEDED",
  "subStatus": "AUTHORIZED",
  "amount": {
    "value": 100000,
    "currency": "TWD"
  },
  "paidAmount": {
    "value": 100000,
    "currency": "TWD"
  },
  "nextAction": {
    "type": "Redirect",
    "url": "https://payment.example.com/checkout",
    "method": "GET",
    "data": ""
  },
  "lastPayment": {
    "brand": "Visa",
    "last4": "1234",
    "paymentMethod": "CreditCard",
    "paymentInstrument": {
      "paymentInstrumentId": "6456462132132",
      "savePaymentInstrument": true
    }
  },
  "customer": {
    "referenceCustomerId": "cust_ORDERID-123455677889990",
    "CustomerId": "12412dr133"
  }
}