Sign in

v1

latestOpenAPI 3.0.22026-07-2667277423.4 KB
Sessions

Session: Create

Creates a session. There're 3 modes for the session:

  • payment: A payment will be created after user completed the session (default).
  • customer: A customer will be created instead of a payment, or updated if customer_id is given. This customer resource can then be used to perform delayed billing or subscriptions.
  • customer_payment: A payment will be created, and customer will be created or updated. You can use this mode to charge money upfront and save customer's payment details in one go.
post/sessions

Request body

OR
OR

Example request

{
  "amount": 1000,
  "return_url": "https://example.com/order/complete",
  "currency": "JPY",
  "email": "john@example.com",
  "expires_in_seconds": 86400,
  "external_customer_id": "12345",
  "payment_data": {
    "currency": "JPY",
    "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
        }
      ]
    },
    "billing_address": {
      "name": "Taro Tanaka",
      "street_address1": "5-2-1 Ginza",
      "street_address2": "3rd floor",
      "city": "Chuo-ku",
      "state": "Tokyo",
      "zipcode": "170-3293",
      "country": "Japan"
    },
    "shipping_address": {
      "name": "Taro Tanaka",
      "street_address1": "5-2-1 Ginza",
      "street_address2": "3rd floor",
      "city": "Chuo-ku",
      "state": "Tokyo",
      "zipcode": "170-3293",
      "country": "Japan"
    }
  }
}

Response

200 response

idstring required

A unique 25-character alphanumeric resource identifier.

resource'session' required

Resource type name, always "session".

mode'payment' | 'customer' | 'customer_payment' required

Specifies what to do with the payment details. Can create a payment, or a customer resource.

amountinteger required

Amount greater than or equal to 0, in the lowest denomination of the currency (e.g. cents for USD).

currency'JPY' | 'USD' | 'EUR' | 'TWD' | 'KRW' | 'PLN' | 'GBP' | 'HKD' | 'SGD' | 'NZD' | 'AUD' | 'IDR' | 'MYR' | 'PHP' | 'THB' | 'CNY' | 'BRL' | 'CHF' | 'CAD' | 'VND' required

3-letter ISO currency code.

session_urlstring required

URL to redirect the customer to for completing the session.

return_urlstring nullable required

URL the customer is redirected to after completing or cancelling the session.

default_locale'ja' | 'en' | 'ko' required

For supported payment methods, sets the language of the instruction page.

created_atstring date-time required

Timestamp when the session was created.

cancelled_atstring date-time nullable required

Timestamp when the session was cancelled, or null if not cancelled.

completed_atstring date-time nullable required

Timestamp when the session was completed, or null if not completed.

status'pending' | 'completed' | 'cancelled' required
expiredboolean required

Whether the session has expired.

metadataobject required

Arbitrary key-value metadata attached to this session at creation time.

customer_idstring

Subscription customer UUID. Only present when mode includes "customer".

merchant_idstring

Merchant UUID. Only present for Platform Model seller merchants.

emailstring

Customer email. Only present when an email was provided.

Example response

{
  "currency": "JPY",
  "payment_methods": [
    {
      "currency": "JPY"
    }
  ],
  "payment": {
    "id": "pay3fj6nnhvws08idzacf6et8",
    "status": "captured",
    "amount": 1000,
    "payment_details": {
      "month": 10,
      "year": 2031,
      "email": "example@komoju.com",
      "name": "John Doe",
      "given_name": "John",
      "family_name": "Doe",
      "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"
    },
    "currency": "JPY",
    "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
        }
      ]
    },
    "refunds": [
      {
        "id": "ref442o1crn4qn3a3c7gspfik",
        "amount": 1000,
        "currency": "JPY",
        "payment": "pay3fj6nnhvws08idzacf6et8",
        "description": "Full refund",
        "platform_details": {
          "submerchants": [
            {
              "submerchant_id": "submerc1od2nc89s6u5hh6x4g",
              "amount": 900,
              "platform_fee": 100
            }
          ]
        }
      }
    ],
    "refund_requests": [
      {
        "id": "refreqlv6wny1ew1a1aq4zum1",
        "payment": "pay3fj6nnhvws08idzacf6et8",
        "customer_name": "ｻｲﾄｳ ﾏｻﾋﾛ",
        "bank_name": "サンプル銀行",
        "bank_code": "0900",
        "branch_name": "本店",
        "branch_number": "100",
        "account_number": "1234567",
        "status": "completed",
        "platform_details": {
          "submerchants": [
            {
              "submerchant_id": "submerc1od2nc89s6u5hh6x4g",
              "amount": 900,
              "platform_fee": 100
            }
          ]
        }
      }
    ]
  },
  "payment_data": {
    "platform_details": {
      "submerchants": [
        {
          "submerchant_id": "submerc1od2nc89s6u5hh6x4g",
          "amount": 900,
          "platform_fee": 100
        }
      ]
    }
  }
}