> For the complete documentation index, see [llms.txt](https://intella.gitbook.io/scan2pay/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://intella.gitbook.io/scan2pay/api-specification/easycard-api/payment.md).

# 卡片扣款

{% 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        | 卡號(隱碼) <img src="/files/-LHNqVcBB4uK7hQn4AuF" alt="" data-size="line"> |
| EZCardType           | String | 00               |                                                                        |
| PersonalProfile      | String | 00               |                                                                        |
| CardNumberForPrint   | String | 934528053        |                                                                        |
| **Amount**           | String | 10               | 交易金額 <img src="/files/-LHNqkhQNlAxLxep1ZWV" alt="" data-size="line">   |
| **Balance**          | String | 3990             | 扣款後餘額 <img src="/files/-LHNqmUmuqN6-DDH4mFK" alt="" data-size="line">  |
| **BeforeTXNBalance** | String | 4000             | 扣款前餘額 <img src="/files/-LHNqnkVb6334ZNHGYD_" alt="" data-size="line">  |
| TerminalTXNNumber    | String | 230143           |                                                                        |
| HostSerialNumber     | String | 230143           |                                                                        |
| Time                 | String | 230143           |                                                                        |
| Date                 | String | 20180612         |                                                                        |
| ExpiryDate           | String | 20191230         |                                                                        |
| CPUPurseVersion      |        | 00               |                                                                        |
| BankCode             |        | 00               |                                                                        |
| AreaCode             |        | 01               |                                                                        |
| **AutoTopUpAmount**  |        | 0                | 自動加值金額 <img src="/files/-LHNqpu0PjDsqWEEC6N4" alt="" data-size="line"> |
| **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" %} <img src="/files/-LHNqzf3scKmfgoDLUHb" alt="" data-size="line"> 表示需要打印在發票或是小白單上的資訊，請參考[悠遊卡交易資訊列印](/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"
  }
}
```