クラウド端末 API を使用すると、KOMOJU API を通じて、接続された端末デバイスと直接やり取りできます。
クラウド API 統合は、端末を使い始める際の最も簡単な推奨方法です。
利用可能な機能
セッションをデバイスにプッシュする
セッションから領収書を印刷する
デバイス セッションをキャンセルする
クラウド API のフローの例
次の例は、クラウド端末 API を使用してデバイス上で決済セッションを開始し、決済ステータスを POS システムまたはアプリケーションに返す方法を示しています。
これは、予想され得るフローの一例を示したに過ぎません。システム、業界、設定に応じて、異なるフローを選択することもできます。当社の API は、システム ロジックを大幅に変更せずとも、ほとんどの決済フローに対応可能です。
アプリはセッション API を使用してセッションを開始し、金額、通貨、顧客情報、明細項目など、利用可能なすべてのメタデータを必要に応じて含めます。
アプリは、関連付けられたセッション ID を備える新しく作成されたセッションを受信し、このセッション ID を取引の内部レコードに関連付けます。
アプリはクラウド API の Push Session メソッドを呼び出し、端末で決済処理を開始します。
顧客は端末上で決済処理を完了します。
アプリは、受信 Webhook をリッスンするか、セッションのステータスをポーリングします。
セッションが完了すると、商品が配送されるか、サービスが提供されます。
API 参照
デバイス上で決済を開始する
ステップ 1: セッションを作成する
まず、すべての決済情報が含まれるセッションを作成します。外部注文番号やその他のパラメーターを、この決済に関連付けて含めることができます。さらに、この情報は、Webhook メカニズムを通じてフィードバックされます。
POST https://komoju.com/api/v1/sessions
リクエストの例
{
"default_locale": "ja",
"payment_data": {
"capture": "auto",
"external_order_num": "12345678"
},
"mode": "payment",
"amount": 1000,
"currency": "JPY",
"payment_types": [
"credit_card_terminal"
]
}応答
{
"id": "6k4xs4rah6k8bt4ebnufqwhcb",
"resource": "session",
"mode": "payment",
"amount": 1000,
"currency": "JPY",
"session_url": "https://komoju.com/sessions/6k4xs4rah6k8bt4ebnufqwhcb",
"return_url": null,
"default_locale": "ja",
"payment_methods": [
{
"type": "credit_card_terminal",
"amount": 1000,
"currency": "JPY",
"exchange_rate": 1.0,
"hashed_gateway": "e6212ad60e88dbd0"
}
],
"created_at": "2023-12-12T11:55:46.000+09:00",
"cancelled_at": null,
"completed_at": null,
"status": "pending",
"expired": false,
"metadata": {},
"payment": null,
"secure_token": null,
"payment_data": {
"external_order_num": "12345678",
"capture": "auto"
}
}ステップ 2: 端末デバイスにセッションをプッシュする
セッション ID を使用して、この取引セッションをデバイスにプッシュできます。プッシュすると、デバイスに決済開始手順が表示され、使用できるようになります。
端末 ID とセッション ID を提供する必要があります。
これは次のエンドポイントを使用して実行できます。
POST https://komoju.com/api/v1/terminals/{terminal_id}/sessions/{session_id}/push応答
応答は 200 Success メッセージになります。成功しなかった場合は、エラー メッセージが返されます。
{
"status": "success"
}{
"error": {
"code": "error",
"message": "セッションをデバイスにプッシュする処理が保留されているようです。"
}
}ステップ 3: デバイスで決済を完了する
これで、デバイスは決済を受け取り、完了する準備が整いました。完了すると、Webhook をリッスンしたり、セッション ステータスをポーリングして、決済が成功したかどうかを判断できます。
ステップ 4: Webhook
Webhook を使用すると、取引が成功したことを開始者 (POS デバイスなど) に通知できます。販売取引は最終取引ステータスでのみ入金されますが、承認済みの取引だけ扱う場合は、最終ステータスは承認済みステータスになります。
メタデータ セクションには、AID、アプリケーション ラベル、カード名義人名、取引カウンターなど、POS 取引からの情報が含まれます。この情報は、POS 端末側でカスタム領収書を作成したり、記録を保持したりするために使用できます。
{
"id": "4jo7t14vumnhu5cmretrugxiw",
"type": "payment.updated",
"resource": "event",
"data": {
"id": "28e3dhxc8gdr3zdnsdzea17qf",
"resource": "payment",
"status": "captured",
"amount": 1000,
"tax": 0,
"customer": null,
"payment_deadline": "2023-12-14T14:59:59Z",
"payment_details": {
"type": "credit_card_terminal",
"email": null,
"brand": "visa",
"last_four_digits": "0010",
"month": 11,
"year": 2024
},
"payment_method_fee": 0,
"total": 1000,
"currency": "JPY",
"description": null,
"captured_at": "2023-12-12T03:07:29Z",
"external_order_num": "91176632142",
"metadata": {
"action": "sale",
"aid": "A0000000031010",
"application_label": "VISA CREDIT",
"arc": "00",
"atc": "02D4",
"cardholderName": "VISA CREDIT/CARDHOLDER",
"cardholderVerification": "",
"cryptogramType": "ARQC",
"cryptogramValue": "12067CDEAEC09F26",
"method": "CL",
"origin": "terminal",
"terminalSeqCounter": "00000002",
"tsi": "0000",
"tvr": "0000000000"
},
"created_at": "2023-12-12T03:07:28Z",
"amount_refunded": 0,
"locale": "ja",
"session": "ebjljw181tdwpybolb3jpthv6",
"customer_family_name": null,
"customer_given_name": null,
"mcc": null,
"statement_descriptor": null,
"refunds": [],
"refund_requests": []
},
"created_at": "2023-12-12T03:07:30Z",
"reason": null
}領収書を印刷する
以前に完了したセッションから領収書プリンターを呼び出して領収書を印刷する場合は、次の API エンドポイントを呼び出すことで実行できます。
他の呼び出しと同様に、プリンターを呼び出す場合も端末 ID とセッション ID を指定する必要があります。
POST https://komoju.com/api/v1/terminals/{terminal_id}/sessions/{session_id}/print応答は 200 Success メッセージになります。成功しなかった場合は、エラー メッセージが返されます。
{
"status": "success"
}{
"error": {
"code": "error",
"message": "デバイス上でセッションを印刷できませんでした。"
}
}セッションをキャンセルする
セッションがデバイスにプッシュされた後でも、キャンセル リクエストを送信することで決済処理を完全に中止することができます。セッションがキャンセルされると、決済ができなくなります。これは、ユーザーによる取引の続行をシステム側から無人操作で強制的に阻止する必要がある場合に役立ちます。
POST https://komoju.com/api/v1/terminals/{terminal_id}/sessions/{session_id}/cancel応答は 200 Success メッセージになります。成功しなかった場合は、エラー メッセージが返されます。
{
"status": "success"
}{
"error": {
"code": "error",
"message": "セッションをキャンセルできませんでした。"
}
}