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パス。

acquirer_reference_number string

顧客が行った課金の参照番号です。この情報は、VisaおよびMastercardに向けた決済レポートの一部として送信されます。

amount integer

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

approval_code string

Approval code

authorization_type string

実売上化する最終的な取引金額を決定。詳細はパラメータを参照。

authorize_uri string

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

authorized boolean

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

authorized_amount integer

特定のカードへの課金で、与信確保された金額の上限。

branch object_id_expandable

加盟店が端末を設置している販売拠点。

can_perform_void boolean

TBD

capturable boolean

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

capture boolean

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

captured_amount integer

実売上化の額

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

端末に接続されているハードウェア。

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

Opn Payments課金手数料。

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

merchant_advice string

決済エラーが発生した際の処理方法に関する加盟店へのアドバイスです。

merchant_name string

課金を実行したサブマーチャントの名前です。

注: このフィールドは、加盟店がプラットフォーム向けソリューションを導入している場合にのみ適用されます。プラットフォーム向けソリューションのご利用については、サポートまでお問い合わせください。

merchant_uid string

課金を実行したサブマーチャントのIDです。

注: このフィールドは、加盟店がプラットフォーム向けソリューションを導入している場合にのみ適用されます。プラットフォーム向けソリューションのご利用については、サポートまでお問い合わせください。

metadata object

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

net integer

手数料、利子、およびVATを差引後のfunding_amount。

paid boolean

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

paid_at string

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

partially_refundable boolean

各種課金(クレジットカード、QRコード、PromptPay)が一部返金が可能かどうかを示します。

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

販売拠点のPOS

transaction object_id_expandable

課金のTRANSACTION_ID

transaction_fees object

決済手数料

unmanaged_payment object

管理されていない決済情報

voided boolean

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

zero_interest_installments boolean

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

Example

  • JSON Response

仮売上の実売上化

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

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

Request Parameters

Name Type Description
capture_amount integer

(任意) (オプション) 実売上化する課金通貨の最小単位での金額を表示します。Capture(実売上化) APIによって処理され、お客様のアカウントから加盟店のアカウントに振り込まれる金額です。

この金額は、最終オーソリの場合は与信確保額と等しくなり、事前オーソリの場合は与信確保額の一部になります。

1回の一部実売上化をご利用の場合、このフィールドは必須です

Example

  • 仮売上の実売上化

新しい課金の作成

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

新しい課金を作成する際には、まずトークンを作成してからチャージを作成します。トークン作成はクライアント側かサーバ側のプログラムで行い、チャージについてはサーバ側のプログラム(クライアント側では実装しないでください)で行います。

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

failure_code Description
confirmed_amount_mismatch 決済チャネルからの最終金額と当初の課金金額が一致しない場合に発生します。
failed_fraud_check カードが不正だと判定した場合に発生します。
failed_processing トランザクション処理のプロセスが失敗した場合に発生します。
insufficient_balance/insufficient_fund 与信限度枠を超えた時に発生します。
invalid_account_number/invalid_account 利用できないカード番号の場合に発生します。
payment_cancelled 支払者が決済をキャンセルした場合に発生します。
payment_rejected 何らかの理由により、課金が拒否された場合に発生します。
stolen_or_lost_card 盗難カード、または紛失カードの場合に発生します。
timeout 決済事業者が時間内に応答をしなかった場合に発生します。

Request Parameters

Name Type Description
amount integer

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

currency string

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

authorization_type string

(任意) 以下のいずれか:

a. pre_auth: 事前オーソリは、最終的な取引金額が不明または変更される可能性のある場合に通常行われます。加盟店は見積金額分の枠を、事前に与信確保(オーソリゼーション)します。事前オーソリを行うことで、請求する可能性のある最大金額を確保し、実売上化をする直前で与信確保枠を減らすことができます。

b. final_auth:最終的な取引金額に関して加盟店とお客様の両方が事前に合意しており、与信確保枠の調整が発生しないときに、最終オーソリを行います。この場合、与信確保された全額が決済プロセス中に実売上化されます。

capture boolean

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

card string

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

customer string

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

description string

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

expires_at string

(任意) (オプション) ISO 8601フォーマット(YYYY-MM-DDThh:mm:ssZ)による、希望する課金終了のUTC日時。

以下に対応しています:

  • atome
  • atome_qr
  • mobile_banking_ktb
  • shopeepay
  • shopeepay_jumpapp
  • promptpay
  • econtext

注:このリストはすべてを網羅しているわけではありません。このフィールドがサポートされているかどうかを確認するには、各決済方法を参照してください。

first_charge string

(任意) 繰り返し発生する課金における最初の取引のCharge ID。定期課金を作成する際、承認の可能性を高めるためにオプションのパラメータとして渡されます。

ip string

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

metadata object

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

platform_fee object

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

return_uri string

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

source string

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

transaction_indicator string

(任意) 誰が課金を開始したかを示します。以下のどちらかです。

  • MIT - 加盟店が開始した取引
  • CIT - 顧客が開始した取引

Opnはオーソリリクエストを適宜フォーマットします。

webhook_endpoints array

(任意) (オプション) 課金通知の送信先URL。このフィールドには最大で2つのURLを含めることができます。各URLはセキュア(HTTPS)かつ、以下の条件を満たしている必要があります。

  • ローカルホスト
  • IPv4アドレスまたはIPv6アドレス
  • 数字のみのホスト名

該当する課金と返金(もしあれば)に関連するすべてのイベント通知は、アカウント設定のデフォルトのwebhook_endpointではなく、ここで定義されたURLに配信されます。

zero_interest_installments boolean

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

Example

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

  • 分割払いを作成する

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

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

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

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

  • Charge a card while adding metadata

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

保留中の課金を無効にする

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

課金を無効にする まだ承認されていない(status=pending)課金を無効にします。 以下のsource[type] を持つ課金に対応しています。 alipay_cnalipay_hkbarcode_alipaydanagcashkakaopaypaypay または touch_n_go

Example

  • 課金を無効にする

課金リストの取得

- 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

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

metadata object

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

Example

  • 課金説明の更新

  • Update charge metadata

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