# 卡片扣款
{% hint style="info" %}
此API為必要串接
{% endhint %}
{% hint style="warning" %}
扣款時若餘額不足，有自動加值功能的卡片會自動進行加值，加值成功後再自動進行扣款
{% endhint %}
{% hint style="warning" %}
呼叫扣款API後，消費者要在30秒內將卡片放到讀卡機上進行感應付款。若消費者未將卡片靠上讀卡機，扣款API需要等候30秒才會回覆失敗，串接方請勿在收到API回應前就中斷程序。
{% endhint %}
## Request
### Header
| 欄位 | 必填 | 型別 | 範例 | 說明 |
| ----------- | --- | --------- | -------------- | -------------------- |
| Method | YES | String(5) | 31800 | 支付方式, 悠遊卡使用31800 |
| ServiceType | YES | String | **Payment** | 服務代碼 |
| MchId | YES | String | Account0001 | 特店帳號 |
| TradeKey | YES | String | sha256...hash | 交易密碼(sha256編碼) |
| CreateTime | YES | String | 20180101120000 | 建立日期, yyyyMMddHHmmss |
### Data
| 欄位 | 必填 | 型別 | 範例 | 說明 |
| ------------ | --- | ------ | ---------- | ---------- |
| DeviceId | YES | String | 01301234 | 終端機(讀卡機)編號 |
| Retry | YES | String | 0 | 重試次數, 請帶入0 |
| Amount | YES | String | 100 | 扣款金額 |
| StoreOrderNo | YES | String | PO01010001 | 訂單編號 |
| Body | No | String | 今日特餐 | 商品名稱 |
## Response
### Header
| 欄位 | 型別 | 範例 | 說明 |
| ------------ | --------- | -------------- | ---------------------------------------------------- |
| StatusCode | String(4) | 0000 | [交易結果代碼](/scan2pay/appendix/scan2pay-error-codes.md) |
| StatusDesc | String | 交易成功 | 交易結果代碼說明 |
| Method | String(5) | 31800 | 支付方式, 悠遊卡使用31800 |
| ServiceType | String | **Payment** | 服務代碼 |
| MchId | String | Account0001 | 特店帳號 |
| ResponseTime | String | 20180101120000 | 交易回應時間, yyyyMMddHHmmss |
### Data
| 欄位 | 型別 | 範例 | 描述 |
| -------------------- | ------ | ---------------- | ---------------------------------------------------------------------- |
| **EZCardID** | String | 934528053 | 卡號(隱碼) 
|
| EZCardType | String | 00 | |
| PersonalProfile | String | 00 | |
| CardNumberForPrint | String | 934528053 | |
| **Amount** | String | 10 | 交易金額 
|
| **Balance** | String | 3990 | 扣款後餘額 
|
| **BeforeTXNBalance** | String | 4000 | 扣款前餘額 
|
| TerminalTXNNumber | String | 230143 | |
| HostSerialNumber | String | 230143 | |
| Time | String | 230143 | |
| Date | String | 20180612 | |
| ExpiryDate | String | 20191230 | |
| CPUPurseVersion | | 00 | |
| BankCode | | 00 | |
| AreaCode | | 01 | |
| **AutoTopUpAmount** | | 0 | 自動加值金額 
|
| **TXNResult** | String | Success | 交易結果 |
| Retry | String | 0 | |
| **ErrorCode** | String | 000000 | [交易結果代碼](/scan2pay/appendix/easycard-error-codes.md) |
| OrderId | String | PO180101001 | 特店訂單編號 |
| DongleDeviceID | String | 08100DE0A57E | |
| RRNumber | String | 18061223014301 | |
| TXNType | String | Payment | |
| NewAESKey | String | 61c4d0f9...3607 | |
| DeviceNumber | String | 0830000001304104 | |
| request | JSON | | |
{% hint style="info" %} 
表示需要打印在發票或是小白單上的資訊，請參考[悠遊卡交易資訊列印](/scan2pay/appendix/easycard-printout.md)說明
{% endhint %}
{% hint style="warning" %}
悠遊卡交易, Header欄位的 "StatusCode" 表示API呼叫成功, 不代表交易成功, 請讀取Data欄位中的TXNResult結果 ("Success" 為成功, "Fail"為失敗) , 對應的錯誤碼 "ErrorCode" 為6碼, "000000" 為成功, 其他為錯誤.
{% endhint %}
## API Example
### Request
```
{
"Header": {
"Method": "31800",
"ServiceType": "Payment",
"MchId": "myMchId",
"TradeKey": "9af15b336e6a9619928537df30b2e6a2376569fcf9d7e773eccede65606529a0",
"CreateTime": "20180715104643"
},
"Data": "{\"DeviceId\":\"01304187\",\"Retry\":\"0\",\"Amount\":\"10\",\"StoreOrderNo\":\"PO20180715005\",\"Body\":\"Chicken Rice\"}"
}
```
### Response
```
{
"Header": {
"StatusCode": "0000",
"StatusDesc": "STATUS_SUCCESS",
"Method": "31800",
"ServiceType": "Payment",
"MchId": "myMchId",
"ResponseTime": "20180715104650"
},
"Data": {
"EZCardID": "1917740208",
"EZCardType": "08",
"PersonalProfile": "00",
"CardNumberForPrint": "1917740208",
"Amount": "10",
"Balance": "462",
"BeforeTXNBalance": "472",
"TerminalTXNNumber": "104644",
"HostSerialNumber": "104644",
"Time": "104644",
"Date": "20180715",
"ExpiryDate": "20250810",
"CPUPurseVersion": "00",
"BankCode": "32",
"AreaCode": "01",
"AutoTopUpAmount": "0",
"request": {
"Amount": "10",
"Retry": "0",
"BatchNumber": "18071511",
"SameCard": "0",
"ServiceType": "Payment",
"TerminalID": "09900000",
"DeviceID": "01304187",
"TerminalTXNNumber": "104644",
"HostSerialNumber": "104644",
"Time": "104644",
"Date": "20180715",
"AESKey": "a304c6beb25bb660d5d9668eb1d6bf3b"
},
"TXNResult": "Success",
"Retry": "0",
"ErrorCode": "000000",
"OrderId": "PO-20180715-005",
"DongleDeviceID": "5B100DE00F97",
"RRNumber": "18071510464488",
"TXNType": "Payment",
"NewAESKey": "574660f677ee8314812ad829a6b48bf7",
"DeviceNumber": "0990000001304187"
}
}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://intella.gitbook.io/scan2pay/api-specification/easycard-api/payment.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.