Platform Processing Model (for Marketplace Use Case)

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

Create a Payment

(1) Fund flow logic

Case 1: Single sub-merchant participation

Create a Payment (platform processing - single sub-merchant)

Case 2: Multiple sub-merchants participation

Create a Payment (platform processing - multiple sub-merchants)
  • 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 send customer payment info directly to us and create a payment via Payment API.

You need to request the Payment: Create API. Besides, this guide to learn how to create payments via Payment API.

During request, you'll have to specify how much Payment Transfer and Platform Fee you are going to charge from each Payout Merchant via submerchant_id, amountand platform_fee

	 "platform_details": { 
			"submerchants": [
				{
					"submerchant_id": "submerchant_one",
          "amount": "1000",
					"platform_fee": "100",
				}
			]
Request AttributeTypeDescription
submerchant_idstringThe ID of the payout merchant.
amountintegerThe amount to be transferred to the payout merchant
platform_feeintegerThe amount to be paid to the platform merchant initiating the transaction

Based on the above example, processing_merchant is platform_merchant

  • The platform_merchant’s credentials are used to process the payment request
  • The platform_merchant’s balance is credited with the payment amount
  • The platform_fee is transferred from the submerchant’s balance to the platform merchant’s balance
  • The Platform Merchant pays the KOMOJU fee

(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 buyers will complete the checkout process via KOMOJU's hosted pages instead of your website. This guide can help you to learn how to create a session for KOMOJU Hosted Page.

The first step is requesting Session: Create API to specify 1) Which Payout Merchant is going to receive a transfer from this payment 2) How much Payment Transfer and Platform Fee you are going to charge from each Payout Merchant

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

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.

curl https://komoju.com/api/v1/payments
-u degica-mart-test: \
-X POST \
-H "Content-Type: application/json" \
-d '{
   "amount":"1000",
   "currency":"JPY",
   "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

You can provide the split information until the capture step. The transfer amount to the sub-merchant 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.

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"
	      }
	   ]
	 }
}'

Create a Reverse Refund

(1) Common context

  • Reverse Refund will fully reverse the payment back to the consumer according to the split logic during payment capture.
  • 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 sub-merchant participation

Reverse Refund (platform processing - single sub-merchant)

Case 2: Multiple sub-merchants participation

Reverse Refund (platform processing - multiple sub-merchants)

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 actually just 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) Common context

  • Reverse Refund Request is used for payment methods not supporting automatic refunds, and it will fully reverse the payment back to the consumer according to the split logic during payment capture.
  • 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.
  • KOMOJU will charge ¥300 refund fee for each successful Reverse Refund Request refund. (reference)
  • If you charged a Customer Fee from the consumer when capturing the payment, you can decide whether to refund it via include_payment_method_fee.

(2) Fund flow logic

Case 1: Single sub-merchant participation

Reverse Refund Request (platform processing - sub-merchant)

Case 2: Multiple sub-merchants participation

Reverse Refund Request (platform processing - multiple sub-merchants)

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

Example:

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) Common context

You should initiate a Non-Reverse Refund when:

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

Other key points:

  • The sum of the refund 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 sub-merchant participation

Case 2: Multiple sub-merchants participation

Non-Reverse Refund (platform processing - multiple sub-merchants)

You have to specify how much you and your user 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 two pieces: ¥900 to Payout Merchant, and ¥100 to Platform Merchant originally.
  • Then, Platform Merchant requests a Non-Reverse Refund and specifies the total refund ¥900 to the consumer, which is composed of ¥850 from Payout Merchant and ¥50 from Platform Merchant

(3) Create a Non-Reverse Refund via API

You can only request the Payment: Refund API to initiate a Non-Reverse Refund. In contrast, the Dashboard is not available to initiate it.

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) Common context

You should initiate a Non-Reverse Refund Request when:

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

Other key points:

  • The sum of the refund 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.
  • KOMOJU will charge ¥300 refund fee for each successful Non-Reverse Refund Request refund.
  • If you charged a Customer Fee from the consumer when capturing the payment, you can decide whether to refund it via include_payment_method_fee.

(2) Fund flow logic

Case 1: Single sub-merchant participation

Case 2: Multiple sub-merchants participation

Non-Reverse Refund Request (platform processing - multiple sub-merchants)

You have to specify how much you and your user 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 two pieces: ¥900 to Payout Merchant, and ¥100 to Platform Merchant originally.
  • Then, Platform Merchant requests a Non-Reverse Refund and specifies the total refund ¥900 to the consumer, which is composed of ¥850 from Payout Merchant and ¥50 from Platform Merchant
  • 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. In contrast, the Dashboard is not available to initiate it.

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) Common context

If you lost a dispute based on card issuer's discretion, we'll execute chargeback and return the entire payment to the consumer, 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 sub-merchant participation

Case 2: Multiple sub-merchants participation

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

Summary of transaction record types

Based on all payment-related actions above, there are multiple kinds of records generated. Below is the summary:

Record typeDescriptionDeposit/Debit
PaymentThe payment captured under Platform Merchant's account.- Platform Merchant: Deposit
Payment TransferThe amount transferred to Payout Merchant account after the payment is captured.- Platform Merchant: Debit
- Payout Merchant: Deposit
Platform FeeThe fee that Platform Merchant charges from Payout Merchant in each payment.- Platform Merchant: Deposit
- Payout Merchant: Debit
Processing FeeThe fee that KOMOJU charges from Platform Merchant in each payment. The rate can be various depending on the payment method.- Platform Merchant: Debit
Processing Fee TaxThe tax of Processing Fee. In Japan, it's 10% of Processing Fee amount.- Platform Merchant: Debit
RefundThe amount Platform Merchant refunds to a consumer.- Platform Merchant: Debit
Payment Transfer ReturnThe refund amount Payout Merchant is in charge of.- Platform Merchant: Deposit
- Payout Merchant: Debit
Refunded Customer FeeThe customer fee that Platform Merchant refunds to a consumer.- Platform Merchant: Debit
Refunded Customer Fee TaxThe tax of the customer fee that Platform Merchant refunds to a consumer. In Japan, it's 10% of Customer Fee amount.- Platform Merchant: Debit
Refund FeeThe fee KOMOJU charges from Platform Merchant after completing a Reverse Refund Request or Non-Reverse Refund Request.- Platform Merchant: Debit
Refund Fee TaxThe tax of refund fee. In Japan, it's 10% of Refund Fee amount.- Platform Merchant: Debit
ChargebackThe amount Platform Merchant refunds to a consumer because of losing a dispute based on the card issuer's discretion.- Platform Merchant: Debit