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

• 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 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) 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",
        "amount": "700"
      }
    ]

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

📘

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 Seller 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 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 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",
          "amount": "700"
        }
      ]

If captureis auto, you must specify the payment split (amount to Seller Merchant and platform fee) 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": "[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":{
       "processing_merchant_id":"submerchant_one"
    }
}'

(2) Capture

You must provide the payment split information in 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.

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":{
      "processing_merchant_id":"submerchant_one",
      "submerchants": [
          {
            "submerchant_id":"submerchant_one",
            "amount":"400",
            "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 on behalf of Seller Merchant 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 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

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 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 from Seller Merchant. (reference)
• If Seller Merchant 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

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

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 customer, 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 from Seller Merchant. (reference)
• If Seller Merchant 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

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

Since the Seller 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: