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:

• 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:

• 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 API. See this guide 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 API to tokenize the card details. Refer to this guide for further instructions.
   • Once you receive the Token ID, pass it as payment_details when creating the payment with the Payment: Create API.
3. 3D Secure:
   For payments requiring 3D Secure:
   • Request the SecureToken: Create API to generate a secure token, and redirect customers to authentication_url depending on the verification_status. Refer to this guide for more details.
   • Then, use the secure token in the Payment: Create API to complete the payment.

For non-Credit Card payments, simply use the Payment: Create 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.

"platform_details": {
    "submerchants": [
      {
        "submerchant_id": "submerchant_one",
        "amount": "1000",
        "platform_fee": "100",
    }
  ]

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

📘

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 Payment: 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 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 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.

"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 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.

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": "[email protected]"
   },
   "payment_details":{
       "email":"[email protected]",
       "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 theamount within submerchants array.

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), 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), all four payment methods support partial capture.

For example, if the original payment was ¥1000, you can partially capture ¥500.

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

Case 2: Multiple Payout Merchants

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 API to initiate a Reverse Refund. The platform details can be omitted, and the system will automatically reverse the splits.

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)
• 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

Case 2: Multiple Payout Merchants

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

Case 2: Multiple Payout Merchants

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 API to avoid manual errors.

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)
• 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

Case 2: Multiple Payout Merchants

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

Example:

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

Case 2: Multiple Payout Merchants

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: