Payment Details

KOMOJU's API strives to provide one generalized interface to many different payment methods. We encapsulate these differences in an object called payment_details.

This payment_details object typically contains any user input that is required for one specific payment method but not others. For example, credit card numbers live inside payment_details, and so does bank transfer contact information and konbini store selection.

payment_details show up not only in requests, but in responses as well. All Payment object responses will contain payment_details - usually slightly different from the input (for example, we do not render full credit card numbers in response payment_details).

APIs That Use Payment Details

Payment: Create

Session: Pay

Token: Create

Customer: Create

Payment Flows

Here are the different payment_details formats and associated UX flows.

Credit Card

Credit card payments require you to collect your customer's card details. If these card details hit your server, then you will be subject to PCI-DSS regulation.

Request AttributeTypeDescription
payment_details[type] *constant"credit_card"
payment_details[number] *stringCard number, no spaces.
payment_details[name]stringCard holder full name as printed on card.
payment_details[month] *stringExpiration date month. e.g. "02".
payment_details[year] *stringExpiration date year last 2 digits. e.g. "29"
payment_details[verification_value]stringCard verification value (CVV) on the back of the card. This is optional but acceptance rates may drop if not provided. Take care to never store this value long term.

Credit card payments are completed synchronously. You will see the payment's final status in the resulting payment object's status attribute, or you will receive an error object.


Konbini payments require you to ask your customer which store they wish to pay at.

Request AttributeTypeDescription
payment_details[type] *constant"konbini"
payment_details[store] *enumConvenience store chain that the customer intends to pay at.
payment_details[email] *stringCustomer email address.
payment_details[phone]stringCustomer phone number.

In the response, you should get a payment object with status "authorized". This "authorized" status is different from credit card authorizing. It means we are waiting for the customer to go to the store and pay in cash. When the customer pays, you will receive a webhook of type payment.captured.

When creating konbini payments directly, it's important to make sure you show your customer payment instructions. The response object will have a payment_details.instructions_url attribute that you can read and present to your customer. KOMOJU will also send this content to the customer's email address, but we see increased conversion rates when instructions are shown directly after paying.

Japanese Bank Transfer

We support domestic Japanese bank transfer payments. The flow is similar to konbini where you collect some info from the customer, submit it to us, and then we wait until the customer performs some action.

Here's the flow from the customer's perspective:

  1. I submit my bank details to merchant (which merchant sends to KOMOJU).
  2. Merchant shows me a bank name and account number (automatically generated for this transaction).
  3. I go to my bank (or bank app) and manually transfer the full amount into the above account.
Request AttributeTypeDescription
payment_details[type] *constant"bank_transfer"
payment_details[email] *stringCustomer email address.
payment_details[family_name] *stringCustomer's family name in alphabet or kanji.
payment_details[given_name] *stringCustomer's given name in alphabet or kanji.
payment_details[family_name_kana] *stringCustomer's family name in kana.
payment_details[given_name_kana] *stringCustomer's given name in kana.
payment_details[phone]stringCustomer's phone number.

Again similar to konbini, we recommend showing the user payment instructions. You'll have a payment_details.instructions_url in the response that you can optionally send your customers to.

Alternatively, you can show the bank details yourself. If you wish to do this, please display all of the following response fields:

Response AttributeTypeDescription
payment_details.bank_namestringName of financial institution that customer must send money to.
payment_details.account_branch_namestringName of branch under the above institution.
payment_details.account_numberstringUsually 6-7 digit account number, generated specifically for this transaction. We will automatically detect when money reaches this account number and capture the payment.
payment_details.account_typestringUsually "普通預金".
payment_details.account_namestringAccount holder name of this transaction's virtual bank account.
payment_details.payment_deadlinedatetimeDeadline by which the customer must complete their transfer.

Mobile Apps (PayPay, LinePay, MerPay, RakutenPay, auPay)

Mobile app payment methods all behave the same. They don't require you to collect any information from the customer, as the only thing that needs to happen is the customer must log in to their app.

Request AttributeTypeDescription
payment_details[type] *constant"paypay", "linepay", "rakutenpay", "aupay"
payment_details[email]stringCustomer email address. We can use this to send a receipt but it's optional.

In the response, you should get a payment object with status "pending", along with a payment_details.redirect_url attribute. Redirect your customer to that URL. When the customer finishes paying, they will be redirected back to your return_url that you specified during payment or session creation, and you will receive a payment.captured webhook.


The full list of supported payment_details objects can be found on the Payment: Create reference, which is always up-to-date with the latest API schema. The vast majority of payment methods behave the same as the above mobile app payment methods.

We recommend using our test mode to get a feel for the general flow. All new accounts get a free test merchant that can make unlimited simulated payments.