To process payments under Marketplace Use Case, you have to adopt Platform Processing Model that Platform Merchant is the processing merchant.

Create a Payment

(1) Fund flow logic

Case 1: Single Payout Merchant Participant

Case 2: Multiple Payout Merchant Participants

• Platform Merchant can specify the amount of payment transferred to each Payout Merchant in each payment. Besides, the aggregation should be equal to the total payment amount.
• Platform Merchant can specify Platform Fee charged from each Payout Merchant
• Platform Merchant pays the Payment Processing Fee to KOMOJU. The fee rate is specified in Owned Payment Methods of Platform Merchant.

(2) Create a payment via API

If you're PCI-DSS compliant, you can have card details hit your server and send customer payment info directly to us by creating a payment via Payment API.

You need to request the Payment: Create API. This guide can help you learn how to create payments via Payment API.

When making a payment request, you'll have to specify 1) how much Payment Transfer should be transferred to each Payout Merchant via submerchant_id and amount2) how much Platform Fee you are going to charge from each Payout Merchant via submerchant_id and platform_fee.

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

📘

Must specify the payment split logic when capturing payments

You must specify the amount and platform fee within platform_detailsarray when capturing payments since our system will split the payment based on it.

If you specify capture is true while requesting Payment: Create, you must offer the payment split (amount to Payout Merchant and Platform Fee amount) in platform_details array.

In contrast, if you specify capture is false while requesting Payment: Create, you can offer the payment split information when requesting Payment: Capture afterwards.

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

First is requesting Session: Create API to specify 1) how much Payment Transfer should be transferred to each Payout Merchant 2) how much Platform Fee you are going to charge from each Payout Merchant

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

If captureis auto, you must specify the payment split (amount to Payout Merchant and Platform Fee amount) within platform_detailsarray when requesting Session: Create API.

If captureis manual in requesting Session: Create, you'll need to request Payment: Capture later as you ensure the order can be fulfilled. At that time, you must specify the payment split within platform_detailsarray.

Two-step Capture

(1) Authorization

Regarding credit card type payments, Platform Merchant can decide if the payment should be authorized or be captured immediately via capture parameter in the payment API. It can be created by specifying capture: false. The platform splits are not provided upon authorization, and instead are provided during the capture step. The processing merchant can still be specified if the platform merchant is not the processing merchant.

You can 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": "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

You can provide the split information until the capture step. The combination of the transfer amount to all sub-merchants should not be greater than the payment captured amount

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 when the payment methods are VISA/Mastercard, JCB/AMEX/Diners Club, PayPay, LINE Pay, and Merpay. The platform splits must add up to the partially captured amount. In addition, KOMOJU only supports single partial capture and doesn’t support multiple partial captures.

If you create a payment via API directly ( Payment: Create), only VISA/Mastercard and JCB/AMEX/Diners Club are supported for partial capture.

In contrast, if you create a payment via Hosted Page ( Session: Create), all five payment methods mentioned above are supported for partial capture.

Suppose the original payment was 1000 yen, it can be partially captured for 500 yen like this:

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 given payment that have a state of pending or authorized via Payment: Cancel API.

(2) Cancel a Payment via Dashboard

You'll be able to cancel a payment that have a state of pending or authorized via the Dashboard.

Create a Reverse Refund

(1) Setup

• Reverse Refund will fully reverse the payment back to the customer based on the payment split logic when capturing the payment.
• Applicable payment methods: VISA/Mastercard, JCB/AMEX/Diners Club, PayPay, LINE Pay, Merpay
• Your balance and Payout Merchant's balance should be greater than the amount of refund each is in charge of respectively. Otherwise, the refund will not be processed.

(2) Fund flow logic

Case 1: Single Payout Merchant Participant

Case 2: Multiple Payout Merchant Participants

The system debits the fund from Platform Merchant account and refunds it to the customer’s account of the payment method. Immediately after that, the system also debits the corresponding refund amount from Payout Merchant account and transfers it to Platform Merchant account.

(3) Create a Reverse Refund via API

Request the Payment: Refund API to initiate a Reverse Refund. Besides, you can omit the platform details and the amount and the payment splits will be reversed automatically

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

You'll be able to execute a Reverse Refund via the Dashboard.

Create a Reverse Refund Request

(1) Setup

• Reverse Refund Request is used for payment methods not supporting automatic refunds, and it will fully reverse the payment back to the customer based on the payment split logic when capturing the payment.
• Applicable payment methods: Konbini, Bank Transfer, and Pay-Easy
• Your balance and Payout Merchant's balance should be greater than the amount of refund each is in charge of respectively. Otherwise, the refund will not be processed.
• You must collect customer's bank account and pass it to KOMOJU, so the customer will be able to receive the refund from KOMOJU afterwards.
• KOMOJU will charge ¥300 refund fee for each successful Reverse Refund Request refund from you. (reference)
• If you charged a Customer Fee from the customer when capturing the payment, you can specify whether to refund it via include_payment_method_fee.

