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

授權交易 / Apple Pay交易授權

應用場景

提供特店使用Apple Pay呼叫綠界API進行幕後交易授權。

❗ 注意事項：此 API 需與銀行連線，如遇銀行連線不穩定時可能導致回應時間增加。特店如需設定 API 連線逾時的時間，建議至少 30 秒以上。

API介接網址

  • 測試環境: https://ecpayment-stage.ecpay.com.tw/1.0.0/Cashier/BackAuth
  • 正式環境: https://ecpayment.ecpay.com.tw/1.0.0/Cashier/BackAuth

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)
特店編號 必填

OrderInfo Object
交易訂單資訊 必填

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

僅支援a-zA-z0-9

MerchantTradeDate String(20)
特店交易時間 必填

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

TotalAmount Int
交易金額 必填

ItemName String(400)
商品名稱 必填

  • 如有多項商品，商品名稱以分隔線#分開
  • 請勿傳入超過長度 200 的內容，避免該欄位資訊被截斷

TradeDesc String(200)
交易描述 必填

ReturnURL String(200)
付款回傳結果URL 必填

請帶入可接收付款結果的URL

ChoosePayment Object
付款方式 

固定為 ApplePay

ApplePayInfo Object
信用卡資訊 必填

CurrencyCode String(20)
幣別 必填

Apple Server做商店驗證所傳的CurrencyCode

TradeType Int
交易來源 必填

1:In App
2:On the Web

PaymentToken String
支付憑證 必填

Apple Server做商店驗證完回傳的Merchant Session物件中的paymenttoken

ConsumerInfo Object
持卡人資訊 

Email String(30)
信用卡持卡人電子信箱

❗ 注意事項：檢核規則請參考正規表達式@”^([a-zA-Z\d._%+-]+@[a-zA-Z\d.-]+\.[a-zA-Z]{2,6})*$”;

Phone String(60)
信用卡持卡人電話

可帶入國碼，但不可帶入+號。ex:886912345678

❗ 注意事項：若非台灣手機號碼，請在電話號碼前帶入國碼。

Name String(50)
信用卡持卡人姓名

  • 該欄位可接受中文、英文與部分特殊符號
  • 可支援的特殊符號為 : , . () / –

CountryCode String(3)
國別碼

  • 持卡人帳單地址國別碼，請參考 ISO3166
  • 臺灣請填寫 158

Address String(50)
地址

請帶入持卡人帳單地址

CustomField String(200)
自訂欄位 

請勿傳入超過長度200的內容，避免該欄位資訊被截斷

Data參數範例(Json格式)

				
					{
    "MerchantID": "3002607",
    "OrderInfo": {
　　    "MerchantTradeDate" : "2022/05/23 14:10:00",
        "MerchantTradeNo" : "1234567890",
        "TotalAmount":  500,
        "TradeDesc" : "交易描述",
        "ItemName" : "泡麵#清潔用品",
        "ReturnURL" : "https://aa.aa.aa"
    },
    "ApplePayInfo": {
　　    "CurrencyCode" : "123",
        "TradeType" : 2,
        "PaymentToken":  "1bwfbkjkd"
    }
}

綠界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 格式資料

Data參數說明(Json格式) :

當付款方式為信用卡一次付清、定期定額、分期付款且不需要進行3D或銀聯卡驗證時，將直接回傳以下授權結果

RtnCode Int
交易狀態

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

RtnMsg String(200)
回應訊息

MerchantID String(10)
特店編號

OrderInfo Object
交易訂單資訊 

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
手續費 

ChargeFee Number
手續費 

TradeStatus String(8)
交易狀態 

若為 0 時，代表交易訂單付款失敗
若為 1 時，代表交易訂單付款成功

CardInfo Object
信用卡授權資訊 

AuthCode String(6)
銀行授權碼 

Gwsr Int
銀行授權碼 

ProcessDate String(20)
交易時間 

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

Amount Int
金額 

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

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

Eci Int
3D(VBV) 回傳值 

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

IssuingBank String(30)
發卡銀行名稱 

IssuingBankCode String(10)
發卡銀行代碼 

CustomField String(200)
自訂欄位 

提供特店使用客制化欄位

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

				
					{
    "RtnCode": 1,
    "RtnMsg": "Success",
    "MerchantID": "1234567890",
    "CardInfo": 
    {
        "Card6No": "123456",
        "Card4No": "1234",
        "IssuingBank": "中國信託商業銀行",
        "IssuingBankCode ": "822",
        "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",
    }
}

YAML

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

				
					openapi: 3.1.0
info:
  title: ECPay BackAuth 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/BackAuth:
    post:
      summary: Back-end authorization for credit card 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
        OrderInfo:
          type: object
          properties:
            MerchantTradeNo:
              type: string
              maxLength: 20
              description: Merchant trade number
            MerchantTradeDate:
              type: string
              maxLength: 20
              description: Merchant trade date
            TotalAmount:
              type: integer
              description: Total amount
            ItemName:
              type: string
              maxLength: 400
              description: Item name
            TradeDesc:
              type: string
              maxLength: 200
              description: Trade description
            ReturnURL:
              type: string
              maxLength: 200
              description: Return URL
            ChoosePayment:
              type: object
              properties:
                Credit:
                  type: string
                  description: Payment method (Credit)
            CardInfo:
              type: object
              properties:
                CardNo:
                  type: string
                  maxLength: 19
                  description: Credit card number
                CardValidMM:
                  type: string
                  maxLength: 2
                  description: Card validity month
                CardValidYY:
                  type: string
                  maxLength: 2
                  description: Card validity year
                CardCVV2:
                  type: string
                  maxLength: 4
                  description: Card security code
                DirectCapture:
                  type: string
                  maxLength: 1
                  description: Direct capture (0 or 1)
                Redeem:
                  type: string
                  maxLength: 1
                  description: Redeem (N or Y)
                CreditInstallment:
                  type: string
                  maxLength: 20
                  description: Credit installment period
                PeriodAmount:
                  type: integer
                  description: Period amount for periodic authorization
                PeriodType:
                  type: string
                  maxLength: 1
                  description: Period type (D, M, Y)
                Frequency:
                  type: integer
                  description: Execution frequency
                ExecTimes:
                  type: integer
                  description: Execution times
                PeriodReturnURL:
                  type: string
                  maxLength: 200
                  description: Periodic return URL
                TravelStartDate:
                  type: string
                  maxLength: 20
                  description: Travel start date
                TravelEndDate:
                  type: string
                  maxLength: 20
                  description: Travel end date
                TravelCounty:
                  type: string
                  maxLength: 20
                  description: Travel county
                OrderResultURL:
                  type: string
                  maxLength: 200
                  description: 3D authentication return URL
            ConsumerInfo:
              type: object
              properties:
                Email:
                  type: string
                  maxLength: 30
                  description: Consumer email
                Phone:
                  type: string
                  maxLength: 60
                  description: Consumer phone number
                Name:
                  type: string
                  maxLength: 50
                  description: Consumer name
                CountryCode:
                  type: string
                  maxLength: 3
                  description: Country code
                Address:
                  type: string
                  maxLength: 50
                  description: Address
            CustomField:
              type: string
              maxLength: 200
              description: Custom field
    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
        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
                Card6No:
                  type: string
                  maxLength: 6
                  description: First six digits of card number
                Card4No:
                  type: string
                  maxLength: 4
                  description: Last four digits of card number
                Eci:
                  type: integer
                  description: 3D secure ECI value
                IssuingBank:
                  type: string
                  maxLength: 30
                  description: Issuing bank name
                IssuingBankCode:
                  type: string
                  maxLength: 10
                  description: Issuing bank code
                Stage:
                  type: integer
                  description: Installment stage
                Stast:
                  type: integer
                  description: First installment amount
                Staed:
                  type: integer
                  description: Each installment amount
                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
                CoBrandingInfo:
                  type: array
                  items:
                    type: object
                    properties:
                      CoBrandingCode:
                        type: string
                        maxLength: 20
                        description: Co-branding code
                Comment:
                  type: string
                  maxLength: 100
                  description: Comment
                CustomField:
                  type: string
                  maxLength: 200
                  description: Custom field

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

綠界官方網站