Get started

As a Platform Merchant (Platform Business), you are required to register a "Seller Merchant" account for each of your sellers/users via our APIs.

Key prerequisites:

1. We only accept Japanese entities (both Corporation and Sole Proprietorship) to register a Seller Merchant account.
2. Seller Merchant must have a Japanese Bank Account to receive payouts in JPY from KOMOJU.

1) Create a Seller Merchant account

Request Merchant: Create API to create a Seller Merchant account with platform_role set to seller.

curl -X POST https://komoju.com/api/v1/merchants \
-u <platform merchant secret key>: \
-d name='New Seller Merchant 1' \
-d platform_role="seller"

2. Query the seller merchant's live_application for required fields

Request Live Application: Show API with seller merchant's uuid you received from the previous step.

curl -X GET https://komoju.com/api/v1/live_application/{id}?locale=en \
-u platform_merchant_secret_key:

Response example

{
    "merchant_id": "5td723eoi9txn8sj545ww2mv1",
    "status": "incomplete",
    "payments_enabled": false,
    "payouts_enabled": false,
    "requested_fields": [
        {
            "field_type": "phone_number",
            "field": "company_information.company_phone",
            "field_name": "Company Phone",
            "field_properties": {
                "minLength": 1,
                "pattern": "^([() \\-_+]*[0-9]){10}[() \\-_+0-9]*$"
            },
            "optional": false
        },
      	...
    ],
    "newly_requested_fields": [],
    "errored_fields": []
}

Within the requested_fields array, you'll find the required information for Seller Merchant registration. If a field's optional parameter is set to false, the Seller Merchant must provide the relevant information. If set to true, they can skip it if they don't have the corresponding details.

Following is the breakdown of each field property.

"field": "visa_mastercard_credit_card.access_restrictions",
"field_name": "Implemented (to be implemented)",
"field_description": "Restrict IP addresses accessible to administrators; if IP addresses cannot be restricted, set access restrictions such as basic authentication on the administrator screen.",
"field_type": "checkbox",
"field_properties": {}
"optional": false

• field is the property name that should be used when submitting information for that field.
• field_name is the localized name for the field that should be shown to the user.
• field_description is a localized explanation of what the field is asking.
• field_type is the type of component that should be displayed.
• field_properties includes information about restrictions on the value of the field.
• optional represents whether the field is required or not.

(1) field_types

Different field_types are meant to help direct the types of form components shown to the user to help differentiate and format expected values.

(2) field_properties

field_properties provide information on the properties of the field.

3. Upload files for seller merchant

Some field_types (single_file_upload, file_upload) require that files be uploaded via our merchant file API first, then the UUID(s) submitted as the value for the live_application.

Request File: Create API to upload the files for Seller Merchant onboarding.

We only accept jpg, png, and pdf formats. Besides, each file size should be smaller than 10MB.

curl -X POST https://komoju.com/api/v1/merchants/{id}/files \
  -u platform_merchant_secret_key: \
  -F "paper=/path/to/file"

The response will look like:

{
    "id": "6ssx1zxovw3fgmdsdd1zuzr5u",
    "resource": "file",
    "filename": "blank.png",
    "size": 998,
    "mime_type": "image/png",
    "created_at": "2023-01-10T12:16:00.819+09:00",
    "updated_at": "2023-01-10T12:16:01.085+09:00"
}

4. Submit fields

Based on the requested_fields received in step 2, information can now be submitted for the Seller Merchant via Live Application: Update API.

Here's an example of submitting company_information.company_name

curl -X PATCH https://komoju.com/api/v1/live_application/{id} \
  -u platform_merchant_secret_key: \
  -d "company_information.company_name=My Company"

If successful, the response will include any additional required fields based on what was just submitted. In the case of company_name, newly_requested_fields will be blank as no additional fields rely on the value company_name.

An example of newly_requested_fields

If you submit sole_proprietor as the company_information.corporation_type

curl -X PATCH https://komoju.com/api/v1/live_application/{id} \
  -u platform_merchant_secret_key: \
  -d "company_information.corporation_type=sole_proprietor"

