OwlPay

開始使用 OwlPay API

💡 摘要

OwlPay API 是以 REST 形式設計，用來讀取與寫入 OwlPay 平台上的資料，您可以使用 OwlPay API 來操作 OwlPay 功能，與您的系統進行串接整合。

API 的功能包含獲取權限、管理供應商、管理訂單、管理付款等。

內容大綱

1. 使用概覽

開發與使用 OwlPay API 主要有 2 個步驟：

(1) 取得開發者 API Key
(2) 取用 OwlPay API

2. 使用說明

2-1. 獲取權限 (Authentication)

取用每一隻 OwlPay API 都需要您的專屬 API Key，您可以在「開發者」頁面申請 API Key，參考 開發者 > API Key 申請您的開發 API Key。

當您取得專屬 API Key 後，請參考 開發者 API 文件 > Authenticationopen in new window 了解取用 API 的權限細節。

2-2. 建立與管理供應商 (Vendor)

2-2-1. 建立供應商 (Create a vendor)

首先，使用 (POST) Create a vendoropen in new window 建立供應商資訊。您必須在公司下建立 供應商 資料，才能進行後續的付款。

💡 API 參數

國家碼 (Country code)、電話碼 (Phone code)、幣別碼 (Currency code) 請參考 API Parameter Mapping Tableopen in new window。


(POST) Create a vendor

curl https://api.owlpay.com/api/v1/platform/tunnel/vendors \ 
  -u <application_secret>: \
  -d name="OwlPay Vendor Name" \
  -d email="owlting@owlpay.com"
1
2
3
4

Response

