--- title: "Sessions" description: "A **Session** is a hosted checkout experience that walks a customer through selecting a payment method and completing a payment." url: "https://docs.komoju.com/en/api-reference#2025-01-28/tag/sessions" source_url: "https://docs.komoju.com/en/api-reference/2025-01-28/resources/sessions.md" language: en api_version: "2025-01-28" --- # Sessions A **Session** is a hosted checkout experience that walks a customer through selecting a payment method and completing a payment. Redirect your customer to the session's `session_url` and KOMOJU handles the UI, method selection, and 3-D Secure flows for you; on completion a Payment is created and linked back to the session. Sessions are the recommended integration path for most merchants — they keep PCI scope minimal and unlock every payment method KOMOJU supports with no additional integration work. ## The Session object A **Session** is a hosted checkout experience: redirect the customer to `session_url` and KOMOJU walks them through payment method selection, 3-D Secure, and final confirmation. When the customer completes the flow, a `Payment` is created and linked back to the session. Sessions are the recommended integration path for most merchants because they unlock every supported payment method with no additional client-side work and keep PCI scope minimal. ### Attributes - **`id`** *string (UUID)* *required* A unique 25-character alphanumeric resource identifier. - **`resource`** *string enum* *required* Resource type name, always "session". - **`mode`** *string (SessionMode)* *required* Specifies what to do with the payment details. Can create a payment, or a customer resource. - **`amount`** *integer (Amount)* *required* Amount greater than or equal to 0, in the lowest denomination of the currency (e.g. cents for USD). - **`currency`** *string (Currency)* *required* 3-letter ISO currency code. - **`session_url`** *string* *required* URL to redirect the customer to for completing the session. - **`return_url`** *string or null* *required* URL the customer is redirected to after completing or cancelling the session. - **`default_locale`** *string (Locale) or null* *required* For supported payment methods, sets the language of the instruction page. - **`payment_methods`** *array of PaymentMethod object* *required* List of payment methods available for this session. - **`created_at`** *string* *required* Timestamp when the session was created. - **`cancelled_at`** *string or null* *required* Timestamp when the session was cancelled, or null if not cancelled. - **`completed_at`** *string or null* *required* Timestamp when the session was completed, or null if not completed. - **`status`** *string (SessionStatus)* *required* - **`expired`** *boolean* *required* Whether the session has expired. - **`merchant`** *MerchantData object* *required* - **`metadata`** *object* *required* Arbitrary key-value metadata attached to this session at creation time. - **`payment`** *The Payment object object or null* A **Payment** represents a single charge against a customer for a specific amount in a specific currency. Payments are the primary way money is moved through KOMOJU — every accepted charge, whether initiated directly through the API or via a hosted `Session`, results in a `Payment` object. A payment moves through a series of statuses (`pending`, `authorized`, `captured`, `cancelled`, `expired`, `refunded`, `failed`) as the customer completes the flow and funds are captured or refunded. - **`payment_data`** *PaymentData object* - **`customer_id`** *string* Subscription customer UUID. Only present when mode includes "customer". - **`secure_token`** *The Secure Token object object* A **Secure Token** is a 3-D Secure–authenticated token that carries the outcome of a strong customer authentication challenge. Use secure tokens whenever the card, issuer, or regulation requires 3DS — the token records the challenge result and can then be used to create an authorized payment. - **`line_items`** *array of LineItem object* Line items for this session. Only present when line items were provided on create. - **`merchant_id`** *string* Merchant UUID. Only present for Platform Model seller merchants. - **`email`** *string* Customer email. Only present when an email was provided. ### Example ```json { "id": "string", "resource": "session", "mode": "payment", "amount": 0, "currency": "JPY", "session_url": "https://komoju.com/en/sessions/9f4bd8ac02d24abf9f4e", "return_url": "string", "default_locale": "ja", "payment_methods": [ { "type": "string", "hashed_gateway": "string", "amount": 0, "currency": "JPY", "exchange_rate": 0, "offsite": true, "additional_fields": [ "string" ], "brands": [ "string" ], "seven_eleven_merchant_number": "string", "installments": [ { "amount": 0, "pay_at": "string" } ], "api_endpoint": "string" } ], "created_at": "2025-01-15T10:10:00Z", "cancelled_at": "2024-01-01T00:00:00Z", "completed_at": "2024-01-01T00:00:00Z", "status": "pending", "expired": false, "merchant": { "name": "string" }, "metadata": {}, "payment": { "id": "pay3fj6nnhvws08idzacf6et8", "resource": "payment", "status": "captured", "amount": 1000, "tax": 0, "customer": "string", "payment_deadline": "2024-01-01T00:00:00Z", "payment_details": { "type": "credit_card", "brand": "string", "last_four_digits": "string", "month": 10, "year": 2031, "email": "example@komoju.com", "verification_value": "Approved", "name": "John Doe", "given_name": "John", "family_name": "Doe", "expiry_days": 0, "intent": "one_time", "initiator": "merchant", "usage": "first", "scheme_reference": "string", "installments": "3", "shipping_address_name": "Taro Tanaka", "shipping_address_line1": "5-2-1 Ginza", "shipping_address_line2": "3rd floor", "shipping_address_city": "Chuo-ku", "shipping_address_state": "Tokyo", "shipping_address_zip": "170-3293", "shipping_address_country": "Japan", "billing_address_name": "Taro Tanaka", "billing_address_line1": "5-2-1 Ginza", "billing_address_line2": "3rd floor", "billing_address_city": "Chuo-ku", "billing_address_state": "Tokyo", "billing_address_zip": "170-3293", "billing_address_country": "Japan" }, "payment_method_fee": 0, "total": 0, "currency": "JPY", "description": "string", "captured_at": "2024-01-01T00:00:00Z", "external_order_num": "string", "metadata": {}, "created_at": "2025-01-15T10:10:00Z", "amount_refunded": 0, "locale": "ja", "session": "string", "customer_family_name": "string", "customer_given_name": "string", "mcc": "string", "statement_descriptor": { "statement_descriptor": "株式会社KOMOJU", "statement_descriptor_alpha": "KOMOJU", "statement_descriptor_kana": "コモジュ", "statement_city": "Tokyo", "contact_phone": "0312345678" }, "platform_details": { "submerchants": [ { "submerchant_id": "submerc1od2nc89s6u5hh6x4g", "amount": 900, "platform_fee": 100 } ], "processing_merchant_id": "string" }, "refunds": [ { "id": "ref442o1crn4qn3a3c7gspfik", "resource": "refund", "amount": 1000, "currency": "JPY", "payment": "pay3fj6nnhvws08idzacf6et8", "description": "Full refund", "created_at": "2024-01-01T00:00:00Z", "chargeback": false, "refund_type": "string", "platform_details": { "submerchants": [ { "submerchant_id": "submerc1od2nc89s6u5hh6x4g", "amount": 900, "platform_fee": 100 } ], "processing_merchant_id": "string" } } ], "refund_requests": [ { "id": "refreqlv6wny1ew1a1aq4zum1", "payment": "pay3fj6nnhvws08idzacf6et8", "customer_name": "ｻｲﾄｳ ﾏｻﾋﾛ", "bank_name": "サンプル銀行", "bank_code": "0900", "branch_name": "本店", "branch_number": "100", "account_number": "1234567", "description": "string", "status": "completed", "created_at": "2024-01-01T00:00:00Z", "platform_details": { "submerchants": [ { "submerchant_id": "submerc1od2nc89s6u5hh6x4g", "amount": 900, "platform_fee": 100 } ], "processing_merchant_id": "string" } } ] }, "payment_data": { "capture": "auto", "external_order_num": "string", "name": "string", "name_kana": "string", "platform_details": { "submerchants": [ { "submerchant_id": "submerc1od2nc89s6u5hh6x4g", "amount": 900, "platform_fee": 100 } ], "processing_merchant_id": "string" } }, "customer_id": "string", "secure_token": { "id": "string", "created_at": "2025-01-15T10:10:00Z", "verification_status": "OK", "authentication_url": "string", "three_d_secure_account": { "acquirer_mid": "string", "acquirer_bin": "string" }, "three_ds_auth_result": { "dsReferenceNumber": "string", "acsReferenceNumber": "string", "threeDSRequestorTransID": "string", "acsTransID": "string", "dsTransID": "string", "eci": "string", "messageVersion": "string", "authenticationType": "string", "authenticationValue": "string", "transStatus": "string", "threeDSServerTransID": "string" } }, "line_items": [ { "amount": 0, "description": "string", "quantity": 0, "image": "string", "external_product_num": "string" } ], "merchant_id": "string", "email": "string" } ``` ## Endpoints ### Session: Show - [GET /sessions/{id}](https://docs.komoju.com/en/api-reference/2025-01-28/show-session.md) ### Session: Create - [POST /sessions](https://docs.komoju.com/en/api-reference/2025-01-28/create-session.md) ### Session: Cancel - [POST /sessions/{id}/cancel](https://docs.komoju.com/en/api-reference/2025-01-28/cancel-session.md) ### Session: Pay - [POST /sessions/{id}/pay](https://docs.komoju.com/en/api-reference/2025-01-28/pay-session.md)