(2) Fund flow logic

Case 1: Single Payout Merchant Participant

Case 2: Multiple Payout Merchant Participants

The system debits the fund from Platform Merchant account and refunds it to the customer’s bank account. Immediately after that, the system 1) charges refund fee from Platform Merchant 2) debits the corresponding refund amount from Payout Merchant account and transfers it to 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.

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

You'll be able to execute a Reverse Refund Request via the Dashboard.

Create a Non-Reverse Refund

(1) Setup

You should initiate a Non-Reverse Refund when:

1. Initiate a full refund that does not follow the payment split logic when capturing the payment.
2. Initiate a partial refund

Other key points to know:

• The refund amount can NOT be greater than the original payment amount.
• Applicable payment methods: VISA/Mastercard, JCB/AMEX/Diners Club, PayPay, LINE Pay, Merpay
• Your balance and Payout Merchant's balance should be greater than the amount of refund each is in charge of respectively. Otherwise, the refund will not be processed.

(2) Fund flow logic

Case 1: Single Payout Merchant Participant

Case 2: Multiple Payout Merchant Participants

You have to specify how much you and each Payout Merchant to refund respectively via API. Then, the system debits the fund from Platform Merchant account and refunds it to the customer’s account of the payment method. Immediately after that, the system also debits the corresponding refund amount from Payout Merchant account and transfers it to Platform Merchant account.

In this example,

• A ¥1,000 payment was split into three pieces when capturing the payment: ¥100 to Platform Merchant, and ¥630 to Payout Merchant-1, and ¥270 to Payout Merchant-2 originally.
• Then, Platform Merchant requests a Non-Reverse Refund and specifies the total refund ¥900 to the customer, which is composed of ¥50 from Platform Merchant, ¥600 from Payout Merchant-1, and ¥250 to Payout Merchant-2.

(3) Create a Non-Reverse Refund via API

You can only request the Payment: Refund API to initiate a Non-Reverse Refund. In contrast, it can not be initiated via the Dashboard to prevent 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

You should initiate a Non-Reverse Refund Request when:

1. Initiate a full refund that does not follow the payment split logic when capturing the payment.
2. Initiate a partial refund

Other key points to know:

• The refund amount can NOT be greater than the original payment amount
• Applicable payment methods: Konbini, Bank Transfer, and Pay-Easy
• Your balance and Payout Merchant's balance should be greater than the amount of refund each is in charge of respectively. Otherwise, the refund will not be processed.
• You must collect customer's bank account and pass it to KOMOJU, so the customer will be able to receive the refund from KOMOJU afterwards.
• KOMOJU will charge ¥300 refund fee for each successful Non-Reverse Refund Request refund from you. (reference)
• If you charged a Customer Fee from the customer when capturing the payment, you can specify whether to refund it via include_payment_method_fee.

(2) Fund flow logic

Case 1: Single Payout Merchant Participant

Case 2: Multiple Payout Merchant Participants

You have to specify how much you and each Payout Merchant to refund respectively via API. Then, the system debits the fund from Platform Merchant account and refunds it to the customer’s bank account.
Immediately after that, the system also debits the corresponding refund amount from Payout Merchant account and transfers it to Platform Merchant account.

In this example,

• A ¥1,000 payment was split into three pieces when capturing the payment: ¥100 to Platform Merchant, and ¥630 to Payout Merchant-1, and ¥270 to Payout Merchant-2 originally.
• Then, Platform Merchant requests a Non-Reverse Refund Request and specifies the total refund ¥900 to the customer, which is composed of ¥50 from Platform Merchant, ¥600 from Payout Merchant-1, and ¥250 to Payout Merchant-2.
• KOMOJU charges a refund fee ¥300 from Platform Merchant

(3) Create a Non-Reverse Refund Request via API

You can only request the Payment: Refund Request API to initiate a Non-Reverse Refund Request along with the customer's bank account information. In contrast, it can not be initiated via the Dashboard to prevent 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 you loses a dispute based on the customercard issuer's discretion, we'll execute chargeback and return the entire payment to the customer, which is debited from Platform Merchant's balance. The chargeback will be executed regardless of whether the Platform Merchant's balance is sufficient or not.

(2) Fund flow logic

Case 1: Single Payout Merchant Participant

Case 2: Multiple Payout Merchant Participants

Since the Platform Merchant is the processing merchant, it undertakes the entire chargeback.

Summary of transaction record types

Based on all the actions above, multiple kinds of records will be generated. Below is the summary: