【API】API決済接続マニュアル

[ドキュメント更新日]

04/23/2024 : Document Version 3.7

[概要]

このAPIは、カード決済を行うための仮想端末機能を提供します。ログインIDとパスワード、ならびにストアIDを使用して認証を行い、指定されたストアでの決済を処理します。

[エンドポイント]

- ステージングURL: https://stg-uix.vpay.global/api/v1/virtual_terminal
- プロダクションURL: https://cp.vpay.global/api/v1/virtual_terminal
- Method: POST

[リクエストボディ]

リクエスト、は以下の属性をJSON形式で含む必要があります。

フィールド名	タイプ	説明	必須
login_id	string	ユーザーのログインID	◯
login_pass	string	ユーザーのログインパスワード	◯
amount	number	決済金額	◯
currency_id	string	通貨ID 1: 日本円（JPY） 2: 米ドル（USD）	◯
card_first_name	string	カード所有者の名	◯
card_last_name	string	カード所有者の姓	◯
card_number	string	カード番号	◯
card_cvv	string	カードセキュリティコード	◯
card_expire_month	string	カード有効期限（月）	◯
card_expire_year	string	カード有効期限（年）	◯
store	string	ストアID	◯
payment_method	string	支払い方法 1: 一括決済 2: リカーリング決済 3: 分割決済	◯
payment_selection	string	支払い選択 1: DIRECT (現在はDirectのみ)	◯

[レスポンスデータ]

レスポンスは以下の属性をJSON形式で返します。

フィールド名	タイプ	説明
code	number	結果コード
message	string	処理結果のメッセージ

レスポンスコードとその意味

- 20000: 決済に関するデータ通信が完了（決済結果はresultsに記載）

- 40001: 不正なリクエスト（バリデーションエラー）

- 40002: 決済処理失敗

- 40301: 指定されたストアが無効

- 50000: サーバー内部エラー

例

リクエストの例

{
  "login_id": "user123",
  "login_pass": "password",
  "amount": 1000,
  "currency_id": "JPY",
  "card_first_name": "TEST",
  "card_last_name": "TEST",
  "card_number": "4242424242424242",
  "card_cvv": "123",
  "card_expire_month": "12",
  "card_expire_year": "2025",
  "store": "105",
  "payment_method": "1",
  "payment_selection": "1"
}

成功レスポンスの例１
(Data送信完了後、決済が成功した例)

{
    "message": "Payment completed successfully.",　(← Data送信完了メッセージ)
    "code": 20000, (← HTTPステータスコード)
    "msg": "",
    "results": {　　　　
        "transaction_id": "202541310742FKZRM",
        "transaction_status": "COMPLETED", (← 決済成功メッセージ)
        "processor_msg": "成功",
        "store_id": 105,
        "store_name": "KESSAI",
        "api_type": "EXTERNAL",
        "payment_method": "ONE_TIME",
        "payment_selection": "DIRECT",
        "currency": "JPY",
        "amount": 1000,
        "charged_at": "2024-03-20T05:10:09.002040Z"
   }
}

成功レスポンスの例２
(Data送信完了後、決済が失敗した例)

{
    "message": "Payment completed successfully.",　(← Data送信完了メッセージ)
    "code": 20000,　(← HTTPステータスコード)
    "msg": "",
    "results": {
        "transaction_id": "2024032102692Q9ZBL",
        "transaction_status": "FAILED", (← 決済失敗メッセージ)
        "processor_msg": "発行会社の承認拒否",
        "store_id": 105,
        "store_name": "KESSAI",
        "api_type": "EXTERNAL",
        "payment_method": "ONE_TIME",
        "payment_selection": "DIRECT",
        "currency": "JPY",
        "amount": 1000,
        "charged_at": "2024-03-21T06:25:15.001950Z"
    }
}

※ 決済結果を確認する方法 ※

「Payment completed successfully.」は上位との決済データ通信が問題なく完了した際に出るメッセージです。　決済結果はresultsのbody内に記載される「transaction_status」の以下ステータスを参照します。

成功した場合・・・transaction_status: “COMPLETED”
失敗した場合・・・transaction_status: “FAILED”

※上位による否決で「FAILED」の場合、決済結果には必ず「transaction id」が付与されます。

HTTPステータスコード/エラーレスポンスの例

{ "code": 40001, "message": "Missing field: amount" }

送信データに amount(金額）が入っていない場合のメッセージです。送信しているデータを再度確認してください。

[HTTPステータスコードとその意味]

操作の結果に応じて以下のHTTPステータスコードを返します。これらのコードは、通信リクエストが成功したか、特定の種類のエラーが発生したかを示します。なお、弊社では詳細なコード分類をするために、このHTTPステータスコードに独自の数字2桁を追加し、20000、40000、50000などのコードが表示されます。

成功レスポンス

- 200 OK: 通信リクエストが成功し、決済リクエストに関するデータ転送ならびに処理が正常に完了したことを意味するHTTPのステータスコードです。このステータスは、データ通信が成功し、レスポンスボディに決済結果が含まれる場合に返されます。200 OKを受信した場合には、レスポンスボディのresultにて決済結果を参照して下さい。

クライアントエラー系のレスポンス

- 400 Bad Request: クライアントからのリクエストが不正であることを示します。必須パラメータの欠落、データ形式の誤りなどが含まれます。

- 403 Forbidden: クライアントがリクエストした操作を実行する権限がないことを示します。例えば、無効なストアIDが提供された場合などです。このステータスは、認証は成功したが、アクセスが拒否された場合に返されます。

サーバーエラー系のレスポンス

- 500 Internal Server Error: サーバー側でエラーが発生し、リクエストを処理できなかったことを示します。これはサーバーの問題であり、クライアント側で解決できるものではありません。運営者にお問い合わせ下さい。