Charge(課金)

Charges(課金)は、クレジットカードへ課金をするためのAPIです。 このAPIを用いることで、新規課金取引の作成、すべての課金履歴の表示、個別の課金情報の閲覧、払い戻し処理等を行うことができます。 新規に課金を作成するときには、トークン、CustomerオブジェクトまたはCustomerオブジェクトとCardオブジェクトを使った3種類の課金方法があり、用途によって使い分けをすることができます。

Attribute

Name Type Description
object string

このJSONレスポンスがChargeによるものを示す値の charge

id object_id

ChargeのID、 /chrg(_test)?_[0-9a-z]+/ 形式の一意なオブジェクトを示す文字列。

livemode boolean

本番モード (true) あるいはテストモード(false) charge。

location string

現在のchargeオブジェクトを取得するためのAPIパス。

amount integer

指定された通貨において最小単位、かつ正の整数で表される金額。(例:100サターンは1タイバーツ) サポート通過コード一覧

authorize_uri string

3-D Secureでオーソリを行うURLで、return_uriがある場合に含まれます。

authorized boolean

Chargeがオーソライズされている場合はtrue、まだの場合はfalse。

capturable boolean

課金を売上確定できるか。

capture boolean

Charge作成後に即時売上の場合はtrue、後日にcaptureする場合はfalse(仮売上)。

card card

Chargeに利用したCardオブジェクト。

created datetime

ISO 8601 形式(YYYY-MM-DDThh:mm:ssZ)でcharge作成の協定世界時(UTC)。

currency string

小文字3桁の国際識別コードで、ISO 4217規格 によって定義された通貨(サポート通貨コード一覧)。

customer object_id

Chargeで利用したCustomerのID。

description string

解読可能なchargeの説明。

disputable boolean

課金がチャージバックできるかどうか。

dispute dispute

ChargeがDisputeされた場合に、Disputeオブジェクトが含まれます。

failure_code string

status == failed の場合の失敗コード。可能なコードについては、testing を参照してください。

failure_message string

status == failed の場合の解読可能なメッセージ。

funding_amount integer

加盟店が使用する通貨の最小単位で、正の整数として表される金額。

funding_currency string

funding_amountの通貨。

ip string

Omiseに提供された顧客IP。

metadata object

メタデータをカスタムする (例 {"customer-id": 42}) charge。

paid boolean

Chargeが支払われていればtrue、まだの場合はfalse。

paid_at datetime

課金が支払われたISO 8601形式 (YYYY-MM-DDThh:mm:ssZ)のUTC日時。

refundable boolean

返金が可能かどうか。

refunded integer

返金された金額。

refunds list

Refundオブジェクトのリスト。

return_uri string

3-D Secureでのオーソリ後にリダイレクトするURL。

reversed boolean

Chargeの取消が行われていればtrue、そうでなければfalse。

reversed_at datetime

リバース課金されたISO 8601 形式 (YYYY-MM-DDThh:mm:ssZ) のUTC日時。

reversible boolean

リバース課金が可能かどうか。

schedule object

The schedule associated with the charge.。

source source

課金されたソース。

status string

Chargeのステータスを表す、failedexpiredpendingreversed または successfulのいずれかが含まれます。

transaction object_id

TransactionのID、 /trxn(_test)?_[0-9a-z]+/ 形式の一意なオブジェクトを示す文字列。

voided boolean

chargeが無効化されているかどうか。

Deprecated Attribute

Name Type Description
reference string

return_uriがレスポンスに含まれている場合に、Chargeのリファレンスコードが含まれます。

Example

  • Json Response

課金リストの取得

- GET https://api.omise.co/charges

chargeに属するすべての お客様のアカウントオブジェクトの list を返します。

Request Parameter

Name Type Description
offset integer

(optional、default:0) 返される最初のレコードのオフセット(先頭からスキップするレコードの数)。

limit integer

(optional, default: 20, maximum: 100) 返されたレコード数。

from datetime

(optional, default: 1970-01-01T00:00:00Z) ISO 8601 形式の返されたレコードの最初のUTC日付と時刻(YYYY-MM-DDThh:mm:ssZ)。

to datetime

(optional, default: current UTC datetime) ISO 8601 形式で返されたレコードの最新のUTC日付と時刻(YYYY-MM-DDThh:mm:ssZ)。

order string

(optional, default: chronological) chronological(最初のものから最新のもの)または reverse_chronological (最新のものから最初のもの)のリストのオーダーが返されます。

Example

  • 課金リストの取得

新しい課金の作成

- POST https://api.omise.co/charges

クレジットカードへの課金を行うには、新しい課金(Charge)オブジェクトを作成してください。 テストモードのAPIキーを使用中の場合は、指定されたカードへ請求が行くことはありません。 ※テストモードでは、課金は成功したとみなして動作します。 新しい課金の作成時には、トークン、Customerまたは、CustomerとCardオブジェクトを使った3つの方法があります。

課金の作成に失敗した場合には、下記のエラーコードが返却されます。

Code Description
insufficient_fund 与信限度枠を超えた時に発生します。
stolen_or_lost_card 盗難カード、または紛失カードの場合に発生します。
failed_processing トランザクション処理のプロセスが失敗した場合に発生します。
payment_rejected 何らかの理由により、課金が拒否された場合に発生します。
invalid_security_code セキュリティコードが無効の場合に発生します。
failed_fraud_check カードが不正だと判定した場合に発生します。
invalid_account_number 利用できないカード番号の場合に発生します。

Request Parameter

Name Type Description
amount integer

必須:0以上の符号なし整数を金額として指定、通貨ごとのamountの最小・最大値

capture boolean

任意:"Charge作成後に即時売上の場合はtrue、後日にcaptureする場合はfalse(仮売上)。"。

card object_id

必須または任意:未使用のToken IDを指定します。Customer IDと併用して使うこともできます。Token IDだけで課金を行う時に必須です。

currency string

必須:3桁のISO通貨コード、 サポート通貨コード一覧

customer object_id

必須または任意:利用可能なCustomer IDを指定します。Customerを利用した課金の時に必須です。

description string

任意:Chargeのdescriptionはダッシュボードでのグローバルサーチでの検索対象として利用できます。

ip string

課金者のIPアドレス。

metadata object

任意:お好きなJSONハッシュを課金オブジェクトに紐づけることが可能です。 オーダーID、トラッキング番号、emailアドレス等の顧客のメタデータなどにお使いいただけます。

return_uri string

任意:"3-D Secureでのオーソリ後にリダイレクトするURL。"。

source object_id

(任意) 有効なSOURCE_IDまたはsource のリクエストオブジェクト。

Example

  • トークンを使い、新しい課金を作成する

  • Customerに保存したCardオブジェクトを使い、新しい課金を作成する

  • CustomerとCardオブジェクトを使い、新しい課金を作成する

  • 新しいソースを作成し課金する

  • オフサイトのインターネットバンキング課金を作成する

  • オフサイトのアリペイ料金を作成する

  • 分割払いを作成する

課金情報の取得

- GET https://api.omise.co/charges/CHARGE_ID

過去に作成済みの課金(charge)オブジェクトを取得します。課金は課金ID(charge ID)によって識別されます。ここで返す情報は、課金オブジェクトの作成時に返ってくる情報と同じです。

Example

  • 課金情報の取得

課金説明の更新

- PATCH https://api.omise.co/charges/CHARGE_ID

Chargeオブジェクトのdescriptionを更新するためのAPIです。

Request Parameter

Name Type Description
description string

任意:Chargeのdescriptionはダッシュボードでのグローバルサーチでの検索対象として利用できます。

metadata object

任意:お好きなJSONハッシュを課金オブジェクトに紐づけることが可能です。 オーダーID、トラッキング番号、emailアドレス等の顧客のメタデータなどにお使いいただけます。

Example

  • 課金説明の更新

仮売上の実売上化

- POST https://api.omise.co/charges/CHARGE_ID/capture

仮売上として作成した課金を、実売上化します。仮売上とする課金は事前に「課金の作成」をcapture=falseとして作成しておきます。仮売上は作成されてから30日間が経過すると失効します。その時点までに実売上化しなかった場合、払い戻し済みとして扱われ、実売上化できなくなります。

Example

  • 仮売上の実売上化

仮売上の取消

- POST https://api.omise.co/charges/CHARGE_ID/reverse

仮売上(capture=falseのCharge)を取消すためのAPIです。仮売上の取消後、抑えていた与信枠が解放されます。

Example

  • 仮売上の取消

テストモードで支払った課金にマークを付ける

- POST https://api.omise.co/charges/CHARGE_ID/mark_as_paid

テストモードの目的の一環でもありますが、このエンドポイントを利用することで、テスト課金を支払い済みとして手動でマークできます。

Example

  • テスト課金を支払い済みとしてマークを付ける

テストモードで課金に失敗したとマークを付ける

- POST https://api.omise.co/charges/CHARGE_ID/mark_as_failed

テストモードの目的の一環でもありますが、このエンドポイントを利用することで、テスト課金を失敗したとして手動でマークすることができます。

Example

  • テスト課金を失敗としてマークを付ける