Sign in

v1

latestOpenAPI 3.0.22026-07-2667277423.4 KB
Payments

Payment: Create

Creates a payment for a given amount and currency.

There are two ways to create payment:

  • For one-time payment, you can pass payment_details with payment method type and additional attributes.
  • For recurring payment, you can pass customer's ID via customer attribute. Customer's saved payment method will be used for the payment.

Note that either payment_details or customer is required for the payment. However, both of them should not be given at the same time.

post/payments

Request body

OR

Example request

{
  "amount": 1000,
  "description": "Payment description",
  "currency": "JPY",
  "external_order_num": "ORDER-12345",
  "return_url": "https://example.com/order/complete",
  "cancel_url": "https://example.com/cart",
  "mcc": "5799",
  "statement_descriptor": {
    "statement_descriptor": "株式会社KOMOJU",
    "statement_descriptor_alpha": "KOMOJU",
    "statement_descriptor_kana": "コモジュ",
    "statement_city": "Tokyo",
    "contact_phone": "0312345678"
  },
  "fraud_details": {
    "customer_ip": "::1",
    "customer_email": "john@example.com",
    "customer_id": "123",
    "browser_language": "ja-JP",
    "browser_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0",
    "browser_session_id": "abc1234",
    "phone": "07012345678"
  },
  "platform_details": {
    "submerchants": [
      {
        "submerchant_id": "submerc1od2nc89s6u5hh6x4g",
        "amount": 900,
        "platform_fee": 100
      }
    ]
  },
  "payment_details": {
    "email": "example@komoju.com",
    "number": "4111111111111111",
    "month": 10,
    "year": 2031,
    "verification_value": "000",
    "name": "John Doe",
    "given_name": "John",
    "family_name": "Doe",
    "expiry_days": 2,
    "scheme_reference": "SUBSCRIPTION-1234",
    "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"
  }
}

Response

Payment successfully created

idstring required

A unique 25-character alphanumeric payment identifier.

resource'payment' required

Resource name. Will always be payment.

status'pending' | 'authorized' | 'captured' | 'cancelled' | 'expired' | 'refunded' | 'failed' required
amountinteger required

The payment amount before tax, greater than or equal to 0, in the lowest denomination of the currency (e.g. cents for USD).

taxinteger required

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

customerstring nullable required

Customer UUID if associated with a customer, otherwise null.

payment_deadlinestring date-time nullable required

Deadline by which the payment must be completed, or null.

payment_method_feeinteger required

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

totalinteger 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.

descriptionstring nullable required

A description for this payment. May be null if it's not set.

captured_atstring date-time nullable required

Timestamp when the payment was captured, or null if not yet captured.

external_order_numstring nullable required

Merchant-assigned external order number for this payment.

metadataobject required

Arbitrary key-value metadata attached at payment creation time.

created_atstring date-time required

Timestamp when the payment was created.

amount_refundedinteger required

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

locale'ja' | 'en' | 'ko' required

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

sessionstring required

A unique 25-character alphanumeric resource identifier.

customer_family_namestring nullable required

Customer's family name.

customer_given_namestring nullable required

Customer's given name.

mccstring nullable required

Merchant Category Code used for this payment.

Example response

{
  "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
          }
        ]
      }
    }
  ]
}