信用卡幕後授權API技術文件

請款與退款 / 信用卡請退款功能

應用場景

當收到訂單授權成功，透由查詢信用卡單筆明細記錄API取得交易狀態，再依交易狀態發動欲執行動作

❗ 注意事項：若「每日自動關帳」開啟時，每天 20:15 ~ 20:30 請勿執行此API。

請款使用說明

1. 信用卡付款成功，查詢訂單會顯示[已授權] (此時僅會占用信用卡額度)，如果此筆訂單要送至銀行請款，須執行[關帳](Action=C)。
2. 執行[關帳]後，查詢訂單會顯示[要關帳]，表示綠界將要向銀行進行請款作業。
3. 當綠界已向銀行完成[請款]作業，查詢訂單會顯示[已關帳]。

退款使用方式

1. 呼叫查詢信用卡單筆明細紀錄API取得狀態
2. 查詢後，呼叫信用卡請退款API:

  • [已授權]階段: 執行[放棄] (Action=N)可釋放信用卡佔額。
  • [要關帳]階段:

       i. 全額退款: 先執行[取消] (Action=E)，接著進行[放棄] (Action=N)。
       ii. 部份退款: 執行[退刷] (Action=R)。

  • [已關帳]階段: 執行[退刷] (Action=R)。

「關帳 」：授權請/退款。

❗ 注意事項：

  1. 若「每日自動關帳」開啟時，每日20:15系統會自行關帳，綠界依關帳後的金額向銀行請/退款。
  2. 若於廠商後台將系統「每日自動關帳」關閉以後，訂單仍須於21天內完成關帳作業，若於21天內未完成手動關帳作業，後續將無法以API方式進行關帳；至第80天仍未手動關帳，將發送信用卡未完成關帳通知；超過90天系統會將未關帳訂單進行放棄作業，不作請款。
  3. 產生錯誤訊息「error_overDate」須通知客服協助關帳。
  4. 若為銀聯卡交易時，授權完成會立即關帳。

「退刷」：在系統關帳或自行關帳後，可修改訂單金額。

❗ 注意事項：

  1. 修改上限為訂單金額。
  2. 分期的交易一定得全額退刷，一般授權才能作部份金額退刷。
  3. 紅利折抵交易須全額退刷，僅一般交易才可退刷部分金額。
  4. 如帳戶餘額低於退刷金額，將無法退刷，建議留存一定金額於綠界帳戶或至廠商後台預存綠界帳戶餘額供退刷之用。

「取消」：可用於取消關帳，訂單將會回復到前一個的狀態。

「放棄」：適用在關帳前放棄此筆交易，不做請款。

❗ 注意事項：

  1. 此API不支援定期定額「停用收款」功能，若要停用定期定額收款請使用定期定額訂單作業API或登入廠商後台進行操作，系統路徑為信用卡收單>定期定額查詢＞明細／編輯。
  2. 不支援部分金額退款，一律會以訂單全額進行退款

API介接網址

  • 測試環境：因無法提供實際授權，故無法使用此API
  • 正式環境：https://ecpayment.ecpay.com.tw/1.0.0/Credit/DoAction

HTTPS 傳輸協定

  • Content Type ：application/json
  • HTTP Method ：POST

特店Request參數說明 (Json格式)

MerchantID String(10)
特店編號 必填

RqHeader Object
傳輸資料 必填

Timestamp Number
傳輸時間 必填

請將傳輸時間轉換為時間戳(GMT+8)，綠界會利用此參數將當下的時間轉為Unix TimeStamp來驗證此次介接的時間區間。

❗ 注意事項：
  • 驗證時間區間為 10 分鐘內有效，若超過此驗證時間則此次訂單將無法建立，產生時間戳請參考相關資料。
  • 合作特店須進行主機「時間校正」，避免主機產生時差，導致API無法正常運作。

Data String
加密資料 必填

此參數為加密過的 JSON 格式資料，加密方式請參考說明。

特店Request參數範例 (Json格式)

				
					{
"MerchantID": "3002607",
"RqHeader": {
"Timestamp": 1234567890
},
"Data": "enter your data"
}

Data參數說明(Json格式)

❗ 注意事項：請在加密前對參數值進行 URLEncode

MerchantID String(10)
特店編號 必填

MerchantTradeNo Sring(20)
特店交易編號 必填

TradeNo String(20)
綠界交易編號 必填

Action String(1)
執行方式 

針對訂單做處理的動作，例如要對訂單做關帳時，請帶C

  • C : 關帳
  • R : 退刷
  • E : 取消
  • N : 放棄

TotalAmount Int
金額 必填

Data參數範例(Json格式)

				
					{
    "MerchantID": "3002607",
    "MerchantTradeNo": "20180914001",
    "TradeNo": "1809261503338172",
    "Action": "C",
    "TotalAmount": 100
}

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

  • 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)
回應訊息

PlatformID String(10)
平台商編號

MerchantID String(10)
特店編號

MerchantTradeNo String(20)
特店交易編號

TradeNo String(20)
綠界交易編號

Data參數範例(Json格式)

				
					{
    "RtnCode": 1,
    "RtnMsg": "Success",
    "MerchantID": "1234567890",
    "MerchantTradeNo": "20180914001",
    "TradeNo": "1809261503338172"
}

YAML

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

				
					openapi: 3.1.0
info:
  title: ECPay Credit Card Refund 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:
  /Credit/DoAction:
    post:
      summary: Perform actions such as capture, refund, cancel, or void on transactions
      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:
        MerchantID:
          type: string
          maxLength: 10
          description: Merchant ID
        MerchantTradeNo:
          type: string
          maxLength: 20
          description: Merchant trade number
        TradeNo:
          type: string
          maxLength: 20
          description: ECPay trade number
        Action:
          type: string
          maxLength: 1
          description: Action to be performed on the transaction (C: capture, R: refund, E: cancel, N: void)
        TotalAmount:
          type: integer
          description: Total amount
    ResponseData:
      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
        MerchantTradeNo:
          type: string
          maxLength: 20
          description: Merchant trade number
        TradeNo:
          type: string
          maxLength: 20
          description: ECPay trade number

Copyright © Green World FinTech Service Co., Ltd. All rights reserved.

綠界官方網站