カスタム支払い連携

このドキュメントでは、Monetization が標準ではサポートしていないサードパーティ支払いプロバイダーに対する支払い処理サポートを有効にする方法、または Monetization 外部の連携プロセスで支払い処理ロジックを扱う場合の方法を説明します。
カテゴリ:

このドキュメントのトピック:

Monetization におけるサードパーティ支払い処理

サードパーティ支払い処理は、同期方式と非同期方式の 2 つの方法で実現できます。同期方式では支払い連携コンポーネントから即時応答が必要ですが、非同期方式では Monetization から請求書を抽出し、その後のタイミングで支払いをインポートします。

非同期支払い処理

非同期支払い処理では、Monetization から請求書をエクスポートし、支払いは完全に Monetization の外部で処理されます。支払い処理結果が得られたら、CSV ファイルまたは Monetization API 経由でインポートします。

請求書のエクスポート

Monetization から請求書をエクスポートするには、invoice export mapper を設定して exporting job をスケジュールし、ファイルを SFTP ロケーションへエクスポートします。または、Webhook による invoice creation を購読し、新しい請求書が作成されるたびに指定 URL アドレスへ invoice request を送信させます。

Exporting job – CSV file to SFTP

請求書を CSV ファイルとしてエクスポートするには、請求書パラメーターを CSV ファイル列にマッピングする Invoice Export mapper を設定する必要があります。Monetization User Interface では、Business configuration Export Invoice mappers でこの設定を行えます。

Example of invoice export mapper configuration Figure 1: 請求書エクスポート mapper 設定の例

請求書エクスポートは Exporting Jobs を通じてスケジュールされます。これは一回限りのタスク、または特定期間に実行される自動タスクにできます。Exporting Job はエクスポートされた CSV ファイルを対応する SFTP ロケーション storage/invoice/folder_name/file_name.csv に保存します。

Example of invoice export job Figure 2: 請求書エクスポートジョブの例

通知 - webhook メソッド

webhook による請求書エクスポートでは、請求書作成直後に請求書を受信できます。これは Invoice Notification Rule を設定することで実現されます。このルールは、作成された各請求書を JSON body request として、事前設定された header option とともに指定 URL アドレスへ送信します。

Example of invoice creation webhook configuration Figure 3: 請求書作成 webhook 設定の例

支払いのインポート

payment import mapper を設定して支払い CSV ファイルを SFTP 入力ロケーションにアップロードするか、Monetizations REST API を利用することで、支払いトランザクションを Monetization にインポートできます。

SFTP による CSV file import

Monetization が CSV ファイル経由で支払いトランザクションをインポートするには、Payment Import Mapper を設定しておく必要があります。この設定は Monetization User Interface の Business configuration Import Payment mappers で行えます。

Payment mapper では、CSV 列を支払いトランザクションパラメーターにマッピングし、アップロードファイルに含まれる必要があるファイル接頭辞を定義できます。

ファイルは SFTP サーバーの edl/input フォルダーにアップロードされ、処理結果に応じて edl/processed、edl/successful、edl/error、edl/rejected フォルダーへ移動されます。

Example of payment import mapper configuration Figure 4: 支払いインポート mapper 設定の例

API call によるインポート

Monetization API 経由で支払いトランザクションをインポートするには、トランザクション詳細を含む JSON リクエストを Monetization REST API に POST します。

認証

Monetization API は Bearer Token 認証を使用します。

  1. username、password、特定の site code を指定して Authentication request を実行します。
  2. レスポンスから token を取得します。
  3. 以降のリクエストで Authorization ヘッダーを Bearer <token> に設定します。
  4. token は 5 分後に期限切れになります。
URL: {{api_url}}/authenticate

Headers
Content-Type:application/json

Body
{
    "username": "your_monetization_username",
    "password": "password",
    "site_code": "your_monetization_site_code - subdomain"
}
支払いインポートリクエスト
URL: {{api_url}}/api/v1/import

