--- 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#2024-07-15/tag/payments" source_url: "https://docs.komoju.com/en/api-reference/2024-07-15/resources/payments.md" language: en api_version: "2024-07-15" --- # 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. ### 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* *required* Customer UUID if associated with a customer, otherwise null. - **`payment_deadline`** *string or null* *required* Deadline by which the payment must be completed, or null. - **`payment_details`** *ResponsePaymentDetailsAll object* *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 description for this payment. May be null if it's not set. - **`captured_at`** *string* *required* Timestamp when the payment was captured, or null if not yet captured. - **`external_order_num`** *string* *required* Merchant-assigned external order number for this payment. - **`metadata`** *object* *required* Arbitrary key-value metadata attached at payment creation time. - **`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)* *required* For supported payment methods, sets the language of the instruction page. - **`session`** *string (UUID)* *required* A unique 25-character alphanumeric resource identifier. - **`customer_family_name`** *string* *required* Customer's family name. - **`customer_given_name`** *string* *required* Customer's given name. - **`mcc`** *string* *required* Merchant Category Code used for this payment. - **`statement_descriptor`** *string* *required* Statement descriptor shown on the customer's bank statement. - **`refunds`** *array of Refund object* *required* An array of refunds. Will be an empty array if there are no refunds. - **`refund_requests`** *array of RefundRequest object* *required* An array of refund requests. Will be an empty array 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": "string", "refunds": [ { "id": "ref442o1crn4qn3a3c7gspfik", "resource": "refund", "amount": 1000, "currency": "JPY", "payment": "pay3fj6nnhvws08idzacf6et8", "description": "Full refund", "created_at": "2024-01-01T00:00:00Z", "chargeback": false, "platform_details": { "submerchants": [ { "submerchant_id": "submerc1od2nc89s6u5hh6x4g", "amount": 900, "platform_fee": 100 } ] } } ], "refund_requests": [ { "id": "refreqlv6wny1ew1a1aq4zum1", "payment": "pay3fj6nnhvws08idzacf6et8", "customer_name": "ｻｲﾄｳ ﾏｻﾋﾛ", "bank_name": "サンプル銀行", "bank_code": "string", "branch_name": "本店", "branch_number": "100", "account_number": "1234567", "status": "completed", "created_at": "2024-01-01T00:00:00Z", "platform_details": { "submerchants": [ { "submerchant_id": "submerc1od2nc89s6u5hh6x4g", "amount": 900, "platform_fee": 100 } ] } } ] } ``` ## Endpoints ### Payment: List - [GET /payments](https://docs.komoju.com/en/api-reference/2024-07-15/list-payments.md) ### Payment: Create - [POST /payments](https://docs.komoju.com/en/api-reference/2024-07-15/create-payment.md) ### Payment: Show - [GET /payments/{id}](https://docs.komoju.com/en/api-reference/2024-07-15/show-payment.md) ### Payment: Update - [PATCH /payments/{id}](https://docs.komoju.com/en/api-reference/2024-07-15/update-payment.md) ### Payment: Capture - [POST /payments/{id}/capture](https://docs.komoju.com/en/api-reference/2024-07-15/capture-payment.md) ### Payment: Refund - [POST /payments/{id}/refund](https://docs.komoju.com/en/api-reference/2024-07-15/refund-payment.md) ### Payment: Cancel - [POST /payments/{id}/cancel](https://docs.komoju.com/en/api-reference/2024-07-15/cancel-payment.md) ### Payment: Finalize - [POST /payments/{id}/finalize](https://docs.komoju.com/en/api-reference/2024-07-15/finalize-payment.md) ### Payment: Refund Request - [POST /payments/{id}/refund_request](https://docs.komoju.com/en/api-reference/2024-07-15/create-refund-request.md) ### Payment Method: List - [GET /payment_methods](https://docs.komoju.com/en/api-reference/2024-07-15/list-payment-methods.md)