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.

💳

Payment details example (credit card)

Open Recipe

Request Attribute	Type	Description
`payment_details[type]` *	constant	"credit_card"
`payment_details[number]` *	string	Card number, no spaces.
`payment_details[name]`	string	Card holder full name as printed on card.
`payment_details[month]` *	string	Expiration date month. e.g. "02".
`payment_details[year]` *	string	Expiration date year last 2 digits. e.g. "29"
`payment_details[verification_value]`	string	Card 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

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

🏬

Payment details example (konbini)

Open Recipe

Request Attribute	Type	Description
`payment_details[type]` *	constant	"konbini"
`payment_details[store]` *	enum	Convenience store chain that the customer intends to pay at.
`payment_details[email]` *	string	Customer email address.
`payment_details[phone]`	string	Customer 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:

I submit my bank details to merchant (which merchant sends to KOMOJU).
Merchant shows me a bank name and account number (automatically generated for this transaction).
I go to my bank (or bank app) and manually transfer the full amount into the above account.

🏛️

Payment details example (bank transfer)

Open Recipe

Request Attribute	Type	Description
`payment_details[type]` *	constant	"bank_transfer"
`payment_details[email]` *	string	Customer email address.
`payment_details[family_name]` *	string	Customer's family name in alphabet or kanji.
`payment_details[given_name]` *	string	Customer's given name in alphabet or kanji.
`payment_details[family_name_kana]` *	string	Customer's family name in kana.
`payment_details[given_name_kana]` *	string	Customer's given name in kana.
`payment_details[phone]`	string	Customer'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 Attribute	Type	Description
`payment_details.bank_name`	string	Name of financial institution that customer must send money to.
`payment_details.account_branch_name`	string	Name of branch under the above institution.
`payment_details.account_number`	string	Usually 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_type`	string	Usually "普通預金".
`payment_details.account_name`	string	Account holder name of this transaction's virtual bank account.
`payment_details.payment_deadline`	datetime	Deadline 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.

📱

Payment details example (PayPay)

Open Recipe

Request Attribute	Type	Description
`payment_details[type]` *	constant	"paypay", "linepay", "rakutenpay", "aupay"
`payment_details[email]`	string	Customer 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.

Others

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.