授權交易 / 付款結果通知 ReturnURL

應用場景

Server端方式(POST)(ReturnURL)
當特店會員信用卡交易完成後，特店接受綠界的信用卡授權結果訊息，並回應接收訊息。

Step1.綠界：以ServerPost方式傳送授權結果訊息至廠商的Server網址(ReturnURL)
Step2.特店：收到綠界的授權結果訊息，回應1|OK

注意事項：

1|OK僅是廠商回應綠界是否收到通知，並不會改變付款狀態。

HTTPS 傳輸協定

Accept ：text/html
Content Type：application/json
HTTP Method：POST

綠界Response參數說明 (Json格式)

MerchantID String(10)
特店編號

RpHeader Object
回傳資料

Timestamp Number
回傳時間

時間戳 Unix timestamp

TransCode Int
回傳代碼

1 代表 API 傳輸資料 (MerchantID, RqHeader, Data) 接收成功，實際的API執行結果狀態請參考 RtnCode 參數

TransMsg String(200)
回傳訊息

Data String
加密資料

此參數為加密過的 JSON 格式資料

綠界Response參數範例 (Json格式)

				
					{
    "MerchantID": "3002607",
    "RpHeader": {
        "Timestamp": 1234564848
    },
    "TransCode": 1,
    "TransMsg": "Success",
    "Data": "…"
}

Data參數說明(Json格式)

RtnCode Int
交易狀態

1 代表 API 執行成功，其餘代碼均為失敗，失敗代碼請參考交易訊息代碼表。

RtnMsg String(200)
回應訊息

MerchantID String(10)
特店編號

SimulatePaid Int
是否為模擬付款

當交易為模擬付款時，才會回傳此欄位。回傳值為:

1 : 代表此交易為模擬付款，並非是由消費者實際真的付款。所以綠界也不會撥款給特店，請勿對該筆交易做出貨等動作，以避免損失。

注意事項：

特店可透過廠商後台來針對單筆訂單模擬綠界回傳付款通知，以方便介接API
此功能僅只是用於測試ReturnURL是否能成功接收，不會改變付款狀態
只有透過廠商後台的定期定額查詢功能發動的模擬付款通知，綠界才會傳送此參數，正常由定期定額排程所發送的付款通知，不會傳送此參數

OrderInfo JSON
訂單資訊

MerchantTradeNo String(20)
特店交易編號

TradeNo String(20)
綠界交易編號

請保存綠界的交易編號與特店交易編號MerchantTradeNo的關聯。

TradeAmt Int
交易金額

TradeDate String(20)
訂單成立時間

格式為 yyyy/MM/dd HH:mm:ss

PaymentType String(20)
付款方式

Credit: 信用卡

PaymentDate String(20)
付款時間

格式為 yyyy/MM/dd HH:mm:ss

ChargeFee Number
手續費

TradeStatus String(8)
交易狀態

0 :代表交易訂單成立未付款
1 : 代表交易訂單成立已付款

CardInfo JSON
信用卡授權資訊

AuthCode String(6)
銀行授權碼

Gwsr Int
授權交易單號

ProcessDate String(20)
交易時間

格式為yyyy/MM/dd HH:mm:ss

Amount Int
金額

Stage Int
分期期數

使用信用卡分期時回傳

Stast Int
首期金額

使用信用卡分期時回傳

Staed Int
各期金額

Eci Int
3D(VBV) 回傳值

Eci=5,6,2,1 代表該筆交易為3D交易，且付款方式為銀聯卡時不回傳

Card6No String(6)
信用卡卡號前六碼

付款方式為銀聯卡時不回傳

Card4No String(4)
信用卡卡號末四碼

付款方式為銀聯卡時不回傳

RedDan Int
紅利扣點

使用信用卡紅利時回傳

RedOkAmt Int
實際扣款金額

使用信用卡紅利時回傳

RedYet Int
紅利剩餘點數

使用信用卡紅利時回傳

RedDeAmt Int
紅利折抵金額

使用信用卡紅利時回傳

PeriodType String(1)
週期種類

定期定額時回傳，訂單所設定的週期種類

Frequency Int
執行頻率

定期定額時回傳，訂單所設定的執行頻率

ExecTimes Int
執行次數

定期定額時回傳，訂單所設定的執行次數

PeriodAmount Int
訂單建立時的每次要授權金額

定期定額時回傳

TotalSuccessTimes Int
目前已成功授權的次數

定期定額時回傳，目前已成功授權的次數

TotalSuccessAmount Int
目前已成功授權的金額合計

定期定額時回傳

IssuingBank String(30)
銀行名稱

IssuingBankCode String(10)
銀行代碼

CustomField String(200)
自訂欄位

提供特店使用客制化欄位

