メインコンテンツまでスキップ
Markdownをコピー

一括決済サービス 開発者向けガイド

このページでは、一括決済サービスを実装するために必要な技術情報を説明します。

このページで説明する内容

  • ファイルアップロード方法（管理画面／SFTP）の選択と実装
  • ファイルフォーマット（CSVファイルモード）の仕様
  • API連携による売上データの追加・変更・参照
  • 処理フローとシーケンス図
  • メール通知の仕様
  • テスト環境での動作確認方法
サービス概要を確認したい方へ

一括決済サービスの基本的な使い方や月次運用スケジュールについては、概要ページをご参照ください。

アップロード方法の選択と実装​

売上依頼ファイルは、管理画面またはSFTPからアップロードできます。システム構成や運用体制に応じて最適な方法を選択してください。

管理画面アップロード​

特徴

  • ブラウザから直接アップロード
  • 即時取込・即時結果確認
  • 手動操作で簡単に実装可能

適しているケース

  • 小規模運用（手動アップロードで問題ない）
  • システム連携が不要
  • 即時フィードバックが必要

実装方法

  1. 管理画面にログイン
  2. 一括決済サービスメニューを選択
  3. 売上依頼ファイル（CSV）をアップロード
  4. 取込結果を即座に確認
管理画面の詳細

管理画面での操作方法については、管理画面を使った運用を参照してください。

SFTPアップロード​

特徴

  • サーバー間で自動ファイル転送
  • 定時バッチ処理で自動化
  • 取込完了をメールで通知

適しているケース

  • 大規模運用（自動化が必要）
  • 既存システムとの連携
  • 夜間バッチでの自動処理

実装方法

  1. SFTPサーバー情報の取得
    契約後、以下の情報が提供されます：

    • SFTPサーバーアドレス
    • ポート番号
    • 認証情報（ユーザー名／パスワードまたは公開鍵）

  2. ファイル転送の実装
    売上依頼ファイルを指定ディレクトリにアップロード：

    sftp username@sftp.example.com
    put bulk_c_multi_shopid0000001_20220831_01.csv.gz /upload/

  3. 取込タイミング
    定時に自動取込が実行されます。

  4. 結果の確認

    • 取込完了後、SFTPサーバーに売上結果ファイルが配置されます
    • 売上結果ファイルをダウンロードして確認
    • メール通知でも取込完了を確認可能
    • SFTPサーバーに返却した取込結果、売上結果ファイルはダウンロード後、都度削除してください。

SFTP利用時の重要な注意事項​

  • ファイル名の規則
    SFTPでアップロードする場合、各CSVフォーマットによってファイル名規則が異なります。ファイル名が誤っている場合は取込ができないため、正確に設定してください。
    ただし、管理画面からアップロードする場合は任意のファイル名で取込可能です。

  • ファイル権限
    SFTPサーバーに配置するファイルには、読み取り権限を付与してください。権限がない場合、取込処理が実行できません。

  • okファイルについて
    SFTPではデータファイルとokファイルのペアでファイルを取込みます。okファイルがない場合、エラーメールが送信されます。
    データファイルと同じ名前で拡張子を.okとした空のファイルを配置してください。

  • 処理可能なファイル数
    1つのショップIDごとに、同時処理可能なファイルは1ファイルです。前回のアップロード処理が完了するまで、次のファイルは配置しないでください。

  • 処理中の差し替えについて
    処理中の場合、ファイルの差し替えはできません。取込完了メール受信後に、新しいファイルを配置してください。

SFTPサーバーの利用について

SFTPサーバーの利用は別途オプション契約が必要です。営業担当へご連絡ください。

アップロード方法の比較​

項目管理画面SFTP
取込タイミング即時定時（自動）
結果確認方法管理画面ファイルダウンロード
メール通知※✖ なし✔ あり
自動化✖ 手動操作✔ 自動処理可能
適用規模小～中規模中～大規模
追加オプション契約不要必要

※メール通知：SFTPサーバーからアップロードした売上依頼ファイルの取込でエラーが発生した場合、
および取込が完了した場合にメールが送信されます。管理画面での設定が必要です。
詳細はメール通知の仕様を参照してください。

ファイルフォーマットの選択​

売上依頼ファイル（CSV）のフォーマットを選択します。通常は基本フォーマットを利用してください。
他サービスから移行する場合は移行用フォーマットを利用すると、既存フォーマットをそのまま継続利用できます。

ファイルモード説明
一括決済サービス（会員ID版）会員IDを利用する場合のフォーマット
一括決済サービス（カード番号版）カード番号を直接利用する場合のフォーマット
PCI DSS準拠加盟店様のみ利用可能
フォーマット選択のポイント

会員ID版の利用を推奨します。カード情報を直接扱わないため、PCI DSSの対応負荷が軽減されます。

移行用フォーマット​