{
    "data":{
        "uuid":"ven_LfktdIojNyoN4LQ96xLkDAc",
        "object":"vendor",
        "application_vendor_uuid":"1",
        "name":"OwlTing Hotel TWD (測試旅館)",
        "email":"",
        "description":"",
        "vendor_information":{
            "address_country":"tw",
            "address_city":"new_taipei",
            "address_township":null,
            "address":"231台灣新北市新店區北新路三段219號",
            "phone_code":null,
            "phone_number":"+886-2-7727-6500",
            "tax_number":"53092632",
            "note":null
        },
        "contact":{
            "contact_name":"OwlTing",
            "contact_email":"owlting1@gmail.com",
            "phone_code":null,
            "phone_number":"+886-2-7727-6500"
        },
        "remit_info":{
            "currency":"TWD",
            "country":"TW",
            "bank_code":"617",
            "branch_code":"6170035",
            "account_name":"OwlTing Hotel TWD",
            "account":87609457,
            "swift_code":null,
            "address":null
        },
        "is_invited":false
    },
    "status":200
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

2-2-2. 邀請供應商 (Invite Vendor)

當您建立完成供應商資料後，使用 (POST) Create a vendor inviteopen in new window 寄送邀請信到管理者 Email 信箱，邀請該供應商的管理者加入 OwlPay。

(POST) Create a vendor invite

curl https://api.owlpay.com/api/v1/platform/tunnel/vendor_invite \ 
  -u <application_secret>: \
  -d is_owlpay_send_email=false \
  -d email='owlpay-team@owlting.com' \
  -d "meta_data[vendor_name]"='Hello'
1
2
3
4
5

Response

{
    "data": {
        "object": "vendor_invite",
        "uuid": "veninv_xxxxxxx",
        "vendor_uuid": "ven_xxxxxxxxxxx",
        "connect_invite_hash": "xxxxxxxxxxxx",
        "invite_url": "https://auth.owlting.com/...",
        "email": "vendor@owlpay.com",
        "is_owlpay_send_email": false,
        "expired_at": "2021-09-11T16:23:07+00:00",
        "created_at": "2021-09-10T16:23:07+00:00"
    },
    "status": 200
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

2-2-3. 更多 Vendor API 細節

請參考 開發者 API 文件 > Vendoropen in new window

2-3. 管理訂單 (Order)

2-3-1. 建立單張訂單 (Create an order)

當您的供應商通過審核後，就可以開始使用 Order API 來新增、修改、取消訂單。使用 (POST) Create an orderopen in new window 來建立單張訂單。

💡 API 參數

國家碼 (Country code)、電話碼 (Phone code)、幣別碼 (Currency code) 請參考 API Parameter Mapping Tableopen in new window。


(POST) Create an order

curl https://api.owlpay.com/api/v1/platform/tunnel/orders \ 
  -u <application_secret>: \
  -d order_serial="OPY12345678" \
  -d total=10000 \
  -d "meta_data[order_id]"=9527
1
2
3
4
5

Response

{
    "data": {
        "order_token": "ord_eb503be5c41d61932a7e852e07d326b600189aa0abc0dc0060ea5a3a5e928938",
        "object": "order",
        "uuid": "ord_eb503be5c41d61932a7e852e07d326b600189aa0abc0dc0060ea5a3a5e928938",
        "status": "owlpay.received_order",
        "is_checked": false,
        "order_serial": "OBE3xxxxxxxxx",
        "application_order_serial": "OBE3xxxxxxxxx",
        "application_order_created_at": "2021-02-24T02:20:06+00:00",
        "allow_transfer_time_at": null,
        "last_reject_transfer_reason": null,
        "is_rejected": false,
        "currency": "TWD",
        "total": 451,
        "display_currency": "JPY",
        "created_at": "2021-04-23T05:09:51+00:00",
        "vendor_uuid": "ven_U2vCLXIpBewe71LX0OG3ibX",
        "vendor_name": "xxxxxxxxx",
        "application_vendor_uuid": "f3a80c83-ec69-4ba0-98b1-f17b18e2b64f",
        "description": "xxxxxxxxx order - OBE3xxxxxxxxx during at 2021-02-25 - 2021-02-26",
        "meta_data": {
            "payment_total (營運單位應收款項)": "460.00",
            "fee_total (服務費)": "9",
            "order_total (訂單總金額)": "950.00",
            "order_source (訂單來源)": "booking_engine",
            "language (訂單語系)": "zh_tw",
            "hotel_uuid (旅館識別碼)": "xxxxxxxxxxxx",
            "hotel_id (旅館編號)": "2006",
            "hotel_name (旅館名稱)": "xxxxxxxxx",
            "hotel_timezone (旅館時區)": "Asia/Taipei"
        }
    },
    "status": 200
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

2-3-2. 建立多張訂單 (Create orders)

若要一次建立多張訂單，請使用 (POST) Create orders(batch)open in new window。

(POST) Create orders(batch)

curl https://api.owlpay.com/api/v1/platform/tunnel/orders/batch \ 
  -u <application_secret>: \
  -d "orders[0][order_serial]"="OPY12345678" \
  -d "orders[0][currency]"="TWD" \
  -d "orders[0][total]"=10000 \
  -d "orders[0][meta_data][order_id]"=9527
1
2
3
4
5
6

Response

{
    "data": [
        {
            "order_token": "ord_eb503be5c41d61932a7e852e07d326b600189aa0abc0dc0060ea5a3a5e928938",
            "object": "order",
            "uuid": "ord_eb503be5c41d61932a7e852e07d326b600189aa0abc0dc0060ea5a3a5e928938",
            "status": "owlpay.received_order",
            "is_checked": false,
            "order_serial": "OBE3xxxxxxxxx",
            "application_order_serial": "OBE3xxxxxxxxx",
            "application_order_created_at": "2021-02-24T02:20:06+00:00",
            "allow_transfer_time_at": null,
            "last_reject_transfer_reason": null,
            "is_rejected": false,
            "currency": "TWD",
            "total": 451,
            "display_currency": "JPY",
            "created_at": "2021-04-23T05:09:51+00:00",
            "vendor_uuid": "ven_U2vCLXIpBewe71LX0OG3ibX",
            "vendor_name": "xxxxxxxxx",
            "application_vendor_uuid": "f3a80c83-ec69-4ba0-98b1-f17b18e2b64f",
            "description": "xxxxxxxxx order - OBE3xxxxxxxxx during at 2021-02-25 - 2021-02-26",
            "meta_data": {
                "payment_total (營運單位應收款項)": "460.00",
                "fee_total (服務費)": "9",
                "order_total (訂單總金額)": "950.00",
                "order_source (訂單來源)": "booking_engine",
                "language (訂單語系)": "zh_tw",
                "hotel_uuid (旅館識別碼)": "xxxxxxxxxxxx",
                "hotel_id (旅館編號)": "2006",
                "hotel_name (旅館名稱)": "xxxxxxxxx",
                "hotel_timezone (旅館時區)": "Asia/Taipei"
            }
        },
        {...},
        {...},
    ],
    "status": 200,
    "pagination": {
        "total": 270386,
        "count": 12,
        "perPage": 12,
        "currentPage": 1,
        "totalPages": 22533,
        "links": {
            "next": "http://owlpay.owlting.worker/api/platform/applications/app_9KITy3ziM4Z841FX6dkRnYl/orders?q=%2Fapi%2Fplatform%2Fapplications%2Fapp_9KITy3ziM4Z841FX6dkRnYl%2Forders&page=2"
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

2-3-3. 更多 Order API 細節

請參考 開發者 API 文件 > Orderopen in new window

2-4. 申請對帳 (Apply for order reconciliation)

若您需要開始付款給供應商，必須申請訂單對帳 (請參考 OwlPay 付款流程 瞭解付款細節)。

2-4-1. 建立對帳訂單 (Create an order reconciliation)

當 公司 準備進行訂單付款時，必須先申請對帳。使用 (POST) Create an order reconciliationopen in new window 來建立單張的對帳訂單。

(POST) Create an order transfer

curl https://api.owlpay.com/api/v1/platform/tunnel/orders_reconciliation \ 
  -u <application_secret>: \
  -d order_serials[0]="OPY00000001" \
  -d order_serials[1]="OPY00000002"
1
2
3
4

Response

{
    "data": {
        "is_test": true,
        "is_pair_approval": false,
        "group_uuid": null,
        "uuid": "otr_lBfu9B0YZmzk6nRb5SzznIS",
        "object": "order_transfer",
        "uncheck_count": 0,
        "checked_count": 1,
        "currency": "TWD",
        "status": "settled",
        "total": 2980,
        "settled_total": 0,
        "finished_at": "2021-03-28 09:08:27",
        "display_currency": "TWD",
        "display_total": 2980,
        "fee_currency": "TWD",
        "fee": 0,
        "display_fee_currency": "TWD",
        "display_fee": 0,
        "apply_user": {
            "object": "order_transfer.apply_user",
            "owlting_uuid": "08842a50-9940-11e8-b24c-5f482ae31d14",
            "name": "Test 俊仁",
            "email": "maraschen@owlting.com",
            "guard": "platform"
        },
        "orders": [
            {
                "order_token": "ord_2d010d244506025df9170e1a50b87da3fd2a85681be8765a644e5f9b0ed5eac2",
                "object": "order",
                "uuid": "ord_2d010d244506025df9170e1a50b87da3fd2a85681be8765a644e5f9b0ed5eac2",
                "status": "owlpay.order_confirmed",
                "order_serial": "OBE90600353321031902",
                "application_order_serial": "OBE90600353321031902",
                "application_order_created_at": "2021-03-19T08:18:47+00:00",
                "last_reject_transfer_reason": null,
                "is_rejected": false,
                "currency": "TWD",
                "total": 2980,
                "display_currency": "TWD",
                "display_total": 2980,
                "created_at": "2021-03-19T08:18:49+00:00",
                "vendor_uuid": "ven_yFiXHQ9jveYavxRn39Av0Ze",
                "vendor_name": "桐話親子民宿",
                "application_vendor_uuid": "4dae51cf-c26f-41c2-9b89-202338ce5f3e",
                "is_transferred": false,
                "events": [
                    {
                        "object": "blockchain_event",
                        "type": "owlpay.received_order",
                        "block_number": "21163191",
                        "transaction_hash": "0x66db40dff16433c442355b4ea97ba10ff7d1540fc9307b35df69e4fea0ad3fb7",
                        "created_at": "2021-03-19T08:18:54+00:00",
                        "blockchain_created_at": "2021-03-19T08:18:54+00:00"
                    }
                ],
                "description": "桐話親子民宿 order - OBE90600353321031902 during at 2021-05-31 - 2021-06-01",
                "meta_data": [
                    {
                        "order_source": "manual"
                    },
                    {
                        "language": "zh_tw"
                    },
                    {
                        "items": "[{\"room_id\":15692,\"plan_id\":12766,\"date\":\"2021-05-31\",\"qty\":1,\"currency\":\"TWD\",\"total\":\"3580.00\",\"room_name\":\"四人房\",\"plan_name\":\"官網訂房\"}]"
                    },
                    {
                        "hotel_info": "{\"id\":3533,\"name\":\"桐話親子民宿\",\"uuid\":\"4dae51cf-c26f-41c2-9b89-202338ce5f3e\",\"timezone\":\"Asia\\/Taipei\"}"
                    }
                ],
                "logs": [
                    {
                        "uuid": "req_21ZDNSOkZzG4Kjx9J26U7Ub2",
                        "route_name": "v1.owlpay.tunnel.orders.create",
                        "route_name_description": "v1.owlpay.tunnel.orders.create",
                        "action": "POST",
                        "path": "api/v1/platform/tunnel/orders",
                        "is_test": true,
                        "created_at": "2021-03-19T08:18:49+00:00"
                    }
                ]
            }
        ],
        "vendors": [
            {
                "object": "order_transfer.vendor",
                "application_vendor_uuid": "4dae51cf-c26f-41c2-9b89-202338ce5f3e",
                "uuid": "ven_yFiXHQ9jveYavxRn39Av0Ze",
                "email": "n22790049@gmail.com",
                "name": "桐話親子民宿"
            }
        ],
        "created_at": "2021-03-19T08:19:02+00:00",
        "updated_at": "2021-03-28T09:08:27+00:00"
    },
    "status": 200
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

2-4-2. 更多 Order Reconciliation API 細節

請參考 開發者 API 文件 > Orders reconciliationopen in new window

2-5. 審核 (Review reconciliation order)

目前尚無審核相關 API，請參考 審核 頁面從 UI 畫面上操作。

2-6. 付款 (Make payout to vendors)

目前尚無付款相關 API，請參考 付款 頁面從 UI 上操作。

相關連結

開發者 API 文件open in new window

Copyright © OwlPay.