Charge(課金)

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

Attributes

Name Type Description
object string

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

id string

/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

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

branch object_id_expandable

Physical location of a merchant terminal.

capturable boolean

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

capture boolean

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

card card

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

created_at string

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

currency string

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

customer object_id_expandable

課金に紐付けられたCUSTOMER_ID

description string

課金の説明。

device object_id_expandable

Physical hardware linked to a terminal.

disputable boolean

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

dispute dispute

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

expired boolean

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

expired_at string

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

expires_at string

課金の有効期限は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 string

funding_amountの通貨。

interest integer

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

interest_vat integer

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

ip string

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

link object_id_expandable

課金のLINK_ID

metadata object

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

net integer

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

paid boolean

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

paid_at string

課金が支払われた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 string

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

reversible boolean

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

schedule object_id_expandable

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

source source

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

status string

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

terminal object_id_expandable

Point of sale within a branch.

transaction object_id_expandable

課金のTRANSACTION_ID

unmanaged_payment object

Unmanaged payment information

voided boolean

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

zero_interest_installments boolean

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

Example

  • JSON Response

仮売上の実売上化

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

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

Example

  • 仮売上の実売上化

新しい課金の作成

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

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

failure_code Description
confirmed_amount_mismatch Final amount from payment channel does not match original amount charged
failed_fraud_check カードが不正だと判定した場合に発生します。
failed_processing トランザクション処理のプロセスが失敗した場合に発生します。
insufficient_balance/insufficient_fund 与信限度枠を超えた時に発生します。
invalid_account_number/invalid_account 利用できないカード番号の場合に発生します。
invalid_security_code Deprecated。
payment_cancelled Payment cancelled by payer.
payment_rejected 何らかの理由により、課金が拒否された場合に発生します。
stolen_or_lost_card 盗難カード、または紛失カードの場合に発生します。
timeout Payment provider did not respond in time.

Request Parameters

Name Type Description
amount integer

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

currency string

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

capture boolean

(任意, default: true, one of: true, false) 課金が即時売上確定と設定されているかどうか。

card string

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

customer string

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

description string

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

expires_at string

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

ip string

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

metadata object

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

platform_fee object

(任意) プラットフォーム手数料

return_uri string

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

source string

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

zero_interest_installments boolean

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

Example

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

  • 分割払いを作成する

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

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

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

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

  • Charge a card while adding metadata

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

Expire an unauthorized charge

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

Set a charge that has not yet been authorized (status=pending) to expire. Supported by charges with source[type]=barcode_alipay.

Example

  • Expire a charge

課金リストの取得

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

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

Request Parameters

Name Type Description
from string

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

limit integer

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

offset integer

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

order string

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

to string

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

Example

  • 課金リストの取得

List charges for a link

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

Returns a list of charges associated with a link.

Request Parameters

Name Type Description
from string

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

limit integer

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

offset integer

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

order string

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

to string

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

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

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

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

Example

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

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

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

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

Example

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

課金情報の取得

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

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

Example

  • 課金情報の取得

仮売上の取消

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

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

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

Omiseは、お客様のウェブサイト全般における利便性を向上するためにクッキーを利用し、お客様のアクセス、閲覧履歴に関する情報を収集します。 当社のウェブサイトを閲覧し続けることにより、お客様は当社のプライバシーポリシーに同意することとします。 詳細はこちら