このページは現在翻訳中です。

Charge(課金)

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

Attributes

Name Type Description
object string

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

id object_id

/chrg(_test)?_[0-9a-z]+/に一致するCHARGE_ID

livemode boolean

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

location string

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

amount integer

smallest currency unit(最小通貨単位)での課金金額。

authorize_uri string

決済承認のためのURI(例:3-D Secure)。

authorized boolean

課金が承認されたかどうか。

capturable boolean

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

capture boolean

課金が即時売上確定と設定されているかどうか。

card card

card(カード) 課金されたオブジェクト(カードが課金された場合)

created_at datetime

ISO 8601 形式 (YYYY-MM-DDThh:mm:ssZ)で課金が作成されたUTC日時。

currency currency

ISO 4217 コードで定義された3文字の課金通貨

customer object_id

課金に紐付けられたCUSTOMER_ID

description string

課金の説明。

disputable boolean

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

dispute dispute

Dispute(チャージバック )オブジェクト(請求に異議がある場合)。

expired boolean

課金の有効期限が切れたかどうか。

expired_at datetime

ISO 8601形式 (YYYY-MM-DDThh:mm:ssZ)の、実際に課金の有効期限が切れたUTC日時。

expires_at datetime

課金の有効期限はISO 8601形式(YYYY-MM-DDThh:mm:ssZ)でソース[タイプ]=イーコンテクスト のみです。

failure_code string

status==failedとなった場合のエラーコード。可能なコードについてはtestingをご覧ください。

failure_message string

status==failedの場合にエラーを説明するメッセージ。

fee integer

Omise課金手数料。

fee_vat integer

「手数料」にかかる付加価値税(VAT)。

funding_amount integer

funding_currency(if currency != funding_currency)へ換金後に加盟店に支払われる金額をsmallest currency unit(最少通貨単位)で表したもの。

funding_currency currency

funding_amountの通貨。

interest integer

[分割払い期間](/installment-payment)の間に顧客または加盟店が支払う利息。

interest_vat integer

「利子」にかかる付加価値税(VAT)。

ip string

課金に添付されているIPアドレス。

link object_id

課金のLINK_ID

metadata object

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

net integer

手数料、利子、およびVATを差引後の「資金額」

paid boolean

課金が決済されたかどうか。

paid_at datetime

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

platform_fee object

プラットフォーム手数料

refundable boolean

課金された返金が可能かどうか。

refunded_amount integer

返金された金額。

refunds list

返金オブジェクトのList

return_uri string

3Dセキュアカード認証またはその他の[ソース](/ source-api)承認後に顧客がリダイレクトされるURI

reversed boolean

課金承認が取り消されたかどうか。

reversed_at datetime

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

reversible boolean

リバース課金の取り消しが可能かどうか。

schedule object

課金に紐付けられているスケジュール。

source source

課金されたソースSource(ソースが課金された場合)。

status string

課金のステータス。failedexpiredpendingreversed または successfulのいずれか。

transaction object_id

課金のTRANSACTION_ID

voided boolean

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

zero_interest_installments boolean

加盟店が分割払いの支払いに関する利子を負担するかどうか。

Example

  • JSON Response

新しい課金の作成

- 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 Parameters

Name Type Description
amount integer

(必須) smallest currency unit(最小通貨単位)での課金金額。

currency currency

(必須) ISO 4217 コードで定義された3文字の課金通貨

card object_id

(任意、 場合によって必須) card(カード) 課金されたオブジェクト(カードが課金された場合)

customer object_id

(任意、 場合によって必須) 課金に紐付けられたCUSTOMER_ID

return_uri string

(任意、 場合によって必須) 3Dセキュアカード認証またはその他の[ソース](/ source-api)承認後に顧客がリダイレクトされるURI

source object_id

(任意、 場合によって必須) 課金されたソースSource(ソースが課金された場合)。

description string

(任意だが推奨) 課金の説明。 購入する商品に関する情報(商品の数、商品の種類、配達日など)を入力することで、Omiseが実施する不正検知がより正確になります。

ip string

(任意だが推奨) 課金に紐付けるIPアドレス。 Omiseに、実際のIPアドレスを提供し、不正防止の検査を改善します。

capture boolean

(任意) 課金が即時売上確定と設定されているかどうか。

expires_at datetime

(任意) 課金の有効期限はISO 8601形式(YYYY-MM-DDThh:mm:ssZ)でソース[タイプ]=イーコンテクスト のみです。

metadata object

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

platform_fee[fixed] integer

(任意) 最小通貨単位での固定プラットフォーム手数料。

platform_fee[percentage] float

(任意) プラットホーム手数料は課金のamount(額)割合となる。

zero_interest_installments boolean

(任意) 加盟店が分割払いの支払いに関する利子を負担するかどうか。

Example

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

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

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

  • Charge a card while adding metadata

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

  • 分割払いを作成する

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

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

課金情報の取得

- GET https://api.omise.co/charges/{id}

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

Example

  • 課金情報の取得

課金説明の更新

- PATCH https://api.omise.co/charges/{id}

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

Request Parameters

Name Type Description
description string

(任意だが推奨) 課金の説明。 購入する商品に関する情報(商品の数、商品の種類、配達日など)を入力することで、Omiseが実施する不正検知がより正確になります。

metadata object

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

Example

  • Update charge metadata

  • 課金説明の更新

課金リストの取得

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

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

Request Parameters

Name Type Description
from datetime

(任意, default: 1970-01-01T00:00:00Z) ISO 8601 形式(YYYY-MM-DDThh:mm:ssZ)で返されたレコードの最新のUTC日時。

limit integer

(任意, default: 20, maximum: 100) 返されるレコードの数。

offset integer

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

order string

(任意, default: chronological) listのオーダーがchronological (古い順) or reverse_chronological (新しい順)で返されます。エントリがない場合は nullとなります。

to datetime

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

Example

  • 課金リストの取得

仮売上の実売上化

- POST https://api.omise.co/charges/{id}/capture

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

Example

  • 仮売上の実売上化

Expire an unauthorized charge

- POST https://api.omise.co/charges/{id}/expire

Example

  • Expire a charge

List events

- GET https://api.omise.co/charges/{id}/events

Request Parameters

Name Type Description
from datetime

(任意, default: 1970-01-01T00:00:00Z) ISO 8601 形式(YYYY-MM-DDThh:mm:ssZ)で返されたレコードの最新のUTC日時。

limit integer

(任意, default: 20, maximum: 100) 返されるレコードの数。

offset integer

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

order string

(任意, default: chronological) listのオーダーがchronological (古い順) or reverse_chronological (新しい順)で返されます。エントリがない場合は nullとなります。

to datetime

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

Example

  • List charge events

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

- POST https://api.omise.co/charges/{id}/mark_as_failed

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

Example

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

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

- POST https://api.omise.co/charges/{id}/mark_as_paid

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

Example

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

仮売上の取消

- POST https://api.omise.co/charges/{id}/reverse

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

Example

  • 仮売上の取消