Headers
Content-Type:application/json
Authorization:Bearer {{auth_token}}
Data-Type:Payment

Body
{
    "invoice_id": 123,
    "transaction_identifier": "T-1233-cew3-445f-feew3",
    "amount": 150,
    "transaction_time": 1600613169000,
    "currency": "EUR",
    "method": "other",
    "type": "charge",
    "provider": "stripe"
}

同期支払い処理

同期支払い処理では、Monetization と支払い連携コンポーネントの間で同期通信が必要です。この処理方式により、クレジット/デビットカードのオーソリゼーションと即時支払いが可能になります。

支払い処理関連リクエストの送信先を Monetization に設定します。Monetization には、返却を期待する事前定義済みレスポンスがあります。この処理方式により、顧客上で支払い方法参照を保存でき、自動支払い回収プロセスをサポートします。

Monetization にとって、この連携プロセスは既存プロバイダー（Stripe、Braintree など）との標準連携と実質的に同じです。ただし、通信はユーザーが開発したコンポーネントを通じて実行され、このコンポーネントがローカル支払いプロバイダーへのゲートウェイとして動作します。

同期支払い処理をサポートするための主要操作:

  • Setup Intent
  • Authorize
  • Capture
  • Charge

サードパーティ支払いプロバイダーの設定

サードパーティ支払いプロバイダー連携を設定するには、third-party payment gateway profile を設定し、Monetization がリクエストを送信する URL を指定します。

これは UI の System configuration Payment gateways から、または Monetization REST API 経由で Payment Gateway Profile を作成することで実現できます。

URL: {{api_url}}/api/v1/payment-gateway-profiles

Headers
Content-Type:application/json
Authorization:Bearer {{auth_token}}

Request
{
    "provider": "third-party",
    "headers": {
        "PGW_URL": "URL to your payment gateway"
    }
}

顧客操作

顧客操作は、サードパーティ支払いプロバイダーが顧客管理をサポートする場合にのみ適用されます。支払いプロバイダーが顧客管理をサポートしていない場合、顧客 ids は任意の値（例: リクエストの Unix タイムスタンプ）に置き換えることができます。

顧客の作成（カードなし）

支払いプロバイダーサービス上に顧客をオブジェクトとして作成します。

Monetization から送信されるリクエスト:

{
    "action": "create_customer",
    "content": {
        "customer": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
    }
}

期待されるレスポンス:

HTTP Status: 201 Created

{
    "customer": {
        "id": "payment_provider_customer_id"
    }
}

顧客の更新

支払いプロバイダーサービス上の顧客オブジェクトを更新します。

Monetization から送信されるリクエスト:

{
    "action": "update_customer",
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
    }
}

期待されるレスポンス:

HTTP Status: 204 No Content

No Response Body

顧客の読み取り

支払いプロバイダーサービスから顧客オブジェクトを読み取ります。

{
    "action": "read_customer",
    "content": {
        "id": "payment_provider_customer_id_1"
    }
}

期待されるレスポンス:

HTPP Status: 200 OK

{
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        },
        "credit_cards": [
            {
                "is_default": true,
                "card_holder_name": "John Anderson",
                "expiration_month": "03",
                "expiration_year": "2026",
                "type": "Mastercard",
                "token": "payment_provider_card_token",
                "last_four": "1234"
            }
        ]
    }
}

顧客の削除

支払いプロバイダーサービスから顧客オブジェクトを削除します。

Monetization から送信されるリクエスト:

{
    "action": "delete_customer",
    "content": {
        "id": "payment_provider_customer_id_1"
    }
}

期待されるレスポンス:

HTTP Status: 204 No Content

No Response Body

カード操作

カード操作とは、クレジットカードとデビットカードの設定または削除を指します。

Setup（setup card request）