In the response, see that newly_requested_fields now includes sole_proprietor_proofs.

"newly_requested_fields": [
      {
          "field": "company_information.sole_proprietor_proofs",
          "field_name": "Sole proprietor proofs",
          "field_type": "file_upload",
          "field_properties": {}
      }
  ]

newly_requested_fields are only shown upon update and return new fields that should be added to the form as a result of the last update to live_application.

For fields that allow multiple values (multi_select, file_upload field_types)

Submit an array of values.

curl -X PATCH https://komoju.com/api/v1/live_application/{id} \
  -u platform_merchant_secret_key: \
  -d '{
    "visa_mastercard_credit_card.countermeasures_during_card_registration":
      [ "access_restrictions_during_card_registration"]
  }'

5. Complete the Live Application

The required information may vary based on the seller's type (e.g., corporation, sole proprietorship). Our API responses will guide you through the entire onboarding process, providing additional fields under the requested_fields and newly_requested_fields arrays as needed.

The live application must be completed by filling out all fields until requested_fields, newly_requested_fields, and errored_fields are empty. At this stage, the status field of the application should be set to pending.

The information required typically falls into five categories:

(1) Acceptance of KOMOJU Service Agreements

To provide Platform Model service to your sellers, KOMOJU must establish a direct contractual relationship with them. It requires each Seller Merchant to consent to KOMOJU Merchant Services Terms of Use and Privacy Policy. As the Platform Merchant, you are responsible for ensuring your sellers agree to these terms when registering via your interfaces.

Referencing KOMOJU's service agreement

At a minimum, you must provide your sellers with links to the correct terms and obtain their explicit consent when starting the onboarding process. Here's the recommended process:

1. Request Live Application: Show API to retrieve the URLs of KOMOJU Merchant Services Terms of Use and Privacy Policy from service_agreement.agreed_to_tos field.
2. Display these terms to your sellers on your platform when they opt into the service.
3. Submit your seller's consent back to KOMOJU via service_agreement.agreed_to_tos field in Live Application: Update API.

Here's an example of how to present our terms to your users via your interface.

(2) Company information

Below is a detailed list of the company-related information required for registration.

(3) Personal Information

Below is the required information for the Representative Director and Applicant.

For Corporations:

• The Representative Director and Applicant can be the same person.
• The Applicant must have the authority to make decisions on corporate contracts.

For Sole Proprietorships:

• The Representative Director and Applicant should be the same person, so you only have to complete the representative_director fields.

(4) Site Information

Below is the required information related to your website.

• The store address must match the one listed on the website that hosts the Specified Commercial Transactions Law URL.

(5) Bank Account information

Below is the required bank account information.

For Corporations:

• You can only register a bank account under the same name as the corporation applying.

For Sole Proprietorships:

• You can only register a bank account under the name of the representative or the business name.

Before proceeding, please read this guide to ensure the bank account information is entered correctly.

6. Review submitted information

Request Live Application: Show again to review all submitted information. The submitted_fields array will display the information you've already provided.

7. Set up webhook

You can set up webhooks to subscribe to events and receive notifications when there are updates to the review status of a Seller Merchant's application.

• Learn more about Webhook events for Platform Model here

8. Specify Seller Merchant's Owned Payment Methods

You will need to apply for the payment methods your Seller Merchant intends to use. To view applicable payment methods to apply for, use the Live Application: Payment Methods API which will return the following:

curl -X GET https://komoju.com/api/v1/live_application/{id}/payment_methods \
  -u platform_merchant_secret_key:

• submitted_payment_methods lists the payment methods Seller Merchant has already applied for.
• unsubmitted_payment_methods lists the applicable payment methods Seller Merchant has not yet applied for.

To apply for a specific payment method, request Live Application: Update Payment Method API.

Below are the details when applying for each payment method:

(1) VISA/MasterCard

Payment methods: visa_mastercard_credit_card

Available for corporation and sole_proprietor

Note: 3D Secure 2.0 will be used for all credit card payments except some integration types. For more details, please see this article (Japanese).

To enable credit card payments for your Seller Merchant, you will have to provide additional information about their business.