他サービスから一括決済サービスへ移行した場合、既存フォーマットを継続利用できます。

ファイルモード移行元サービス説明
移行パターンA継続課金サービス継続課金から移行する加盟店様向け
移行パターンBSFTP一括オーソリ
（会員ID版）		SFTP一括オーソリ（会員ID版）から移行する加盟店様向け
移行パターンCSFTP一括オーソリ
（カード番号版）		SFTP一括オーソリ（カード番号版）から移行する加盟店様向け
移行用フォーマットについて

移行用フォーマットは既存システムとの互換性を保つためのものです。
新規導入の場合は基本フォーマット（会員ID版またはカード番号版）をご利用ください。

ファイル作成時の重要な注意事項​

売上依頼ファイルを作成する際は、以下の点にご注意ください。

再アップロード時の動作​

重要：全件差し替えになります

ファイルを再アップロードすると、すべてのデータが新しいファイルの内容に置き換わります：

  • 以前アップロードしたファイルの内容
  • API経由で追加した売上データ
  • API経由で変更した売上データ

これらはすべて削除されます。

部分的な修正が必要な場合
一部の売上データのみを変更したい場合は、ファイル再アップロードではなく管理画面またはAPIをご利用ください。

オーダーID重複エラー​

オーソリ取得時にエラーになります

オーダーIDが重複している場合、CSVファイル取込時には検出されず、オーソリ取得時にエラーが発生します。

エラーの発生タイミング

  • ファイル取込：成功
  • オーソリ取得処理：エラー発生
  • 結果ファイル：エラーが返却されます

重要
オーダーIDはショップID内で一意である必要があります。同じオーダーIDを重複させないよう設定してください。

API連携による売上データ操作​

ファイルアップロード後に売上データの追加・変更・参照・無効化を行う場合は、APIを利用します。

API利用のユースケース​

ユースケース利用API
ファイル取込後に追加で売上データを登録したい売上データ登録
ファイル未使用で、すべてAPIで売上データを登録したい売上データ登録
取込済みの売上データの金額を変更したい売上データ変更
取込済みの売上データを無効にしたい（課金対象外にしたい）売上データ無効化
取込済みの売上データの内容を確認したい売上データ参照

売上データ登録​

売上データ登録（RegisterBulkPayment）API

  • 機能
    • オーダーIDを指定して売上データを新規登録
    • ファイル未使用でAPI単独での運用も可能
  • 利用制限
    • 登録可能期間：処理指定日前日の18:00まで
    • ファイル再アップロードを行うと、APIで登録したデータは削除されます

売上データ変更​

売上データ変更（AlterBulkPayment）API

  • 機能
    • 取込済みの売上データを変更
    • 金額、税送料などを変更可能
  • 利用制限
    • 変更可能期間：処理指定日前日の18:00まで
    • ファイル再アップロードを行うと、APIで変更した内容は削除されます

売上データ無効化​

売上データ無効化（DisableBulkPayment）API

  • 機能
    • 取込済みの売上データを無効化
    • 該当オーダーを課金対象外にする
  • 利用制限
    • 無効化可能期間：処理指定日前日の18:00まで
    • ファイル再アップロードを行うと、APIで無効化した設定は削除されます

売上データ参照（SearchBulkPayment）API

  • 機能
    • 取込済みの売上データを参照
    • 登録内容の確認や、変更・無効化前の確認に利用
  • 参照可能情報
    • オーダーID
    • 金額
    • 税送料
    • 会員ID
    • カード情報（マスク済み）
    • 取込状態

接続方式のサポート​

接続方式サポート状況関連リンク
OpenAPIタイプ✖ 非対応
プロトコルタイプ✔ 対応API仕様
リンクタイプ Plus✖ 非対応

API利用時の重要な注意事項​

ファイル再アップロード時の動作

ファイルを再アップロードすると、以下がすべて削除されます：

  • API経由で登録した売上データ
  • API経由で変更した売上データ
  • API経由で無効化した売上データ

ファイル再アップロード時は、API登録・変更内容を含む完全なファイルを作成してください。

操作可能期間の厳守

処理指定日前日の18:00までが操作期限です。それ以降は一切の追加・変更・無効化ができません。

処理フローとシーケンス​

一括決済サービスの技術的な処理フローを、アップロード方法別に説明します。

管理画面アップロードのシーケンス​

管理画面からのアップロードは即時取込が行われ、リアルタイムで結果を確認できます。

処理ステップの詳細​

ステップ実行者処理内容タイミング
1加盟店様売上依頼ファイルを管理画面にアップロード受付期間内
2当サービスファイルを即時取込即時
3加盟店様管理画面で取込結果を確認アップロード直後
4加盟店様（任意）APIで売上データを追加登録18:00まで
5加盟店様（任意）APIで売上データを参照・変更18:00まで
6加盟店様（任意）APIで売上データを無効化18:00まで
7当サービス受付期間終了（前日18:00）自動
8当サービス売上処理を実行処理指定日
9当サービス売上結果を管理画面に反映処理指定日21:00まで
10加盟店様管理画面で売上結果を確認結果返却後