Data參數範例(Json格式)

				
					{
    "RtnCode": 1,
    "RtnMsg": "Success",
    "PlatformID": "1234567890",
    "MerchantID": "1234567890",
    "CardInfo": {
        "Card6No": "123456",
        "Card4No": "1234",
        "CardValidYY": "25",
        "CardValidMM": "12",
        "AuthCode": "654123",
        "Gwsr": 125,
        "ProcessDate": "2022/09/18 15:39:10",
        "Amount": 2
        "Eci": 1,
    },
  "OrderInfo": {
        "MerchantTradeNo": "test123466",
        "TradeNo": "123456789",
        "PaymentDate": "2022/09/18 15:39:10",
        "TradeAmt": 2,
        "PaymentType": "Credit",
        "TradeDate": "2022/09/18 15:39:10",
        "ChargeFee": 0,
        "TradeStatus": "1",
    }
}

注意事項：

若未正確回應1|OK，系統會隔5~15分鐘後重發訊息給特店，當天重複發送四次。
若特店持續收到綠界回傳付款資訊，此時請檢查是否未正確回應1|OK給綠界，常見錯誤回傳值為(“1|OK”、1|ok、_OK 、1\OK、空白 )。
若遇消費者已付款，但未收到綠界回傳付款完成資訊，此時請檢查接收回傳參數的伺服器是否服務正常，導致無法接收。請參考：無法收到綠界回傳的付款結果通知
特店務必判斷交易狀態RtnCode是否為1，若非1時請勿對該筆交易做出貨動作，並取得交易訊息RtnMsg記錄失敗原因。

YAML

提供的 YAML 文件用於定義 API 的配置、結構、操作和基礎設施管理等資訊，方便開發人員理解和使用 API。

				
					openapi: 3.1.0
info:
  title: ECPay ReturnURL API
  version: 1.0.0
servers:
  - url: https://ecpayment-stage.ecpay.com.tw
    description: Testing environment
  - url: https://ecpayment.ecpay.com.tw
    description: Production environment
paths:
  /Cashier/ReturnURL:
    post:
      summary: Notification for transaction result
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                MerchantID:
                  type: string
                  maxLength: 10
                  description: Merchant ID
                RqHeader:
                  type: object
                  properties:
                    Timestamp:
                      type: integer
                      description: Transmission timestamp
                Data:
                  type: string
                  description: Encrypted data
              required:
                - MerchantID
                - RqHeader
                - Data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  MerchantID:
                    type: string
                    maxLength: 10
                    description: Merchant ID
                  RpHeader:
                    type: object
                    properties:
                      Timestamp:
                        type: integer
                        description: Response timestamp
                  TransCode:
                    type: integer
                    description: Transmission code
                  TransMsg:
                    type: string
                    maxLength: 200
                    description: Transmission message
                  Data:
                    type: string
                    description: Encrypted data

components:
  schemas:
    Data:
      type: object
      properties:
        RtnCode:
          type: integer
          description: Transaction status code
        RtnMsg:
          type: string
          maxLength: 200
          description: Response message
        MerchantID:
          type: string
          maxLength: 10
          description: Merchant ID
        SimulatePaid:
          type: integer
          description: Indicates if the transaction is simulated
        OrderInfo:
          type: object
          properties:
            MerchantTradeNo:
              type: string
              maxLength: 20
              description: Merchant trade number
            TradeNo:
              type: string
              maxLength: 20
              description: ECPay trade number
            TradeAmt:
              type: integer
              description: Trade amount
            TradeDate:
              type: string
              maxLength: 20
              description: Trade date
            PaymentType:
              type: string
              maxLength: 20
              description: Payment type
            PaymentDate:
              type: string
              maxLength: 20
              description: Payment date
            ChargeFee:
              type: number
              description: Charge fee
            TradeStatus:
              type: string
              maxLength: 8
              description: Trade status
            CardInfo:
              type: object
              properties:
                AuthCode:
                  type: string
                  maxLength: 6
                  description: Authorization code
                Gwsr:
                  type: integer
                  description: GWSR
                ProcessDate:
                  type: string
                  maxLength: 20
                  description: Process date
                Amount:
                  type: integer
                  description: Amount
                Stage:
                  type: integer
                  description: Installment stage
                Stast:
                  type: integer
                  description: First installment amount
                Staed:
                  type: integer
                  description: Each installment amount
                Eci:
                  type: integer
                  description: 3D secure ECI value
                Card6No:
                  type: string
                  maxLength: 6
                  description: First six digits of card number
                Card4No:
                  type: string
                  maxLength: 4
                  description: Last four digits of card number
                RedDan:
                  type: integer
                  description: Redeem points used
                RedOkAmt:
                  type: integer
                  description: Actual redeem amount
                RedYet:
                  type: integer
                  description: Remaining redeem points
                RedDeAmt:
                  type: integer
                  description: Redeem deduction amount
                PeriodType:
                  type: string
                  maxLength: 1
                  description: Period type
                Frequency:
                  type: integer
                  description: Execution frequency
                ExecTimes:
                  type: integer
                  description: Execution times
                PeriodAmount:
                  type: integer
                  description: Period amount
                TotalSuccessTimes:
                  type: integer
                  description: Total successful executions
                TotalSuccessAmount:
                  type: integer
                  description: Total successful amount
                IssuingBank:
                  type: string
                  maxLength: 30
                  description: Issuing bank name
                IssuingBankCode:
                  type: string
                  maxLength: 10
                  description: Issuing bank code
                CustomField:
                  type: string
                  maxLength: 200
                  description: Custom field

綠界官方網站