--- title: "Platform Merchant Payment Processing" description: "How to process payments using the Platform Processing Model, including creating payments, two-step capture, refunds, chargebacks, and a summary of transaction record types." url: "https://docs.priv.staging.komoju-dev.tools/en/docs/platform-model/platform-merchant-payment-processing" source_url: "https://docs.priv.staging.komoju-dev.tools/en/docs/platform-model/platform-merchant-payment-processing.md" language: en last_modified: "2026-03-26" --- To process payments under Marketplace Use Case, you have to adopt Platform Processing Model, where the Platform Merchant acts as the processing merchant. # Create a Payment **(1) Fund flow logic** Case 1: Single Payout Merchant An example use case is a transaction between Airbnb and an Airbnb host, where a single participant fulfills the order. Below is an example of payment processing between a Platform Merchant and one Payout Merchant: ![](https://files.readme.io/f467b32-Create_a_Payment_platform_processing_model_-_single_Payout_Merchant.png) - After payment capture, funds are transferred to the Payout Merchant. - The Platform Merchant specifies the **Platform Fee** amount to be charged to the Payout Merchant. - The Platform Merchant pays KOMOJU's **Payment Processing Fee**, based on the fee rate in its Owned Payment Methods. Case 2: Multiple Payout Merchants An example use case is Uber Eats, where multiple participants, such as a restaurant and a delivery partner, fulfill the order. Below is an example of payment processing involving multiple Payout Merchants: ![](https://files.readme.io/5c9cb8d-Create_a_Payment_platform_processing_-_multiple_Payout_Merchants.png) - The Platform Merchant specifies the payment amount allocated to each Payout Merchant, ensuring the total matches the payment amount. - The Platform Merchant specifies the **Platform Fee** amount charged to each Payout Merchant. - The Platform Merchant pays KOMOJU's **Payment Processing Fee**, based on the fee rate in its Owned Payment Methods. **(2) Create a payment via API** We support three methods for processing **Credit Card payments**: 1. Direct Payment via API: - If you are PCI-DSS compliant, you can handle card details on your server and send customer payment information directly by using the [Payment: Create](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/payments/POST/payments) API. See [this guide](https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/payments-api-overview.md) for more details. 2. Tokenization: If you're not PCI-DSS compliant, use tokenization to avoid handling raw credit card data. - First, request the [Token: Create](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/tokens/POST/tokens) API to tokenize the card details. Refer to [this guide](https://docs.priv.staging.komoju-dev.tools/en/docs/development/tokenizing-payment-details.md) for further instructions. - Once you receive the Token ID, pass it as `payment_details` when creating the payment with the [Payment: Create](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/payments/POST/payments) API. 3. 3D Secure: For payments requiring 3D Secure: - Request the [SecureToken: Create](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/securetokens/POST/secure_tokens) API to generate a secure token, and redirect customers to `authentication_url` depending on the `verification_status`. Refer to [this guide](https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/payments-api-3ds.md) for more details. - Then, use the secure token in the [Payment: Create](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/payments/POST/payments) API to complete the payment. For **non-Credit Card payments**, simply use the [Payment: Create](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/payments/POST/payments) API with the appropriate customer payment details. When creating a payment, you must provide the following in the request: - `submerchant_id` and `amount`: The amount to be transferred to the Payout Merchant when splitting the payment - `platform_fee`: The Platform Fee amount to be charged to the Payout Merchant after transferring the amount above. ```json "platform_details": { "submerchants": [ { "submerchant_id": "submerchant_one", "amount": "1000", "platform_fee": "100" } ] } ``` | Request Attribute | Type | Description | | --- | --- | --- | | `submerchant_id` | string | The `ID` of the Payout Merchant. | | `amount` | integer | The amount to be transferred to the Payout Merchant. | | `platform_fee` | integer | The Platform Fee amount that you're going to charge from the Payout Merchant, which can not exceed the `amount` above. | Based on the above example, `processing_merchant` is `platform_merchant`: - The `platform_merchant`'s credentials are used to process the payment request - The `submerchant`'s balance is credited with the `amount` within `submerchants` array. - The `platform_fee` is transferred from the `submerchant`'s balance to the platform merchant's balance - The `platform_merchant` pays the KOMOJU Payment Processing fee > ℹ️ **Note:** **Must specify the payment split logic when capturing payments** > > When capturing payments, you must provide the payment split information (amount to Payout Merchant and Platform Fee) in the `platform_details` array. This ensures that the payment is split accordingly during capture. If `capture` is set to `true` when creating the payment, you must include the payment split in the initial request. If `capture` is `false`, you can specify the payment split later when requesting the [Payment: Capture](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/payments/POST/payments/%7Bid%7D/capture) API. **(3) Create a payment via Hosted Page** Our Hosted Page feature contains PCI compliance and 3D Secure out of the box. So, this solution is recommended if you're not PCI-DSS compliant. During the checkout, the customers will be redirected to KOMOJU's Hosted Page to complete the payment. [This guide](https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/web-integrations/introduction-to-hosted-page.md) can help you to learn how to create a session for KOMOJU Hosted Page. To initiate a session for the Hosted Page, use the [Session: Create](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/sessions/POST/sessions) API, and provide the following details: - `submerchant_id` and `amount`: The amount to be transferred to the Payout Merchant when splitting the payment - `platform_fee`: The Platform Fee amount to be charged to the Payout Merchant after transferring the amount above. ```json "platform_details": { "submerchants": [ { "submerchant_id": "submerchant_one", "amount": "1000", "platform_fee": "100" } ] } ``` If the `capture` mode is set to `auto`, you must include the payment split in the initial session creation request. For `manual` capture, the split can be specified later when using the [Payment: Capture](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/payments/POST/payments/%7Bid%7D/capture) API for capturing. # Two-step Capture **(1) Authorization** For **credit card payments**, the Platform Merchant can decide whether to authorize or capture the payment immediately by setting the `capture` parameter. If `capture: false` is used, the platform split information is not needed during authorization but must be provided during the capture step. Learn more about two-step capture [here](https://docs.priv.staging.komoju-dev.tools/en/docs/development/advanced-payments/two-step-payments.md). ```curl curl https://komoju.com/api/v1/payments \ -u degica-mart-test: \ -X POST \ -H "Content-Type: application/json" \ -d '{ "amount":"1000", "currency":"JPY", "fraud_details": { "customer_ip": "192.0.2.1", "customer_email": "test@example.com" }, "payment_details":{ "email":"test@example.com", "month":"01", "name":"Taro Yamada", "number":"4111111111111111", "type":"credit_card", "verification_value":"123", "year":"2025" }, "capture":"false", "platform_details":{ } }' ``` **(2) Capture** When capturing the payment, you must specify the split information. The sum of `amount` within `submerchants` array must not exceed the authorized payment amount. Besides, the `platform_fee` can not exceed the `amount` within `submerchants` array. ```curl curl https://komoju.com/api/v1/payments/{PAYMENT_UUID}/capture \ -u degica-mart-test: \ -X POST \ -H "Content-Type: application/json" \ -d '{ "amount":"1000", "platform_details":{ "submerchants": [ { "submerchant_id":"submerchant_one", "amount":"1000", "platform_fee":"100" } ] } }' ``` **(3) Partial Capture** Partial capture is supported for VISA/Mastercard, JCB/AMEX/Diners Club, PayPay, and Merpay. **KOMOJU supports only a single partial capture per transaction; multiple partial captures are not supported**. If you create a payment via API directly ([Payment: Create](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/payments/POST/payments)), partial capture is supported only for VISA/Mastercard and JCB/AMEX/Diners Club. In contrast, if you create a payment via Hosted Page ([Session: Create](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/sessions/POST/sessions)), all four payment methods support partial capture. For example, if the original payment was ¥1000, you can partially capture ¥500. ```curl curl https://komoju.com/api/v1/payments/{PAYMENT_UUID}/capture \ -u degica-mart-test: \ -X POST \ -H "Content-Type: application/json" \ -d '{ "amount":"500", "platform_details":{ "submerchants": [ { "submerchant_id":"submerchant_one", "amount":"500", "platform_fee":"100" } ] } }' ``` # Cancel a Payment **(1) Cancel a Payment via API** You can cancel a payment in a `pending` or `authorized` state via the [Payment: Cancel](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/payments/POST/payments/%7Bid%7D/cancel) API. **(2) Cancel a Payment via Dashboard** A payment in the `pending` or `authorized` state can be cancelled through the Dashboard. # Create a Reverse Refund **(1) Setup** - A Reverse Refund **fully refunds the payment** to the customer, following the original payment split logic at the time of capture. - **Applicable payment methods: VISA/Mastercard, JCB/AMEX/Diners Club, PayPay, Merpay** - The balance of you and each Payout Merchant must be greater than the respective refund amounts. If either balance is insufficient, the refund will not be processed. **(2) Fund flow logic** Case 1: Single Payout Merchant ![](https://files.readme.io/0630d28-Reverse_Refund_platform_processing_-_single_Payout_Merchant.png) Case 2: Multiple Payout Merchants ![](https://files.readme.io/25afdc7-Reverse_Refund_platform_processing_-_multiple_Payout_Merchants.png) The system debits the fund from the Platform Merchant account and refunds it to the customer's account. It then debits the corresponding amount from each Payout Merchant's account and transfers it to the Platform Merchant's account. **(3) Create a Reverse Refund via API** You can initiate a Reverse Refund by requesting the [Payment: Refund](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/payments/POST/payments/%7Bid%7D/refund) API. The platform details can be omitted, and the system will automatically reverse the splits. ```curl curl https://komoju.com/api/v1/payments/{PAYMENT_UUID}/refund \ -u degica-mart-test: \ -X POST \ -H "Content-Type: application/json" \ -d '{ }' ``` **(4) Create a Reverse Refund via Dashboard** A Reverse Refund can be initiated through the Dashboard. # Create a Reverse Refund Request **(1) Setup** - A Reverse Refund Request is for payment methods that do not support automatic refunds. This will **fully refund the payment** to the customer based on the payment split logic at the time of capture. - **Applicable payment methods: Konbini, Bank Transfer, and Pay-Easy** - The balance of you and each Payout Merchant must be greater than the respective refund amounts. If either balance is insufficient, the refund will not be processed. - You must collect the customer's bank account details and provide them to KOMOJU for processing. - KOMOJU charges ¥300 per successful refund from you for each Reverse Refund Request. ([reference](https://help.komoju.com/hc/en-us/articles/4747504546334)) - If a Customer Fee was charged in the original payment, you can choose whether to refund it using the `include_payment_method_fee` parameter. **(2) Fund flow logic** Case 1: Single Payout Merchant ![](https://files.readme.io/ca9ed1b-Reverse_Refund_Request_platform_processing_-_single_Payout_Merchant.png) Case 2: Multiple Payout Merchants ![](https://files.readme.io/45c6d40-Reverse_Refund_Request_platform_processing_-_multiple_Payout_Merchants.png) The system debits the fund from the Platform Merchant account and refunds it to the customer's account. It then debits the corresponding amount from each Payout Merchant's account and transfers it to the Platform Merchant's account. Ultimately, KOMOJU will debit the refund fee (¥300) from the Platform Merchant account. **(3) Create a Reverse Refund Request via API** You can request the [Payment: Refund Request](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/payments/POST/payments/%7Bid%7D/refund_request) API to initiate a Reverse Refund Request along with the customer's bank account information. The platform details can be omitted, and the system will automatically reverse the splits. ```curl curl https://komoju.com/api/v1/payments/{PAYMENT_UUID}/refund_request \ -u degica-mart-test: \ -X POST \ -H "Content-Type: application/json" \ -d '{ "include_payment_method_fee":"true", "customer_name":"ｶﾀｶﾅ", "bank_name":"青森銀行", "bank_code":"0117", "branch_name":"東京支店", "branch_number":"921", "account_type":"ordinary", "account_number":"1234567" }' ``` **(4) Create a Reverse Refund Request via Dashboard** A Reverse Refund Request can be executed through the Dashboard. # Create a Non-Reverse Refund **(1) Setup** A Non-Reverse Refund should be used when: 1. A full refund does not follow the original payment split logic 2. A partial refund is required Notes: - The refund amount can not exceed the original payment amount. - **Applicable payment methods: VISA/Mastercard, JCB/AMEX/Diners Club, PayPay, Merpay** - The balance of you and each Payout Merchant must be greater than the respective refund amounts. If either balance is insufficient, the refund will not be processed. **(2) Fund flow logic** Case 1: Single Payout Merchant ![](https://files.readme.io/998c82b-Non-Reverse_Refund_platform_processing_-_single_Payout_Merchant.png) Case 2: Multiple Payout Merchants ![](https://files.readme.io/b95b1f3-Non-Reverse_Refund_platform_processing_-_multiple_Payout_Merchants.png) You specify the refund amounts for both you and each Payout Merchant. The system debits the Platform Merchant's account and refunds the customer. It then debits the corresponding amount from each Payout Merchant and transfers it to the Platform Merchant. In this example: - A ¥1,000 payment was split into three pieces when capturing the payment: ¥100 to Platform Merchant, ¥630 to Payout Merchant-1, and ¥270 to Payout Merchant-2. - Later, Platform Merchant requests a Non-Reverse Refund and specifies a total refund ¥900 to the customer, which is composed of ¥50 from the Platform Merchant, ¥600 from Payout Merchant-1, and ¥250 to Payout Merchant-2. **(3) Create a Non-Reverse Refund via API** A Non-Reverse Refund can be initiated only via the [Payment: Refund](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/payments/POST/payments/%7Bid%7D/refund) API to avoid manual errors. ```curl curl https://komoju.com/api/v1/payments/{PAYMENT_UUID}/refund \ -u degica-mart-test: \ -X POST \ -H "Content-Type: application/json" \ -d '{ "amount":"900", "platform_details":{ "submerchants": [ { "submerchant_id":"submerchant_one", "amount":"850", "platform_fee":"50" } ] } }' ``` # Create a Non-Reverse Refund Request **(1) Setup** A Non-Reverse Refund Request should be initiated in the following cases: 1. When issuing a full refund that does not follow the original payment split logic. 2. When issuing a partial refund. Notes: - The refund amount can not exceed the original payment amount. - **Applicable payment methods: Konbini, Bank Transfer, and Pay-Easy** - The balance of you and each Payout Merchant must be greater than the respective refund amounts. If either balance is insufficient, the refund will not be processed. - You must collect the customer's bank account details and provide them to KOMOJU for processing. - KOMOJU charges ¥300 per successful refund from you for each Non-Reverse Refund Request. ([reference](https://help.komoju.com/hc/en-us/articles/4747504546334)) - If a Customer Fee was charged in the original payment, you can choose whether to refund it using the `include_payment_method_fee` parameter. **(2) Fund flow logic** Case 1: Single Payout Merchant ![](https://files.readme.io/3596ef7-Non-Reverse_Refund_Request_platform_processing_-_single_Payout_Merchant.png) Case 2: Multiple Payout Merchants ![](https://files.readme.io/0e62c85-Non-Reverse_Refund_Request_platform_processing_-_multiple_Payout_Merchants.png) When issuing a Non-Reverse Refund Request via API, you must specify the amounts to be refunded by both you and each Payout Merchant. The system debits the refund amount from the Platform Merchant's account and refunds it to the customer's bank account. Then, the system debits the corresponding amount from each Payout Merchant's account and transfers it to the Platform Merchant's account. Ultimately, KOMOJU will debit the refund fee (¥300) from the Platform Merchant account. For example: - A ¥1,000 payment was split into three pieces when capturing the payment: ¥100 to Platform Merchant, ¥630 to Payout Merchant-1, and ¥270 to Payout Merchant-2. - Then, Platform Merchant requests a Non-Reverse Refund and specifies a total refund ¥900 to the customer, which is composed of ¥50 from the Platform Merchant, ¥600 from Payout Merchant-1, and ¥250 to Payout Merchant-2. **(3) Create a Non-Reverse Refund Request via API** Use the [Payment: Refund Request](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/payments/POST/payments/%7Bid%7D/refund_request) API to initiate a Non-Reverse Refund Request. You must also provide the customer's bank account information. This type of refund cannot be processed via the Dashboard to avoid manual errors. ```curl curl https://komoju.com/api/v1/payments/{PAYMENT_UUID}/refund_request \ -u degica-mart-test: \ -X POST \ -H "Content-Type: application/json" \ -d '{ "amount":"900", "include_payment_method_fee":"true", "customer_name":"ｶﾀｶﾅ", "bank_name":"青森銀行", "bank_code":"0117", "branch_name":"東京支店", "branch_number":"921", "account_type":"ordinary", "account_number":"1234567", "platform_details":{ "submerchants": [ { "submerchant_id":"submerchant_one", "amount":"850", "platform_fee":"50" } ] } }' ``` # Chargeback **(1) Setup** If the Platform Merchant loses a dispute, as determined by the card issuer, a chargeback will be executed. The entire payment will be returned to the customer, and the corresponding amount will be debited from the Platform Merchant's balance. The chargeback will proceed regardless of whether the Platform Merchant's balance is sufficient. **(2) Fund flow logic** Case 1: Single Payout Merchant ![](https://files.readme.io/568292b-Chargeback_platform_processing_-_single_Payout_Merchant.png) Case 2: Multiple Payout Merchants ![](https://files.readme.io/b28c361-Chargeback_platform_processing_-_multiple_Payout_Merchants.png) Since the Platform Merchant is the processing merchant, you are responsible for the entire chargeback amount. # Summary of transaction record types The following table summarizes the types of records generated based on various actions: | Record type | Description | Deposit/Debit | | --- | --- | --- | | Payment | The payment captured under Platform Merchant's account. | (1) Platform Merchant: Deposit | | Payment Transfer | The amount transferred to the Payout Merchant's account once the payment is captured. | (1) Platform Merchant: Debit (2) Payout Merchant: Deposit | | Platform Fee | The fee that Platform Merchant charges the Payout Merchant for each captured payment. | (1) Platform Merchant: Deposit (2) Payout Merchant: Debit | | Processing Fee | The fee KOMOJU charges the Payout Merchant for each captured payment. The rate varies by payment method. | (1) Platform Merchant: Debit | | Processing Fee Tax | The tax on the Processing Fee. In Japan, this is 10% of the Processing Fee amount. | (1) Platform Merchant: Debit | | Refund | The amount the Payout Merchant refunds to a customer. | (1) Platform Merchant: Debit | | Payment Transfer Return | The amount returned by the Payout Merchant to the Platform Merchant, representing shared responsibility in a refund. | (1) Platform Merchant: Deposit (2) Payout Merchant: Debit | | Refunded Customer Fee | The Customer Fee refunded by the Platform Merchant to the customer. | (1) Platform Merchant: Debit | | Refunded Customer Fee Tax | The tax on the Customer Fee refunded by the Platform Merchant. In Japan, this is 10% of the fee amount. | (1) Platform Merchant: Debit | | Refund Fee | The fee KOMOJU charges the Platform Merchant for a successful **Reverse Refund Request** or **Non-Reverse Refund Request**. | (1) Platform Merchant: Debit | | Refund Fee Tax | The tax on the Refund Fee. In Japan, this is 10% of the Refund Fee amount. | (1) Platform Merchant: Debit | | Chargeback | The amount the Platform Merchant refunds to a customer after losing a dispute, as determined by the card issuer. | (1) Platform Merchant: Debit |