--- title: "Payments" description: "A **Payment** represents a single charge against a customer for a specific amount in a specific currency." url: "https://docs.komoju.com/en/api-reference#2025-01-28/tag/payments" source_url: "https://docs.komoju.com/en/api-reference/2025-01-28/resources/payments.md" language: en api_version: "2025-01-28" --- # Payments A **Payment** represents a single charge against a customer for a specific amount in a specific currency. Payments are the primary resource for accepting money through KOMOJU: you create one either directly, or as the result of a customer completing a hosted [Session](#tag/Sessions). Every payment moves through a set of statuses (`pending`, `authorized`, `captured`, `cancelled`, `expired`, `refunded`, `failed`) as the customer completes the flow and, where applicable, funds are captured or refunded. ## The Payment object 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. ### Attributes - **`id`** *string (PaymentUUID)* *required* A unique 25-character alphanumeric payment identifier. - **`resource`** *string enum* *required* Resource name. Will always be `payment`. - **`status`** *string (PaymentStatus)* *required* - **`amount`** *integer (PaymentAmount)* *required* The payment amount before tax, greater than or equal to 0, in the lowest denomination of the currency (e.g. cents for USD). - **`tax`** *integer (Tax amount)* *required* The tax amount, greater than or equal to 0, in the lowest denomination of the currency (e.g. cents for USD). - **`customer`** *string or null* *required* Customer UUID if this payment is associated with a stored customer, otherwise `null`. - **`payment_deadline`** *string or null* *required* Deadline by which the payment must be completed, or `null` if the payment method does not have an expiry. - **`payment_details`** *ResponsePaymentDetailsAll object or null* *required* Specific payment details and attributes for each payment type. It may include payment method specific attributes that are not part of the original request. - **`payment_method_fee`** *integer (Amount)* *required* Amount greater than or equal to 0, in the lowest denomination of the currency (e.g. cents for USD). - **`total`** *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. - **`description`** *string or null* *required* A free-form description for this payment. May be `null` if the merchant did not set one when creating the payment. - **`captured_at`** *string or null* *required* Timestamp when the payment was captured, or `null` if not yet captured. - **`external_order_num`** *string or null* *required* A unique ID from your application used to track this payment (for example your internal order number). `null` if not set at creation time. - **`metadata`** *object* *required* Arbitrary key-value metadata attached to this payment at creation time. Values must be strings. - **`created_at`** *string* *required* Timestamp when the payment was created. - **`amount_refunded`** *integer (Amount)* *required* Amount greater than or equal to 0, in the lowest denomination of the currency (e.g. cents for USD). - **`locale`** *string (Locale) or null* *required* For supported payment methods, sets the language of the instruction page. - **`session`** *string (UUID) or null* *required* A unique 25-character alphanumeric resource identifier. - **`customer_family_name`** *string or null* *required* Customer's family name, if provided. `null` otherwise. - **`customer_given_name`** *string or null* *required* Customer's given name, if provided. `null` otherwise. - **`mcc`** *string or null* *required* Merchant Category Code used for this payment (a 4-digit ISO 18245 code), or `null` if the default MCC applies. - **`statement_descriptor`** *Statement Descriptor object or null* *required* On supported merchant and supported payment methods, specify a custom statement descriptor for this payment. This helps customer to identify the payment on their statement. See [Dynamic Statement Descriptors & MCCs](https://doc.komoju.com/docs/payments-with-dynamic-statement-descriptors) for more information. - **`platform_details`** *PlatformDetails object* - **`refunds`** *array of Refund object* *required* An array of refunds. Empty if there are no refunds. - **`refund_requests`** *array of RefundRequest object* *required* An array of refund requests. Empty if there are no refund requests. ### Example ```json { "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" } } ] } ``` ## Endpoints ### Payment: List - [GET /payments](https://docs.komoju.com/en/api-reference/2025-01-28/list-payments.md) ### Payment: Create - [POST /payments](https://docs.komoju.com/en/api-reference/2025-01-28/create-payment.md) ### Payment: Show - [GET /payments/{id}](https://docs.komoju.com/en/api-reference/2025-01-28/show-payment.md) ### Payment: Update - [PATCH /payments/{id}](https://docs.komoju.com/en/api-reference/2025-01-28/update-payment.md) ### Payment: Capture - [POST /payments/{id}/capture](https://docs.komoju.com/en/api-reference/2025-01-28/capture-payment.md) ### Payment: Refund - [POST /payments/{id}/refund](https://docs.komoju.com/en/api-reference/2025-01-28/refund-payment.md) ### Payment: Cancel - [POST /payments/{id}/cancel](https://docs.komoju.com/en/api-reference/2025-01-28/cancel-payment.md) ### Payment: Finalize - [POST /payments/{id}/finalize](https://docs.komoju.com/en/api-reference/2025-01-28/finalize-payment.md) ### Payment: Refund Request - [POST /payments/{id}/refund_request](https://docs.komoju.com/en/api-reference/2025-01-28/create-refund-request.md) ### Payment Method: List - [GET /payment_methods](https://docs.komoju.com/en/api-reference/2025-01-28/list-payment-methods.md)