顧客がクレジットカード詳細を入力できるプロセスをトリガーします。詳細はトークン化され、Monetization に保存されます。新しいクレジットカードを追加するリクエストがあると、Monetization は setup request を連携コンポーネントへ送信します。

連携コンポーネントは、支払いプロバイダーサービスに関連するロジックを処理し、レスポンスとして redirect URL を Monetization に返す必要があります。その後、顧客は提供された URL にリダイレクトされ、支払いプロバイダーがホストするフォームで顧客のカード詳細を収集してトークン化します。

Credit card setup Figure 5: クレジットカード設定

Monetization から送信されるリクエスト:

{
    "action": "setup",
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
        "custom_attributes": {
            "callback_url": "https://callbackurl.com"
        }
    }
}

期待されるレスポンス:

HTTP Status: 201 Created

{
    "customer": {
        "id": "payment_provider_customer_id"
    },
    "redirect_url": "https://card-data-collection-form.com"
}

カードの削除

支払いプロバイダーサービス経由でクレジットカード参照削除ロジックを処理するリクエストを連携コンポーネントへ送信し、成功後に Monetization から参照を削除します。

Monetization から送信されるリクエスト:

{
    "action": "delete_credit_card",
    "content": {
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

期待されるレスポンス:

HTTP Status: 204 No Content

No Response Body

トランザクション操作

トランザクション操作とは、保存済み支払い方法（クレジット/デビットカード）トークンに対して実行される取引アクションを指します。これらのアクションには次が含まれます。

Authorization

Authorization は、顧客の支払い方法上で資金を承認（ロック）するために使用されます。Authorizations は後で Captured または Voided にできます。以下のリクエストは連携コンポーネントへ送信されます。連携コンポーネントは支払いプロバイダーサービスのロジックを処理し、レスポンスを返す必要があります。

Monetization から送信されるリクエスト:

{
    "action": "authorize",
    "content": {
        "amount": 20.5,
        "currency": "EUR",
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

期待されるレスポンス:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Capture

Capture は、以前の Authorization request で承認された資金の回収を指します。回収額は承認額と同額、またはそれより低い金額にできます。

回収されなかった承認済み資金は、支払いプロバイダーサービスによって顧客へ戻されます。以下のリクエストは連携コンポーネントへ送信されます。連携コンポーネントは支払いプロバイダーサービスのロジックを処理し、レスポンスを返す必要があります。

Monetization から送信されるリクエスト:

{
    "action": "capture",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234",
        "amount": 10.5
    }
}

期待されるレスポンス:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 10.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Charge

Charge は、資金の承認と回収を単一の即時トランザクションとして実行します。以下のリクエストは連携コンポーネントへ送信されます。連携コンポーネントは支払いプロバイダーサービスのロジックを処理し、レスポンスを返す必要があります。

Monetization から送信されるリクエスト:

{
    "action": "charge",
    "content": {
        "amount": 25.5,
        "currency": "EUR",
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

期待されるレスポンス:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Void

Void 操作は Authorization トランザクションを無効化し、承認済み資金を解放します。以下のリクエストは連携コンポーネントへ送信されます。連携コンポーネントは支払いプロバイダーサービスのロジックを処理し、レスポンスを返す必要があります。

Monetization から送信されるリクエスト:

{
    "action": "void",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234"
    }
}

期待されるレスポンス:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Refund

Refund は顧客に資金を返金し、以前の Charge または Capture トランザクションを参照します。以下のリクエストは連携コンポーネントへ送信されます。連携コンポーネントは支払いプロバイダーサービスのロジックを処理し、レスポンスを返す必要があります。

Monetization から送信されるリクエスト:

{
    "action": "refund",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234",
        "amount": 10.5
    }
}

期待されるレスポンス:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

エラー処理

連携コンポーネントで操作が成功しなかった場合は、200-300 の範囲外の任意のステータスと、レスポンス本文内のエラーメッセージを返します。

前へ
デバイス