Seller Processing Model (for Platform Use Case)

Process payments with Seller Processing Model

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

Create a Payment

(1) Fund flow logic

Create a Payment (seller processing model)
  • Platform Merchant can specify the amount of Platform Fee in each payment to charge from Seller Merchant.
  • Seller Merchant pays the Payment Processing Fee to KOMOJU since it's the processing 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 can help you learn how to create payments via Payment API.

When making a payment request, you'll have to specify 1) Which Seller Merchant is going to process the payment via processing_merchant_id 2) How much Platform Fee you are going to charge from the Seller Merchant via submerchant_id and platform_fee.

	 "platform_details": { 
			"processing_merchant_id": "submerchant_one",
			"submerchants": [
				{
					"submerchant_id": "submerchant_one",
					"platform_fee": "100",
				}
			]
Request AttributeTypeDescription
processing_merchant_idstringMust specify the ID of the Seller Merchant that processes the payment.
submerchant_idstringThe ID of the Seller Merchant.
platform_feeintegerThe Platform Fee amount to be paid to the Platform Merchant initiating the transaction.

Based on the above example, processing_merchant is submerchant_one

  • The submerchant’s credentials are used to process the payment request
  • The submerchant’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 submerchant 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 customers will be redirected to KOMOJU's Hosted Page to complete the payment instead of staying on your user's website. This guide can help you learn how to create a session for KOMOJU Hosted Page.

First is requesting Session: Create API to specify 1) Which Seller Merchant is going to process the payment via processing_merchant_id 2) How much Platform Fee you are going to charge from the Seller Merchant via submerchant_id and platform_fee.

	 "platform_details": { 
			"processing_merchant": "submerchant_one",
			"submerchants": [
				{
					"submerchant_id": "submerchant_one",
					"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.

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",
   "payment_details":{
      "email":"[email protected]",
      "month":"01",
      "name":"Taro Yamada",
      "number":"4111111111111111",
      "type":"credit_card",
      "verification_value":"123",
      "year":"2025"
   },
	"capture":"false",
	"platform_details":{
		"processing_merchant_id":"submerchant_one"
	}
}'

(2) Capture

You can provide the split information until the capture step. The combination of the transfer amount to the Seller Merchant and the Platform Fee 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":{
		"processing_merchant_id":"submerchant_one",
		"submerchants": [
       {
         "submerchant_id":"submerchant_one",
				 "amount':"900",
         "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":{
		 "processing_merchant_id":"submerchant_one",
		 "submerchants": [
        {
          "submerchant_id":"submerchant_one",
		 		  "amount':"400",
          "platform_fee":"100"
	      }
	   ]
	 }
}'

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

Create a Reverse Refund (seller processing model)

The system debits the fund from Seller 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 Platform Merchant account, and transfers it to Seller Merchant account.

(3) Create a Reverse Refund via API

Request the Payment: Refund API to initiate a Reverse Refund. Besides, you can just omit the platform details 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 on behalf of Seller Merchant via the Dashboard.

Create a Reverse Refund Request

(1) Setup

  • Reverse Refund Request is used for payment methods not supporting automatic refunds. Besides, 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 Seller 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. (reference)
  • If you charged a Customer Fee from the consumer when capturing the payment, you can specify whether to refund it via include_payment_method_fee.

(2) Fund flow logic

Create a Reverse Refund Request (seller processing model)

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

Create a Non-Reverse Refund (seller processing model)

You have to specify how much you and Seller Merchant to refund respectively via API. Then, the system debits the fund from Seller 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 Platform Merchant account, and transfers it to Seller Merchant account.

In this example,

  • A ¥1,000 payment was split into two pieces when capturing the payment: ¥900 to Seller Merchant, and ¥100 to Platform Merchant originally.
  • Later, Platform Merchant requests a Non-Reverse Refund and specifies a total refund ¥900 to the consumer, which is composed of ¥850 from Seller 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, 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":{
		 "processing_merchant_id":"submerchant_one",
		 "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 Seller 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. (reference)
  • If you charged a Customer Fee from the consumer when capturing the payment, you can specify whether to refund it via include_payment_method_fee.

(2) Fund flow logic

Create a Non-Reverse Refund Request (seller processing model)

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

In this example,

  • A ¥1,000 payment was split into two pieces when capturing the payment: ¥900 to Seller Merchant, and ¥100 to Platform Merchant originally.
  • Then, Platform Merchant requests a Non-Reverse Refund Request and specifies the total refund ¥900 to the consumer, which is composed of ¥850 from Seller Merchant and ¥50 from Platform Merchant.
  • KOMOJU charges a refund fee ¥300 from Seller 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.

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":{
		"processing_merchant_id":"submerchant_one",
		"submerchants": [
       {
         "submerchant_id":"submerchant_one",
				 "amount':"850",
         "platform_fee":"50",
	     }
	   ]
	}
}'

Chargeback

(1) Setup

If Seller Merchant loses a dispute based on the card issuer's discretion, we'll execute a chargeback and return the entire payment to the consumer, which is debited from Seller Merchant's balance. The chargeback will be executed regardless of whether the Seller Merchant's balance is sufficient or not.

(2) Fund flow logic

Chargeback (seller processing model)

Since the Seller Merchant is the processing merchant, it should undertake 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:

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