Sessions

When integrating KOMOJU, you will likely interact with Session objects via our API.

In KOMOJU, a session is an optional precursor to a payment. A session is kind of like an invoice that you want a customer to pay. When the customer "completes" the session, a payment is created.

Session contains an amount and currency, as well as a list of payment methods the customer can choose from. Sessions may also contain detailed transaction information, such as an external order number and individual line items that the customer is purchasing.

Our two primary integration types: Hosted Page and Hosted Fields both start out with a session.

Session Statuses

Each session has its own status attribute, which tells you where the session is along its journey.

Session statusMeaning
pendingThe session is still awaiting customer action.
completedThe customer "completed" the session. This typically means a payment was created and either authorized or captured. For customer-mode sessions, this means the session's customer is now populated with payment details.
cancelledThe session was cancelled by the merchant hitting our /sessions/{id}/cancel endpoint.

Session Modes

By default, all sessions are in "payment" mode. This means the user uses the session to create a Payment. Alternatively, you can use sessions to create customer objects as well.

curl -X POST https://komoju.com/api/v1/sessions \
  --user 'sk_live_xxxxxxxxxxxxx:' \
  --data amount=1000 \
  --data currency=JPY \
  --data mode=payment
Session modeMeaning
paymentThe default. Customer uses session to create a payment.
customerAlternative session mode where a Customer resource is created instead of a payment. This customer resource can be used to perform delayed billing, or subscriptions.
customer_paymentThe session when completed creates both a customer and a payment at the same time. This can be convenient if you want to charge money upfront and save payment details for next time all in one go.