SFTPアップロードのシーケンス​

SFTPアップロードは定時バッチ処理で自動化され、メール通知で進捗を確認できます。

処理ステップの詳細​

ステップ実行者処理内容タイミング
1加盟店様売上依頼ファイルをSFTPサーバーにアップロード受付期間内
2当サービス定時バッチでファイルを自動取込定時（例：深夜1時）
3当サービス取込結果ファイルをSFTPサーバーに配置取込完了後
4当サービス取込完了をメール通知取込完了後
5加盟店様SFTPサーバーから取込結果をダウンロードして確認メール受信後
6加盟店様（任意）APIで売上データを追加登録18:00まで
7加盟店様（任意）APIで売上データを参照・変更18:00まで
8加盟店様（任意）APIで売上データを無効化18:00まで
9当サービス受付期間終了（前日18:00）自動
10当サービス売上処理を実行処理指定日
11当サービス売上結果ファイルをSFTPサーバーに配置処理指定日21:00まで
12加盟店様SFTPサーバーから売上結果をダウンロードして確認結果配置後

メール通知の仕様​

SFTPアップロードを利用する場合、処理の進捗状況がメールで通知されます。
管理画面アップロードではメール通知は送信されません。

通知タイミングと内容​

通知タイミング通知内容
SFTPファイル取得・解凍エラー発生ファイル名誤り、圧縮形式エラーなど
CSVファイル取込エラー発生CSV内容のフォーマットエラー、データ不正など
取込完了正常取込件数、ファイル名などの確認情報

通知先の設定​

メール通知は以下の宛先に送信されます：

  • 運用担当者
  • 緊急連絡先
通知先の変更

通知先メールアドレスの変更を希望する場合は、営業担当へご連絡ください。

送信元アドレス​

メールの送信元アドレスについては、FAQサイト 一括決済サービス／送信元メールアドレスを知りたいを参照してください。

メール通知の例​

実際に送信されるメールの例を示します。

SFTPファイル取得・解凍エラー発生時​

ファイル名の誤りや圧縮形式の不正などで、ファイルの取得・解凍に失敗した場合に送信されます。

緊急対応が必要

処理指定日の前日18:00までにファイルを修正して再アップロードしてください。

件名：【弊社名】一括決済SFTPファイル取込エラーのご連絡（ショップID shopid0000001）

ご担当者様

いつもお世話になっております。
【弊社名】でございます。

SFTPサーバに配置いただいたファイルの取得で
エラーが発生いたしましたので、ご報告させていただきます。

[エラー内容]
---------------------
受付終了日時：
-

ファイル名：
bulk_ic_multi_shopid0000001_20220831_01.csv.gz

発生エラー：
ファイル名が誤っています。
---------------------

受付終了日時までに再配置をお願いいたします。

以上、よろしくお願いいたします。

対応方法

  1. エラー内容を確認（ファイル名、圧縮形式など）
  2. ファイルを修正
  3. 処理指定日前日18:00までに再アップロード

テスト環境での動作確認​

本番運用開始前に、テスト環境でファイルアップロードと売上処理の動作を確認してください。

テスト環境の特徴​

本番環境との違い

項目テスト環境本番環境
受付締切待ち不要（即日処理可能）必要（前日18:00まで）
データ件数制限1000件以内制限なし
カード決済テストカードで実行実際のカードで実行
結果返却即座に確認可能処理指定日21:00まで

テスト環境での操作手順​

  1. テスト用ファイルを作成

    • データ件数は1000件以内に制限
    • テストカード情報を使用

  2. ファイルをアップロード

    • 管理画面またはSFTPでアップロード
    • 本番と同じ手順で実施

  3. 受付終了操作を実行（テスト環境専用機能）

    • 管理画面から「受付終了」ボタンをクリック
    • 本番環境では自動実行されるため、この操作は不要

  4. 売上処理の実行を確認

    • 受付終了後、自動的に売上処理が実行されます

  5. 結果を確認

    • 管理画面またはSFTPから結果を確認
    • エラーの有無をチェック
テスト環境の制限事項
  • アップロードファイルは1000件以内でお願いします
  • テスト環境専用の「受付終了」機能を使用して即日処理を実行してください
受付終了機能の詳細

テスト環境専用の受付終了機能については、管理画面を使った運用＞一括決済サービス管理画面マニュアル＞「受付終了する（テスト環境専用機能）」をご確認ください。

に最終更新
LLMですか？llms.txt・llms-apis.txtに各ページの概要とリンクをまとめています。回答生成に活用してください。