1st stage questionnaire:

2nd stage questionnaire: Reporting on Security Measures

KOMOJU has been requested by the Ministry of Economy, Trade and Industry (METI), the Japan Credit Association (JCA), and other organizations to request that EC merchants planning to introduce new credit card payment systems declare the status of their security measures based on the "Security Checklist" developed by the Credit Transaction Security Measures Council.

The "Security Checklist" covers the basic security measures set forth in the "Credit Card Security Guidelines (Version 4.0)" published by METI.

Topic 1: Measures against inadequate access restrictions on the administrator's screen and administrator ID/PW mismanagement

Topic 2: Measures against inadequate settings due to exposure of data directories

Topic 3: Periodic vulnerability assessments or penetration tests, and measures to address web application vulnerabilities.

Topic 4: Installation and operation of anti-virus software as measures against malware

Topic 5: Countermeasures against malicious validation and credit masters

Topic 6: Countermeasures against unauthorized login

Topic 7: If you answered true to visa_mastercard_credit_card.have_countermeasures_against_unauthorized_login, please answer the following questions regarding the anti-fraud login measures implemented in your system.

• access_restrictions_during_card_registration: Restrict access from suspicious IP addresses
• mfa_implementation_during_card_registration: Identification by two-factor authentication, etc.
• user_information_validation_during_card_registration: Confirmation of personal information at the time of member registration
• fraud_detection_system_during_card_registration: Fraud detection system (Fraud service)
• access_restrictions_during_authentication: Restrict access from suspicious IP addresses
• mfa_implementation_during_authentication: Identification by two-factor authentication, etc.
• login_attempt_restriction_during_authentication: Tighten limits on the number of login attempts (to address account password cracking)
• login_notification_during_authentication: Email and SMS notifications upon login, throttling, etc.
• device_fingerprint_during_authentication: Device fingerprints, etc.
• access_restrictions_during_user_data_modification: Restrict access from suspicious IP addresses
• mfa_implementation_during_user_data_modification: Identification by two-factor authentication, etc.
• fraud_detection_system_during_user_data_modification: Fraud detection system (Fraud service)

(2) JCB/AMEX/Diners (Japan)

Payment methods: jcb_amex_diners_credit_card

Available for corporation and sole_proprietor

Note: 3D Secure 2.0 will be used for all credit card payments except some integration types. For more details, please see this article (Japanese).

To enable credit card payments for your Seller Merchant, you will have to provide additional information about their business.

1st stage questionnaire:

2nd stage questionnaire: Reporting on Security Measures

Same security checklist as VISA/MasterCard above, using the jcb_amex_diners_credit_card field prefix instead of visa_mastercard_credit_card.

(3) PayPay

Payment methods: paypay

Available for corporation and sole_proprietor

The following information is required when applying for PayPay:

(4) Merpay

Payment methods: merpay

Available for corporation only.

The following information is required when applying for Merpay:

(5) Bank Transfer

Payment methods: bank_transfer

Available for corporation and sole_proprietor

No additional information is required when applying for Bank Transfer.

(6) Pay-easy

Payment methods: pay_easy

Available for corporation and sole_proprietor

No additional information is required when applying for Pay-easy.

(7) Konbini

Payment methods: convenience_store

Available for corporation and sole_proprietor

The following information is required when applying for Konbini:

(8) 7-Eleven

Payment methods: seven_eleven

Available for corporation only

For 7-Eleven payment, there is a screening process to ensure that the site and operation are in line with the regulations set by 7-Eleven. The expected review time is approximately one to two months after applying.

The following information is required when applying for 7-Eleven:

9. (Test environment only) Simulate the Live application status

Once you complete the merchant application and at least one Owned Payment Method application, you'll be able to simulate the result of KOMOJU's review.

(1) Simulate Merchant Application status

Request Live Application: Simulate Status API to simulate whether the merchant application will be accepted or declined.

(2) Simulate Owned Payment Method Application status

Request Live Application: Simulate Payment Method Status API to simulate the status (accepted or declined) of an Owned Payment Method application.